# Ative Aqui — API de Players v1

Documentação canônica: https://ativeaqui.com/docs/players/
OpenAPI 3.1: https://ativeaqui.com/docs/players-openapi.yaml
Base URL: https://ativeaqui.com/api/v1/players
Gestão de chaves: https://ativeaqui.com/painel/api/

## Acesso

A API é parte da assinatura ativa do Módulo de Players. Planos pagos e o teste grátis válido usam a abertura global; quando o teste vence, as chaves param. Contas de cortesia dependem de liberação individual pelo administrador. Uma conta pode ter até três chaves ativas. A chave é mostrada só na criação; armazene-a com segurança. A autenticação usa `Authorization: Bearer SUA_CHAVE`, nunca parâmetro de URL. Cada chave tem escopos e validade próprios; IPs permitidos são opcionais.

Escopos: `devices:read`, `devices:write`, `devices:sync`, `playlists:read`, `playlists:write`, `dns:write`, `operations:read`. Peça somente os necessários. Uma chave revogada deixa de autenticar e cancela operações ainda na fila. Uma operação já em envio não pode ser desfeita por revogação.

## Primeira chamada

```sh
curl --request GET 'https://ativeaqui.com/api/v1/players/me' \
  --header 'Authorization: Bearer SUA_CHAVE'
```

`GET /me` informa acesso, assinatura, plano, validade, limite de aparelhos, cota remota diária e unidades usadas. `GET /brands` lista as marcas disponíveis. `GET /devices` lista somente aparelhos da conta, com paginação (`page`, `per_page` até 100) e filtros `brand`, `search`, `expires_before` e `has_error`. Identificadores de aparelhos e playlists retornados pela API são usados nas rotas seguintes. Dados de outra conta retornam 404.

## Operações e segurança

Toda mutação, exceto `POST /dns/preview`, exige cabeçalho `Idempotency-Key` aleatório de 16 a 80 caracteres. Gere uma chave nova para cada alteração. A mesma chave com método, caminho e corpo idênticos devolve a resposta original por 30 dias; conteúdo diferente retorna 409. Não reutilize uma chave para uma alteração diferente.

Escritas remotas e consultas ao aplicativo retornam 202 com `data.operation_id` e `data.status_url`. Consulte `GET /operations/{operation_id}` a cada 5 segundos até `succeeded`, `failed` ou `review`. Respeite `Retry-After` em respostas 429. `review` indica escrita possivelmente efetuada; confira o app e solicite conciliação administrativa. Não repita automaticamente a escrita. Enquanto uma escrita estiver em `queued`, `sending` ou `review`, outra escrita no mesmo aparelho recebe 409 `device_busy`. Lotes param na primeira falha incerta.

Exemplo de leitura remota de um aparelho, que não altera playlists:

```sh
curl --request POST 'https://ativeaqui.com/api/v1/players/devices/123/sync' \
  --header 'Authorization: Bearer SUA_CHAVE' \
  --header 'Idempotency-Key: UUID_UNICA_PARA_ESTA_OPERACAO'
```

Não envie dados reais de aparelhos sem autorização. URLs completas de playlists, senhas e device keys não aparecem em respostas de leitura. Nunca as registre em logs ou prompts. O Swagger em https://ativeaqui.com/docs/players/ pode executar escritas reais com a chave inserida pelo usuário.

## Endpoints

| Método | Caminho | Escopo | Efeito |
| --- | --- | --- | --- |
| GET | `/me` | chave válida | Estado do acesso e cotas |
| GET | `/brands` | `devices:read` | Marcas disponíveis |
| GET | `/devices` | `devices:read` | Aparelhos da conta |
| GET | `/devices/{device}` | `devices:read` | Um aparelho |
| POST | `/devices` | `devices:write` | Cadastra aparelho localmente |
| PATCH | `/devices/{device}` | `devices:write` | Altera identificação ou device key local |
| DELETE | `/devices/{device}` | `devices:write` | Remove só o cadastro local |
| POST | `/devices/{device}/sync` | `devices:sync` | Confere o aplicativo em fila |
| GET | `/devices/{device}/playlists` | `playlists:read` | Última foto local das listas |
| POST | `/devices/{device}/playlists` | `playlists:write` | Envia lista ao aplicativo em fila |
| PATCH | `/devices/{device}/playlists/{playlist}` | `playlists:write` | Edita lista no aplicativo em fila |
| DELETE | `/devices/{device}/playlists/{playlist}` | `playlists:write` | Apaga lista no aplicativo em fila |
| POST | `/dns/preview` | `devices:read` | Prévia local de troca de DNS, válida por 5 minutos |
| POST | `/dns/operations` | `dns:write` | Troca DNS de até 50 aparelhos selecionados |
| POST | `/sync/operations` | `devices:sync` | Confere até 50 aparelhos em lote |
| GET | `/operations` | `operations:read` | Operações paginadas |
| GET | `/operations/{operation}` | `operations:read` | Estado e itens da operação |

`POST /devices` recebe `brand`, `mac`, e opcionalmente `device_key`, `label`, `notes`. `POST /devices/{device}/playlists` recebe `name` e `url` HTTP/HTTPS completa, ou `name`, `dns`, `username`, `password` e `output` (`ts` ou `m3u8`). `PATCH` recebe os campos que deseja alterar. Para trocar DNS em lote, gere uma prévia e envie apenas IDs devolvidos por ela com o `preview_id` válido. Consulte o OpenAPI para tipos, limites e modelos exatos.

## Limites e erros

Cada chave tem limite de 20 chamadas por minuto. A conta tem 60 por minuto por padrão (ajustável pelo administrador), até 10 escritas por minuto e uma cota diária de operações remotas. Consultar snapshots locais não gasta cota remota. Uma resposta de erro inclui `error.code`, `error.message` e `request_id`. Códigos comuns: 401 `invalid_token`, 403 para acesso ou escopo insuficiente, 404 para recurso ausente ou de outra conta, 409 para conflito ou aparelho ocupado, 422 para entrada inválida e 429 para limites. Nenhum cliente deve repetir automaticamente uma escrita remota após timeout ou resultado incerto.