Idempotência e requisições assíncronas

Idempotency-Key opcional vs obrigatório, replay e operações assíncronas.

Header Idempotency-Key

Dois comportamentos existem na API:

Modo	Quando	Sem header	Com header repetido
Opcional (`resolveIdempotency`)	Envio WhatsApp/e-mail, CRM writes, etc.	Gera `requestId` novo	Replay se já `success`
Obrigatório (`requireIdempotency`)	Upload de mídia; mensagem em conversa; send/schedule campanha WA; retry/test/rotate webhook; cancel de execução	`400` `IDEMPOTENCY_KEY_REQUIRED`	Replay se já `success`

Operação em andamento (pending / scheduled / processing) → 409 IDEMPOTENCY_IN_PROGRESS.

200 OK — idempotentReplay

{
  "success": true,
  "data": {
    "requestId": "sua-chave",
    "status": "success",
    "idempotentReplay": true
  }
}

Campos extras do responsePayload original são mesclados em data (exceto secret de rotate — o usage guarda só { rotated: true }).

Envios enfileiram job e respondem com requestId. Consulte GET /usage/status/{requestId} ou webhooks.

Endpoints tipicamente 202: