# Need Alert

> Avise seus clientes no momento em que o que eles esperam fica disponível.

## Guias

### Começando

- [Introdução](https://docs.needalert.app/index.md): O Need Alert avisa seus clientes no momento em que o que eles esperam fica disponível.
- [Como funciona](https://docs.needalert.app/how-it-works.md): Os conceitos do Need Alert: estabelecimento, item, inscrição, disparo e créditos.
- [Casos de uso](https://docs.needalert.app/use-cases.md): Exemplos de como diferentes negócios usam o Need Alert.

### Para estabelecimentos

- [Primeiros passos](https://docs.needalert.app/establishments/getting-started.md): Crie seu estabelecimento e prepare o primeiro item em poucos minutos.
- [Itens e QR Code](https://docs.needalert.app/establishments/items-and-qr-codes.md): Cadastre o que seus clientes esperam e gere o QR Code para as inscrições.
- [Disparar alertas](https://docs.needalert.app/establishments/send-alerts.md): Avise todos os inscritos no momento em que o item fica disponível.
- [Agendar disparos](https://docs.needalert.app/establishments/schedule-alerts.md): Programe o alerta para um horário futuro e receba um aviso de saldo antes.
- [Créditos](https://docs.needalert.app/establishments/credits.md): Como os créditos funcionam, como comprar e como acompanhar o consumo.
- [Equipe e papéis](https://docs.needalert.app/establishments/team-and-roles.md): Convide sua equipe e defina o que cada pessoa pode fazer.
- [Integrações](https://docs.needalert.app/establishments/integrations.md): Chaves de API para o sistema da sua rede cadastrar itens e disparar alertas sem ninguém no painel.
- [Catálogo da rede](https://docs.needalert.app/establishments/chain-catalog.md): Cadastre um produto uma vez e reaproveite em todas as unidades.

### Para quem espera

- [Inscrever-se](https://docs.needalert.app/customers/subscribe.md): Escaneie o QR Code, inscreva-se e seja avisado quando o item estiver disponível.
- [Minhas inscrições](https://docs.needalert.app/customers/my-subscriptions.md): Veja tudo o que você está esperando e cancele uma inscrição quando quiser.
- [Avisos e app](https://docs.needalert.app/customers/alerts-and-app.md): Receba os avisos no celular e instale o Need Alert na tela de início.
- [Minha conta](https://docs.needalert.app/customers/account.md): Perfil, segurança, histórico da conta, exclusão da conta e onde pedir ajuda.

## API

### Introdução

- [Visão geral da API](https://docs.needalert.app/api/overview.md): Integre o sistema do seu negócio ao Need Alert e dispare alertas automaticamente.
- [Autenticação](https://docs.needalert.app/api/authentication.md): Crie uma chave de API no painel e envie o token em toda requisição.
- [Primeira requisição](https://docs.needalert.app/api/first-request.md): Do zero a um alerta disparado pela API, em cinco chamadas.

### Guias

- [Idempotência](https://docs.needalert.app/api/idempotency.md): Repita uma requisição com segurança: a mesma chave devolve a mesma resposta, sem disparar nem cobrar de novo.
- [Referência externa](https://docs.needalert.app/api/external-reference.md): Use o código do seu sistema, como o SKU, para encontrar e sincronizar itens.
- [Casos de uso](https://docs.needalert.app/api/use-cases.md): Roteiros de integração: estoque voltou, horário cancelado, itens sincronizados e saldo sob controle.

### Convenções

- [Convenções](https://docs.needalert.app/api/conventions.md): Versão, formato das respostas, erros, paginação, idioma e limites da API.
- [Changelog](https://docs.needalert.app/api/changelog.md): O que mudou na API, versão a versão.

### Endpoints

#### Establishments

- [List units](https://docs.needalert.app/api/reference/establishments/list-units.md): The units the key can act on, paginated. Each one carries `tenant_id`, which the credit endpoints take, and `permissions`, the key's permissions in that unit.
- [Get a unit](https://docs.needalert.app/api/reference/establishments/get-a-unit.md): One unit of the key's scope. A unit outside the scope is a 404, never a 403.

#### Items

- [List items](https://docs.needalert.app/api/reference/items/list-items.md): The unit's items with their `subscribers_count`, paginated. Filter by `status`, `queue_type`, `search` (name) or `external_reference` (exact, case-sensitive); sort by `name`, `created_at` or `subscribers_count`.
- [Create an item](https://docs.needalert.app/api/reference/items/create-an-item.md): Creates an item people can subscribe to and the unit can alert. `translations` needs the block of the chain's default language with a `name`. `external_reference` is your own code for the item (SKU, procedure code): unique among the unit's non-archived items, matched exactly and case-sensitive; a du…
- [Get an item](https://docs.needalert.app/api/reference/items/get-an-item.md): All the item's fields, including every `translations` block and the `qr_code_url`.
- [Archive an item](https://docs.needalert.app/api/reference/items/archive-an-item.md): Archives instead of deleting: the item keeps its history, stops accepting subscriptions and alerts, and frees its `external_reference` for a new item. Archiving an archived item is a 422.
- [Update an item](https://docs.needalert.app/api/reference/items/update-an-item.md): Only the fields you send change. `translations`, when sent, replaces the whole set; `external_reference: null` clears the reference; `status` accepts `active` and `paused`. An archived item cannot be changed.
- [Get the item's QR code](https://docs.needalert.app/api/reference/items/get-the-items-qr-code.md): The image of the QR code that opens the item's public page (`public_url`). `format` is `svg` (default) or `png`; `size`, in pixels, applies to PNG only; `download=1` makes the browser save the file.
- [Upload the item's picture](https://docs.needalert.app/api/reference/items/upload-the-items-picture.md): `multipart/form-data` with one `image` file: JPEG, PNG or WebP, up to 5 MB. Replaces the current picture; the response is the item with its new `image_url`.
- [Remove the item's picture](https://docs.needalert.app/api/reference/items/remove-the-items-picture.md): The response is the item with `image_url: null`.

#### Dispatches

- [Preview an alert](https://docs.needalert.app/api/reference/dispatches/preview-an-alert.md): What sending this item's alert right now would cost: eligible subscribers, credits (one per person), the chain's balance and whether it covers the send. Nothing is sent or charged. `schedule` gives the window `scheduled_at` accepts and the lead of the low-balance warning.
- [Send or schedule an alert](https://docs.needalert.app/api/reference/dispatches/send-or-schedule-an-alert.md): Without `scheduled_at`, notifies every eligible subscriber of the item now, debiting one credit per person after checking the balance; the response is the dispatch in `pending` (or already `dispatched` when nobody is waiting), and `GET` it to follow the send. With `scheduled_at` (ISO 8601, inside th…
- [List dispatches](https://docs.needalert.app/api/reference/dispatches/list-dispatches.md): The unit's alerts, newest first, paginated. Filter by `item_id` and `status`.
- [Get a dispatch](https://docs.needalert.app/api/reference/dispatches/get-a-dispatch.md): Adds `notifications`, the recipients per delivery status. Poll it to follow a dispatch until it is `dispatched` or `failed`.
- [Cancel a scheduled dispatch](https://docs.needalert.app/api/reference/dispatches/cancel-a-scheduled-dispatch.md): Only while `scheduled`. The dispatch stays in the history as `cancelled`.
- [Reschedule a dispatch](https://docs.needalert.app/api/reference/dispatches/reschedule-a-dispatch.md): Only while `scheduled`. Send at least one of `scheduled_at`, `title` and `message`; `title: null` falls back to the item's name.

#### Credits

- [Get the credit balance](https://docs.needalert.app/api/reference/credits/get-the-credit-balance.md): The chain's balance in credits (one credit notifies one person) and its currency. Needs `manage_billing`.
- [List credit transactions](https://docs.needalert.app/api/reference/credits/list-credit-transactions.md): The chain's statement, newest first, paginated: purchases, bonuses, adjustments, refunds and the consumption of each dispatch. Filter by `type` and by `from`/`to` (ISO 8601 datetimes, inclusive). Needs `manage_billing`.

## OpenAPI Specs

- [openapi](/api-reference/openapi.json)

> The links below point to documentation indexes. Follow each `/_llms/` index recursively until you reach documentation pages.

## Indexes

- [English (41 pages)](https://docs.needalert.app/_llms/en.txt): Guides, API.


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