Visao geral

Operacoes de envio (mensagem, template, email e disparo de flow) nao bloqueiam ate a entrega. A API valida o payload, enfileira o job em background e responde de imediato com 202 Accepted e um requestId. O processamento real acontece nos workers e o resultado e entregue por webhook e/ou consultado por status.

Fluxo de uma requisicao assincrona

Voce chama o endpoint de envio (ex: POST /api/external/whatsapp/messages).
A API responde 202 com { "requestId": "req_..." }.
O job e processado em background.
Voce acompanha o resultado de uma das formas:
- Consultando GET /api/external/usage/status/{requestId}.
- Recebendo um evento de webhook (ex: WHATSAPP_SENT, WHATSAPP_DELIVERED).

requestId

O requestId identifica unicamente a requisicao dentro do seu workspace. Guarde-o para:

Consultar o status posterior em /usage/status/{requestId}.
Correlacionar com os eventos de webhook.
Auditar no historico em /usage/logs.

Header Idempotency-Key

Os endpoints de envio aceitam o header opcional Idempotency-Key. Use-o para evitar envios duplicados em caso de retry de rede.

Comportamento:

Se voce nao enviar o header, a API gera um requestId novo a cada chamada.
Se voce enviar Idempotency-Key, ele e usado como requestId.
Se ja existir uma requisicao com aquela chave, a API nao reprocessa: responde 200 com o status atual e idempotentReplay: true.

Gere uma chave por intencao de envio

Use um identificador unico por intencao de envio (ex: um UUID por mensagem que voce quer entregar) e reutilize a mesma chave em retries. Assim, se a rede falhar e voce repetir a chamada, o LIP nao envia duas vezes.

Exemplo:

Primeira chamada (202 Accepted):

Chamada repetida com a mesma chave (200 OK):

Endpoints que sao assincronos

POST /api/external/whatsapp/messages
POST /api/external/whatsapp/templates/send
POST /api/external/email/send
POST /api/external/email/campaigns/{id}/send
POST /api/external/flows/{id}/trigger

As demais operacoes de leitura e gestao de recursos (templates CRUD, conversas, listagens, webhooks) sao sincronas e respondem 200/201 diretamente.

Proximos passos

Uso e status de requisicoes: /docs/api-uso
Webhooks: /docs/api-webhooks