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:
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.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 porinsufficient_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.
Variante: agendar em vez de disparar
Para um horário certo (“pão de queijo às 16h”), enviescheduled_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.