> ## 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.

# Primeira requisição

> Do zero a um alerta disparado pela API, em cinco chamadas.

Este guia leva o seu sistema de uma chave recém-criada até um alerta disparado e confirmado. Você precisa de um token (veja [Autenticação](https://docs.needalert.app/api/authentication.md)) e de uma unidade com pelo menos um inscrito, para o alerta chegar a alguém.

Nos exemplos, `$API` é o endereço da API e `$TOKEN` o token da chave:

```bash theme={null}
export API=https://needalert.app/api/v1
export TOKEN='3|na_...'
```

**1. Descubra as unidades da chave**

```bash theme={null}
curl "$API/establishments" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Accept: application/json"
```

A resposta lista só as unidades que a chave alcança, com as permissões dela em cada uma (resumida):

```json theme={null}
{
  "data": [
    {
      "id": 12,
      "tenant_id": 7,
      "name": "Bom Pão — Unidade Centro",
      "slug": "bom-pao-centro",
      "status": "active",
      "permissions": ["view", "create_items", "edit_items", "dispatch_events"]
    }
  ]
}
```

Guarde o `id` da unidade (`12`) e o `tenant_id` da rede (`7`).

**2. Encontre o item pela sua referência**

Procure o item pelo código do seu sistema, em `external_reference` (comparação exata):

```bash theme={null}
curl "$API/establishments/12/items?external_reference=SKU-123" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Accept: application/json"
```

Se `data` vier vazio, crie o item. `translations` leva o bloco do idioma padrão da rede (`pt_BR` ou `en`), com `name` obrigatório:

```bash theme={null}
curl -X POST "$API/establishments/12/items" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: 5c1b2a9e-6f0d-4c3e-9a7b-1d2e3f4a5b6c" \
  -d '{
    "queue_type": "single",
    "external_reference": "SKU-123",
    "translations": {
      "pt_BR": { "name": "Pão de queijo", "description": "Saído do forno" }
    }
  }'
```

`queue_type` define o tipo de aviso: `single` para **aviso único** (a inscrição encerra no primeiro alerta) ou `recurring` para **aviso recorrente** (a inscrição continua e recebe todos os alertas). A resposta **201** traz o item (resumida):

```json theme={null}
{
  "data": {
    "id": 42,
    "establishment_id": 12,
    "public_code": "K7Q2M",
    "external_reference": "SKU-123",
    "name": "Pão de queijo",
    "queue_type": "single",
    "status": "active",
    "subscribers_count": 0
  }
}
```

**3. Estime o custo**

```bash theme={null}
curl "$API/establishments/12/items/42/dispatch-preview" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Accept: application/json"
```

```json theme={null}
{
  "data": {
    "recipients_count": 38,
    "credits_cost": 38,
    "current_balance": 950,
    "sufficient": true,
    "schedule": {
      "min_lead_minutes": 10,
      "max_lead_days": 90,
      "warning_lead_minutes": 120
    }
  }
}
```

Um crédito por pessoa avisada. Se `sufficient` for `false`, o disparo seria recusado com `insufficient_credits`.

**4. Dispare o alerta**

```bash theme={null}
curl -X POST "$API/establishments/12/items/42/events" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: 9f8e7d6c-5b4a-4c3d-8e2f-1a0b9c8d7e6f" \
  -d '{ "message": "Pão de queijo quentinho saindo agora!" }'
```

`message` tem até 200 caracteres; `title` (até 120) é opcional. Para agendar, acrescente `scheduled_at` em ISO 8601 UTC, dentro da janela `schedule` do passo anterior. Envie sempre um `Idempotency-Key` novo por disparo pretendido: se a conexão cair e você repetir a chamada com a mesma chave, o alerta não sai duas vezes (veja [Idempotência](https://docs.needalert.app/api/idempotency.md)).

A resposta **201** traz o disparo em `pending` (ou `scheduled`, se agendado; `dispatched` quando ninguém estava inscrito):

```json theme={null}
{
  "data": {
    "id": 9001,
    "item": { "id": 42, "public_code": "K7Q2M", "name": "Pão de queijo" },
    "message": "Pão de queijo quentinho saindo agora!",
    "status": "pending",
    "recipients_count": 38,
    "credits_cost": 38,
    "created_by": null,
    "created_by_api_client": { "id": 3, "name": "ERP Loja Centro" }
  }
}
```

**5. Acompanhe o resultado**

O envio acontece em segundo plano. Consulte o disparo até `status` sair de `pending` ou `processing`:

```bash theme={null}
curl "$API/establishments/12/events/9001" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Accept: application/json"
```

`dispatched`: enviado; `sent_count` e `failed_count` detalham as entregas e os créditos foram debitados. `failed`: não enviado; `failure_reason` diz por quê (por exemplo, `insufficient_credits` no momento do envio). `scheduled`: aguardando `scheduled_at`; pode ser reagendado (`PATCH`) ou cancelado (`DELETE`).

## Se o disparo for recusado

Um disparo pode ser recusado na hora, com **422** e um `code`:

| `code` | Causa | O que fazer |
| - | - | - |
| `insufficient_credits` | `errors.required` créditos necessários, `errors.available` disponíveis. | Comprar créditos no painel e tentar com um `Idempotency-Key` novo. |
| `item_not_dispatchable` | O item não está ativo, ou a unidade ou a rede não estão ativas. | Conferir o `status` do item e da unidade. |
| `dispatch_in_progress` | Já há um disparo deste item em andamento. | Aguardar e consultar o disparo em andamento. |
| `dispatch_too_soon` | O item acabou de ser disparado. | Aguardar alguns segundos e usar um `Idempotency-Key` novo. |
| `schedule_slot_taken` | Já há um disparo agendado deste item no mesmo minuto. | Escolher outro horário. |

A lista completa de códigos está em [Convenções](https://docs.needalert.app/api/conventions.md); cada endpoint está detalhado no grupo **Endpoints** desta aba.


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