# Idempotência

Fonte: https://apiwpp.com/docs/guias/idempotencia
Seção: Guias
Atualizado em: 2026-09-29

Repita um envio com segurança depois de um timeout usando o clientRef e ligue cada webhook da mensagem ao registro certo do seu sistema.

O `clientRef` é o **seu** identificador de um envio: o id do pedido, da notificação, da linha na sua fila de saída. É um campo opcional do corpo de [`POST /connections/{id}/send`](https://apiwpp.com/docs/api/mensagens/enviar-mensagem), com até 200 caracteres, e faz duas coisas:

1. torna o envio **idempotente**: repetir a requisição não duplica a mensagem;
2. volta nos webhooks daquela mensagem, para você saber a qual registro cada evento pertence.

> **Não existe cabeçalho Idempotency-Key**
>
> A idempotência da apiwpp é o campo `clientRef` do corpo, e vale só para o envio de mensagens. Um cabeçalho `Idempotency-Key` é ignorado.

## Repetir sem duplicar

Um timeout não diz se a mensagem entrou na fila. Com `clientRef`, repita a mesma requisição sem medo:

- A **primeira** requisição com um `clientRef` numa conexão enfileira a mensagem e responde `202` com o job.
- Uma **repetição** com o mesmo `clientRef`, na mesma conexão, responde `200` com o **job original** e `"duplicate": true`, e não enfileira nada.

**Enviar com clientRef**

```bash
curl -s -X POST https://api.apiwpp.com/connections/$CONNECTION_ID/send \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"to": "5511988887777", "message": "Seu pedido 1234 saiu para entrega.", "clientRef": "pedido-1234"}'
```

Resposta `202`

```json
{ "jobId": "c2a4e6f8-1b3d-4f5a-8c7e-9d0b1a2c3e4f", "scheduledAt": 1790251205000, "position": 1 }
```

A mesma requisição, repetida:

Resposta `200`

```json
{ "jobId": "c2a4e6f8-1b3d-4f5a-8c7e-9d0b1a2c3e4f", "scheduledAt": 1790251205000, "position": 1, "duplicate": true }
```

Trate `200` com `duplicate: true` como sucesso: a mensagem já está na fila (ou já saiu). Se a repetição chegar enquanto a primeira requisição ainda está sendo enfileirada, `scheduledAt` e `position` vêm `null`; o `jobId` já é o definitivo.

### O que a reserva cobre

- **Por conexão.** O `clientRef` é reservado na conexão do envio. O mesmo valor em outra conexão é outro envio.
- **Por 7 dias.** Depois de aceito, o `clientRef` fica reservado por 7 dias, o mesmo tempo que o job fica guardado.
- **Só envios aceitos.** Uma requisição que termina em erro não reserva nada: se o enfileiramento falhar, a reserva é liberada na hora, e a repetição enfileira normalmente. Se o gateway cair entre a reserva e o enfileiramento, a reserva provisória expira sozinha em 60 segundos.

### Por que uma repetição nunca vira erro

A apiwpp procura o `clientRef` antes de conferir o template, o status da conexão, a cota do plano e o limite de destinatários novos. Então a repetição de um envio aceito recebe o job original mesmo que, nesse meio-tempo, a conexão esteja reconectando ou a cota tenha acabado. Na prática, numa repetição:

| Resposta | O que quer dizer |
| --- | --- |
| `200` com `duplicate: true` | Um envio anterior com esse `clientRef` foi aceito. Nada novo foi enfileirado |
| `202` | Nenhum envio anterior foi aceito; este foi, agora |
| `400`, `404` ou `429` de cota (com `X-Usage-Percent`) ou `new_recipient_cap_reached` | Nenhuma requisição com esse `clientRef` foi aceita: nada foi enfileirado |
| `429` com `Retry-After`, sem `X-Usage-Percent` nem `error` de destinatários novos | Limite de requisições: a repetição nem chegou a ser examinada. Espere e repita |
| `401`, `403` ou `402` | A chave, o escopo ou a assinatura da organização barraram a requisição antes da busca pelo `clientRef`. Não diz nada sobre o envio anterior |
| `503` com `Retry-After` | A conexão está mudando de instância. Espere e repita |

O guia [Erros](https://apiwpp.com/docs/guias/erros) detalha cada status, e [Limites de envio](https://apiwpp.com/docs/guias/limites-de-envio) explica os três tipos de `429`.

### Um cliente que repete com segurança

Gere o `clientRef` **uma vez**, a partir do seu registro, e reutilize-o em todas as tentativas daquele envio. Repita em falhas de rede, `429` e `5xx`, com espera crescente; não repita um `400`, `401`, `402`, `403` ou `404` sem corrigir a causa.

**Node.js**

```js
const BASE = 'https://api.apiwpp.com'

async function sendOnce(connectionId, body, { attempts = 5 } = {}) {
  for (let attempt = 1; ; attempt++) {
    let res
    try {
      res = await fetch(`${BASE}/connections/${connectionId}/send`, {
        method: 'POST',
        headers: { Authorization: `Bearer ${process.env.API_KEY}`, 'Content-Type': 'application/json' },
        body: JSON.stringify(body), // o mesmo clientRef em todas as tentativas
        signal: AbortSignal.timeout(15_000),
      })
    } catch (err) {
      // Timeout ou erro de rede: a mensagem pode ter entrado na fila. Repetir é seguro.
      if (attempt >= attempts) throw err
      await sleep(backoff(attempt))
      continue
    }

    if (res.status === 202 || res.status === 200) return res.json() // 200 = duplicate: true
    const retryable = res.status === 429 || res.status >= 500
    if (!retryable || attempt >= attempts) {
      throw new Error(`send failed: ${res.status} ${await res.text()}`)
    }
    const retryAfter = Number(res.headers.get('retry-after'))
    await sleep(retryAfter > 0 ? retryAfter * 1000 : backoff(attempt))
  }
}

const backoff = (attempt) => Math.min(1000 * 2 ** attempt, 30_000)
const sleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms))

await sendOnce(process.env.CONNECTION_ID, {
  to: '5511988887777',
  message: 'Seu pedido 1234 saiu para entrega.',
  clientRef: 'pedido-1234',
})
```

**cURL**

```bash
# --retry repete a mesma requisição (o mesmo corpo, o mesmo clientRef) em timeouts,
# 408, 429, 500, 502, 503 e 504, respeitando o Retry-After.
curl -s --retry 5 --max-time 15 \
  -X POST https://api.apiwpp.com/connections/$CONNECTION_ID/send \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"to": "5511988887777", "message": "Seu pedido 1234 saiu para entrega.", "clientRef": "pedido-1234"}'
```

> **Um reenvio de propósito usa um clientRef novo**
>
> Se um envio aceito falhou depois (por exemplo, com `message.send_failed`), repetir com o mesmo `clientRef` só responde `duplicate`, durante os 7 dias da reserva. Para mandar a mensagem de novo, use outro `clientRef`, como `pedido-1234-2`.

## Correlacionar os eventos

O `clientRef` volta nos webhooks da mensagem, e você liga cada evento ao seu registro sem precisar saber antes o `messageId` do WhatsApp:

| Evento | Quando |
| --- | --- |
| [`message.outgoing`](https://apiwpp.com/docs/webhooks/message-outgoing) | A mensagem saiu, com `origin: API` (só para projetos com `emitOutgoing: true`) |
| [`message.delivery`](https://apiwpp.com/docs/webhooks/message-delivery) | Cada mudança de status (`sent`, `delivered`, `read`, `failed`), junto com o `messageId` do WhatsApp |
| [`message.send_failed`](https://apiwpp.com/docs/webhooks/message-send-failed) | A apiwpp desistiu do envio; `messageId` é `null` e `reason` diz por quê |

**message.delivery**

```json
{
  "type": "message.delivery",
  "connectionId": "8b1d4e7f-2c3a-4f5b-9e6d-7a8b9c0d1e2f",
  "tenantId": "3f6c2a8e-9d41-4b7a-8c15-2e7d9a0b4c61",
  "externalId": "shop-42",
  "timestamp": "2026-09-24T12:00:02.000Z",
  "data": {
    "messageId": "3EB0C767D26A1D8A3F52",
    "status": "delivered",
    "recipient": "5511988887777",
    "jid": "5511988887777@s.whatsapp.net",
    "phone": "+5511988887777",
    "clientRef": "pedido-1234"
  }
}
```

A apiwpp gera o `messageId` e o associa ao `clientRef` **antes** de entregar a mensagem ao WhatsApp, então o eco de um envio pela API nunca chega como `origin: PHONE`. A associação vale por **72 horas**: depois disso, um status tardio (um celular que ficou desligado no fim de semana, por exemplo) chega com `clientRef: null`. Por isso, guarde o `messageId` do primeiro evento que o trouxer e, daí em diante, correlacione pelos dois.

Um `message.delivery` com `status: failed` pode trazer `reason: reachout_timelocked`: o WhatsApp recusou a mensagem como contato frio. Ela não é tentada de novo; veja [Bloqueio temporário de novas conversas](https://apiwpp.com/docs/guias/limites-de-envio#bloqueio-temporario-de-novas-conversas).

## message.send_failed: o envio aceito que não vai acontecer

Depois do `202`, a apiwpp tenta o envio até 3 vezes, com espera crescente entre as tentativas. Quando ela desiste, um envio **com `clientRef`** gera o evento `message.send_failed`; um envio sem `clientRef` não gera nenhum evento, porque não haveria como correlacioná-lo. É o único aviso de que um envio aceito não vai sair: a repetição com o mesmo `clientRef` continua respondendo `duplicate`.

**message.send_failed**

```json
{
  "type": "message.send_failed",
  "connectionId": "8b1d4e7f-2c3a-4f5b-9e6d-7a8b9c0d1e2f",
  "tenantId": "3f6c2a8e-9d41-4b7a-8c15-2e7d9a0b4c61",
  "externalId": "shop-42",
  "timestamp": "2026-09-24T12:00:05.000Z",
  "data": {
    "clientRef": "pedido-1234",
    "jobId": "c2a4e6f8-1b3d-4f5a-8c7e-9d0b1a2c3e4f",
    "messageId": null,
    "to": "5511988887777",
    "jid": "5511988887777@s.whatsapp.net",
    "phone": "+5511988887777",
    "reason": "not_on_whatsapp",
    "attempts": 1
  }
}
```

`messageId` é sempre `null`, `to` é o destinatário como você o enviou e `attempts` diz quantas tentativas foram feitas. `reason` diz o motivo:

| `reason` | O que houve | O que fazer |
| --- | --- | --- |
| `attempts_exhausted` | Todas as tentativas de envio falharam | Confira a conexão e reenvie com um `clientRef` novo |
| `lease_expired` | O envio travou na última tentativa (por exemplo, num reinício); ele pode ter saído mesmo assim | Espere um eco ou um status do mesmo `clientRef` antes de reenviar |
| `not_on_whatsapp` | O número não está no WhatsApp; não há novas tentativas | Corrija o número; [verifique números](https://apiwpp.com/docs/api/contatos/verificar-numeros) antes de enviar |
| `reachout_timelocked` | A conta está num bloqueio temporário de novas conversas; o envio foi recusado sem ser tentado | Reenvie depois do fim do bloqueio, com um `clientRef` novo |

> **A prova de envio vale**
>
> Se, depois de um `message.send_failed`, chegar um `message.outgoing` ou um `message.delivery` do mesmo `clientRef`, a mensagem saiu: fique com a prova de envio. Sem nenhum evento depois de um envio aceito, concilie pelo registro de mensagens, que procura também pelo `clientRef`: [`GET /messages?q=pedido-1234`](https://apiwpp.com/docs/api/registros/listar-mensagens).

**Conciliar pelo registro de mensagens**

```bash
curl -s "https://api.apiwpp.com/messages?q=pedido-1234" \
  -H "Authorization: Bearer $API_KEY"
```

O registro guarda, por padrão, os últimos 7 dias de mensagens, com o `status` (`queued`, `sent`, `delivered`, `read`, `failed` e, nas recebidas, `received`), o `jobId`, o `clientRef`, o `messageId` e o `error` de cada uma. A chave precisa do escopo `logs:read`.

## Próximos passos

- [Enviar mensagens](https://apiwpp.com/docs/guias/enviar-mensagens): tipos de conteúdo, a fila e o que acontece depois do `202`.
- [Webhooks e assinatura](https://apiwpp.com/docs/guias/webhooks-e-assinatura): receber, verificar e reprocessar os eventos.
- [Limites de envio](https://apiwpp.com/docs/guias/limites-de-envio): por que um envio aceito espera na fila, e os três tipos de `429`.
- [Referência: Enviar mensagem](https://apiwpp.com/docs/api/mensagens/enviar-mensagem): todos os campos do corpo e as respostas.
