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

# Casos de uso

> Roteiros de integração: estoque voltou, horário cancelado, itens sincronizados e saldo sob controle.

Quatro integrações típicas, com a sequência de chamadas de cada uma. Todas usam um token de chave de API (veja [Autenticação](https://docs.needalert.app/api/authentication.md)) e os endereços do guia [Primeira requisição](https://docs.needalert.app/api/first-request.md).

## Estoque voltou (ERP)

O ERP da loja sabe quando o estoque de um SKU volta a ficar positivo. Cada SKU que pode esgotar é um item de **aviso único** (`queue_type: single`): quem se inscreveu quer saber uma vez, e a inscrição encerra no alerta.

**1. Ao cadastrar o produto, crie o item**

`POST /establishments/{establishment}/items` com `external_reference` igual ao SKU e `queue_type: single`. Não precisa guardar o `id` do item: a referência é a ponte.

**2. Quando o estoque volta, encontre o item**

`GET …/items?external_reference=<SKU>`. Se `subscribers_count` for `0`, não há ninguém para avisar e você pode parar aqui.

**3. Estime e dispare**

`GET …/items/{item}/dispatch-preview` para saber o custo; `POST …/items/{item}/events` com `message` e um `Idempotency-Key` derivado do evento do ERP (por exemplo, o id do movimento de estoque), para uma reexecução do job não disparar duas vezes.

## Horário cancelado (agenda da clínica)

Cada especialidade com agenda lotada é um item de **aviso único**. Quem quer um encaixe se inscreve pelo QR Code na recepção ou pelo link.

**1. Um item por especialidade**

`external_reference` com o código da especialidade no seu sistema (por exemplo, `ORTO`).

**2. Ao registrar um cancelamento, dispare na hora**

`POST …/items/{item}/events` com a mensagem do horário vago e um `Idempotency-Key` igual ao id do cancelamento. Todos os inscritos recebem ao mesmo tempo; o primeiro a ligar fica com o horário.

**3. Acompanhe**

`GET …/events/{event}` até `dispatched`, para registrar no seu sistema quantas pessoas foram avisadas (`sent_count`).

## Itens sincronizados com a sua lista de produtos (loja virtual)

A loja virtual mantém os itens do Need Alert espelhando os seus produtos, para o botão "avise-me" da página do produto apontar para o item certo.

**1. Sincronize em lote**

Para cada produto, o padrão [procurar, senão criar](https://docs.needalert.app/api/external-reference.md): `GET` pela referência, `PATCH` se existir, `POST` se não. O limite de 300 requisições por minuto por chave comporta sincronizações grandes; respeite `Retry-After` num **429**.

**2. Atualize nome e descrição**

`PATCH …/items/{item}` com `translations` por idioma (`pt_BR`, `en`). O bloco do idioma padrão da rede sempre precisa de `name`.

**3. Descontinuou? Arquive**

`DELETE …/items/{item}`. O item sai do ar, as inscrições encerram e a referência fica livre.

> [!NOTE]
>
> Quem clica em "avise-me" na sua loja ainda entra com a conta dele no Need Alert (pelo `public_url` do item). Não existe inscrição sem login.

## Saldo sob controle (financeiro)

Um disparo recusado por `insufficient_credits` é um alerta que não saiu. Quem cuida do saldo pode acompanhá-lo pela API, com a permissão `manage_billing`.

**1. Leia o saldo**

`GET /tenants/{tenant}/credit-balance` devolve `balance` (créditos disponíveis, um por pessoa avisada) e `currency`.

**2. Compare com o consumo recente**

`GET /tenants/{tenant}/credit-transactions?type=consumption` lista os débitos, com `amount` negativo e `event_id`. Se `balance` ficar abaixo do custo médio dos últimos disparos, avise o financeiro.

**3. A compra fica no painel**

A API não compra créditos: o pagamento exige uma pessoa. Veja [Créditos](https://docs.needalert.app/establishments/credits.md).

## Variante: agendar em vez de disparar

Para um horário certo ("pão de queijo às 16h"), envie `scheduled_at` no `POST …/items/{item}/events`, dentro da janela `schedule` do `dispatch-preview`. O disparo nasce `scheduled`; reagende com `PATCH …/events/{event}` ou cancele com `DELETE …/events/{event}` enquanto não sair. Duas horas antes, o dono e quem tem a permissão de disparar recebem um aviso de saldo se ele não cobrir o custo.


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