> ## Documentation Index
> Fetch the complete documentation index at: https://docs.needalert.app/llms.txt
> Use this file to discover all available pages before exploring further.

# Convenções

> Versão, formato das respostas, erros, paginação, idioma e limites da API.

Estas regras valem para todos os endpoints da API do Need Alert.

## Autenticação

Toda requisição leva uma chave de API no header `Authorization: Bearer <token>` e pede JSON em `Accept: application/json`. Como criar a chave, o que cada 401/403/404 significa e como trocar o token: [Autenticação](https://docs.needalert.app/api/authentication.md).

## Versionamento

Todos os endpoints ficam sob `/api/v1`. Uma mudança que quebre clientes existentes sai numa nova versão (`/api/v2`) e nunca altera a `v1` silenciosamente. Novos campos podem aparecer nas respostas da `v1` a qualquer momento, então seu código deve ignorar campos que não conhece.

## Formato das respostas

Respostas de sucesso trazem o conteúdo dentro de `data`, tanto para um único recurso quanto para uma lista.

```json theme={null}
{
  "data": {
    "id": 42,
    "status": "active"
  }
}
```

Datas e horas estão sempre em **UTC**, no formato ISO 8601 (`2026-10-01T19:00:00+00:00`). Converta para o fuso local só na exibição.

Valores em dinheiro são **inteiros na menor unidade da moeda**, como centavos: `1990` com moeda `BRL` é R\$ 19,90.

## Erros

Todo erro segue o mesmo formato:

```json theme={null}
{
  "message": "Saldo de créditos insuficiente para este disparo.",
  "code": "insufficient_credits",
  "errors": {
    "required": 40,
    "available": 12
  }
}
```

| Campo | Uso |
| - | - |
| `code` | Identificador estável em `snake_case`. **Programe contra ele.** |
| `message` | Texto traduzido, só para exibição. Pode mudar sem aviso. |
| `errors` | Opcional. Em erros de validação, os campos com problema; em erros de regra, dados extras. |

### Códigos gerais

| HTTP | `code` | Quando |
| - | - | - |
| 400 | `bad_request` | Corpo da requisição malformado. |
| 401 | `unauthenticated` | Chave ausente, malformada, expirada ou revogada. |
| 403 | `forbidden` | A chave não tem a permissão que a operação exige nesta unidade. |
| 403 | `tenant_suspended` | A rede dona da chave está suspensa. |
| 403 | `establishment_unavailable` | A unidade está inativa ou suspensa. |
| 404 | `not_found` | O recurso não existe, não pertence a você ou está fora das unidades da chave. |
| 405 | `method_not_allowed` | Método HTTP não aceito nesta rota. |
| 413 | `payload_too_large` | Arquivo ou corpo grande demais. |
| 422 | `validation_failed` | Dados inválidos. Veja `errors`. |
| 429 | `too_many_requests` | Limite de requisições atingido. |
| 500 | `server_error` | Erro inesperado. Tente de novo mais tarde. |
| 503 | `service_unavailable` | Serviço temporariamente indisponível. |

### Códigos de disparo

| HTTP | `code` | Quando |
| - | - | - |
| 422 | `insufficient_credits` | O saldo não cobre o disparo. `errors.required` e `errors.available` trazem os valores. |
| 422 | `item_not_dispatchable` | O item não está ativo, ou a unidade ou a rede estão inativas ou suspensas. |
| 422 | `dispatch_in_progress` | Já existe um disparo deste item em andamento. |
| 422 | `dispatch_too_soon` | O item foi disparado há poucos segundos. |
| 422 | `schedule_slot_taken` | Já existe um disparo agendado deste item no mesmo minuto. |
| 422 | `event_not_scheduled` | Só disparos agendados podem ser reagendados ou cancelados. |

### Códigos de itens e idempotência

| HTTP | `code` | Quando |
| - | - | - |
| 409 | `item_external_reference_taken` | Outro item não arquivado da mesma unidade já usa esta `external_reference`. Veja [Referência externa](https://docs.needalert.app/api/external-reference.md). |
| 422 | `item_archived` | O item está arquivado e não pode ser alterado. |
| 422 | `idempotency_key_reused` | A mesma `Idempotency-Key` foi usada com um corpo diferente. Veja [Idempotência](https://docs.needalert.app/api/idempotency.md). |
| 409 | `idempotency_request_in_progress` | A primeira requisição com esta `Idempotency-Key` ainda está sendo processada. |

> [!NOTE]
>
> Um recurso de outra rede, ou de uma unidade fora da sua chave, responde **404**, não 403. A API não revela se um recurso que não é seu existe.

## Paginação

Listas aceitam `page` e `per_page`. O padrão é 20 itens por página e o máximo é 100.

```http theme={null}
GET /api/v1/establishments/7/items?page=2&per_page=50
```

A resposta traz `data`, `links` (`first`, `last`, `prev`, `next`) e `meta` (`current_page`, `per_page`, `total`, `last_page`).

## Idioma

Com uma chave de API, envie `Accept-Language: pt-BR` ou `Accept-Language: en` para escolher o idioma das mensagens de erro e dos conteúdos traduzidos, como nome e descrição dos itens; sem o header, a chave recebe o idioma padrão da rede. A sessão do painel usa o idioma salvo na conta da pessoa, escolhido no cadastro e alterável nas configurações, mesmo que o header venha diferente. A resposta informa o idioma usado no header `Content-Language`.

## Rastreamento

Toda resposta traz o header `X-Request-Id`. Você também pode enviar o seu. Informe esse valor ao falar com o suporte sobre uma requisição específica.

## Limite de requisições

| Quem | Limite |
| - | - |
| Chave de API | **300 requisições por minuto**, por chave. |
| Chave de API, `POST …/items/{item}/events` | **60 disparos por minuto**, além do limite acima. |
| Sessão do painel | 60 requisições por minuto, por pessoa. |

Ao passar do limite, a resposta é **429** com o header `Retry-After`, que diz quantos segundos esperar. Os headers `X-RateLimit-Limit` e `X-RateLimit-Remaining` mostram o limite e quanto ainda resta. Uma repetição idempotente conta no limite.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.