# API Aura Farming — Etapa 12

Base: `/api/v1`

No aplicativo mobile, envie `Authorization: Bearer SEU_TOKEN`, `X-Device-ID` e `Content-Type: application/json`. Na interface web, rotas de escrita exigem `X-CSRF-Token`.

## Autenticação e perfil

- `POST /auth/register.php`
- `POST /auth/login.php`
- `POST /auth/logout.php`
- `POST /auth/forgot-password.php`
- `GET|PUT /me/profile.php`
- `POST /me/avatar.php`
- `GET|DELETE /me/devices.php`
- `GET /me/history.php?pagina=1&por_pagina=10`
- `GET|PATCH /notifications/index.php`
- `GET /config.php`

## Progressão e recompensas

- `GET /progression/index.php`
- `POST /progression/claim.php`
- `POST /progression/equip.php`

Resgatar missão:

```json
{"usuario_missao_id": 15}
```

Equipar recompensa:

```json
{"recompensa_id": 8}
```

A resposta de progressão inclui nível, XP atual, sequência, missões, equipamentos, recompensas e histórico recente de XP.

## Partidas

- `POST /matches/start.php`
- `POST /matches/begin.php`
- `POST /matches/heartbeat.php`
- `POST /matches/finish.php`
- `POST /matches/cancel.php`
- `GET /matches/active.php`
- `GET /matches/result.php?s=SESSAO_DE_48_CARACTERES`
- `POST /matches/share.php`

O resultado inclui `xp_ganho`, `xp_base`, `xp_bonus`, `xp_detalhes` e o resumo atual da progressão. IP, fingerprint e identificadores internos do dispositivo não são expostos.

## Rankings

`GET /rankings/index.php?periodo=semanal&escopo=cidade&limite=50&offset=0`

Períodos: `diario`, `semanal`, `mensal`, `global`.

Escopos: `global`, `nacional`, `regional`, `cidade`, `amigos`.

## Rede social

`POST /social/follow.php`

```json
{"aura_id":"AURA-7291","acao":"seguir"}
```

Use `acao: deixar` para deixar de seguir.

## Modo espectador

- `GET /live/search.php?id=AURA-7291`
- `POST /live/state.php?s=TOKEN_PUBLICO`
- `POST /live/interact.php`
- `POST /live/leave.php`
- `POST|GET /live/signal.php`

A transmissão continua P2P. O vídeo não passa pela API nem é armazenado no servidor.


## Combos avançados — Etapa 9
- `GET /api/v1/combos/index.php`: retorna multiplicadores e catálogo de sequências especiais.
- O estado de partida inclui `combo_hits_atual`, `combo_hits_maximo`, `combo_nota`, `combo_ritmo_medio`, `combo_sequencias_concluidas` e `ultima_sequencia_combo`.

## Aura Battle e competições — Etapa 10

### Batalhas
- `GET /battles/index.php`
- `POST /battles/create.php`
- `POST /battles/respond.php`
- `POST /battles/ready.php`
- `GET /battles/state.php?id=10`

Criar duelo:
```json
{"aura_id":"AURA-7291"}
```

Aceitar ou recusar:
```json
{"batalha_id":10,"acao":"aceitar"}
```

Marcar a câmera pronta:
```json
{"sessao_id":"SESSAO_DE_48_CARACTERES"}
```

### Torneios e eventos
- `GET /competitions/index.php`
- `POST /competitions/create.php`
- `POST /competitions/join.php`
- `POST /competitions/start.php`
- `POST /competitions/finish.php`
- `GET /competitions/state.php?id=5`

Criar competição:
```json
{"tipo":"torneio","nome":"Copa Aura","descricao":"Eliminatória","max_participantes":8,"visibilidade":"publico"}
```

Entrar com código:
```json
{"codigo":"AB12CD34"}
```

Iniciar:
```json
{"competicao_id":5}
```

Para criar uma partida de batalha ou evento, `POST /matches/start.php` aceita:
```json
{"fingerprint":"...","batalha_id":10,"modo":"batalha"}
```

ou:
```json
{"fingerprint":"...","competicao_id":5,"modo":"evento"}
```


## Compartilhamento e viralização — Etapa 11

- `POST /viral/challenge.php` — cria ou recupera um desafio para uma partida finalizada.
- `GET /viral/stats.php` — retorna métricas, link pessoal, desafios e resultados compartilháveis.

Criar desafio:
```json
{"partida_id":125,"template":"neon"}
```

`POST /matches/start.php` também aceita `viral_token` quando o usuário aceitou um desafio:
```json
{"fingerprint":"...","modo":"individual","viral_token":"TOKEN_DE_20_CARACTERES"}
```

O resultado e o histórico incluem `replay_url`. Cards PNG e vídeo-resumo são gerados no aparelho; o servidor não armazena a câmera do jogador.

## Segurança e antifraude — Etapa 12

Todos os endpoints autenticados continuam usando Bearer Token. Respostas de rate limit usam HTTP `429`.

- `GET /security/status.php` — resumo da conta, dispositivos, sessões e resultados em revisão.
- `POST /security/report.php` — solicita revisão de uma partida sinalizada.
- `POST /security/admin-review.php` — decisão administrativa; exige conta moderador/admin.

Solicitar revisão:
```json
{"partida_id":125,"mensagem":"A sessão foi realizada normalmente."}
```

Revisão administrativa:
```json
{"partida_id":125,"decisao":"aprovar","observacao":"Movimentos confirmados pela auditoria."}
```

Decisões aceitas: `aprovar`, `rejeitar`, `monitorar` e `suspender`.

O heartbeat da partida aceita `liveness_nonce` e `liveness_passed`. O estado da sessão retorna o desafio ativo quando houver. Vídeo e landmarks completos não são enviados ao backend.


## Etapa 13 — administração

Endpoints administrativos (Bearer token de conta admin/moderador):

- `GET /api/v1/admin/dashboard.php`
- `GET /api/v1/admin/users.php?q=&limit=`
- `GET /api/v1/admin/reports.php`
- `POST /api/v1/admin/notify.php`

Ações sensíveis continuam registradas em `af_admin_logs`. O painel web completo está em `pages/admin.php`.

## Etapa 21 — privacidade e documentos legais

Documentos públicos:
- `GET /privacy/documents.php`

Endpoints autenticados:
- `GET /privacy/status.php`
- `POST /privacy/accept.php`
- `GET|POST|PATCH|DELETE /privacy/requests.php`
- `GET /privacy/export.php?subject_user_id=ID`

Cadastro pela API exige:

```json
{
  "accept_terms": true,
  "accept_privacy": true
}
```

Quando houver uma nova versão obrigatória, endpoints comuns retornam `LEGAL_ACCEPTANCE_REQUIRED`. Os endpoints de privacidade permanecem disponíveis para consulta e aceite.
