Primeira requisição

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) 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:

export API=https://needalert.app/api/v1
export TOKEN='3|na_...'

Descubra as unidades da chave

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):

{
  "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).

Encontre o item pela sua referência

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

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:

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):

{
  "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
  }
}

Estime o custo

curl "$API/establishments/12/items/42/dispatch-preview" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Accept: application/json"

{
  "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.

Dispare o alerta

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).A resposta 201 traz o disparo em pending (ou scheduled, se agendado; dispatched quando ninguém estava inscrito):

{
  "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" }
  }
}

Acompanhe o resultado

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

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; cada endpoint está detalhado no grupo Endpoints desta aba.

Introdução

Guias

Convenções

Endpoints

Primeira requisição

Se o disparo for recusado

​Se o disparo for recusado

Se o disparo for recusado