# Uso e registros

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

Quanto os seus projetos enviaram frente ao plano, o registro de mensagens e de entregas de webhook, o reenvio de webhooks e por quanto tempo tudo fica guardado.

A apiwpp conta as mensagens de cada projeto e guarda um registro das mensagens e das entregas de webhook. É o mesmo registro que o painel mostra, e a API o expõe para você montar os seus próprios relatórios e alertas. Cada operação vale para os projetos que a chave alcança: pedir um `tenantId` de fora deles responde `404`, como se não existisse.

| O quê | Operação | Escopo |
| --- | --- | --- |
| Uso de um projeto frente ao plano | `GET /tenants/{id}/usage` | `usage:read` |
| Totais diários de todos os seus projetos | `GET /usage/daily` | `usage:read` |
| Registro de mensagens | `GET /messages` | `logs:read` |
| Registro de entregas de webhook | `GET /webhooks/deliveries` | `logs:read` |
| Reenviar uma entrega | `POST /webhooks/deliveries/{id}/resend` | `webhooks:write` |
| Reenviar todas as entregas mortas | `POST /webhooks/deliveries/resend-dead` | `webhooks:write` |

## Uso do projeto

`GET /tenants/{id}/usage` traz as mensagens enviadas hoje e neste mês pelo projeto e pela organização dele, o plano, a assinatura e o histórico diário do projeto. Os dias e os meses são contados em UTC. O parâmetro `days` escolhe o tamanho do histórico: padrão 30, no máximo 366.

**cURL**

```bash
curl -s "https://api.apiwpp.com/tenants/$TENANT_ID/usage?days=7" \
  -H "Authorization: Bearer $API_KEY"
```

**Node.js**

```javascript
const res = await fetch(`https://api.apiwpp.com/tenants/${process.env.TENANT_ID}/usage?days=7`, {
  headers: { Authorization: `Bearer ${process.env.API_KEY}` },
})
const { plan, organization } = await res.json()

if (plan && plan.maxMessagesMonth > 0 && organization.usage.percentOfMonthlyLimit >= 80) {
  console.warn(`A organização já usou ${organization.usage.percentOfMonthlyLimit.toFixed(1)}% da cota do mês`)
}
```

Resposta `200`

```json
{
  "tenantId": "3f6c2a8e-9d41-4b7a-8c15-2e7d9a0b4c61",
  "plan": { "name": "pro", "displayName": "Pro", "maxMessagesDay": 1000, "maxMessagesMonth": 20000 },
  "usage": { "today": 12, "thisMonth": 540, "percentOfDailyLimit": 1.2, "percentOfMonthlyLimit": 2.7 },
  "organization": {
    "id": "2d5e8a1b-4c7f-4e9a-8b3d-6f0a2c4e8b1d",
    "usage": { "today": 30, "thisMonth": 1200, "percentOfDailyLimit": 3, "percentOfMonthlyLimit": 6 }
  },
  "subscription": { "status": "active", "trialEndsAt": null, "currentPeriodEnd": "2026-10-24T12:00:00.000Z" },
  "dailyUsage": [
    { "date": "2026-09-23", "messagesSent": 42, "messagesRecv": 17 },
    { "date": "2026-09-24", "messagesSent": 12, "messagesRecv": 5 }
  ]
}
```

| Campo | O que traz |
| --- | --- |
| `plan` | O plano da organização: `maxMessagesDay` e `maxMessagesMonth` são as cotas de mensagens (`-1`: sem cota). `null` quando a organização não tem plano, o que também quer dizer sem cota. |
| `usage` | As mensagens enviadas pelo próprio projeto hoje e no mês, e quanto elas representam das cotas da organização, em porcentagem. |
| `organization.usage` | As mesmas contas somando todos os projetos da organização. É sobre esse número que as cotas valem. |
| `subscription` | O `status` da assinatura, o fim do período de teste (`trialEndsAt`) e o fim do período pago (`currentPeriodEnd`). |
| `dailyUsage` | Uma linha por dia do projeto, com as mensagens enviadas (`messagesSent`) e recebidas (`messagesRecv`). |

Uma mensagem conta como enviada quando sai da fila para o WhatsApp, não quando a API a aceita.

### A cota do plano no envio

Os planos são da organização, e todos os projetos dela somam para as cotas diária e mensal. Os planos por número, LITE e PRO, não têm cota de mensagens (`-1`): neles os percentuais ficam em `0`, e os únicos limites de envio são os de ritmo que protegem o número (veja [Limites de envio](https://apiwpp.com/docs/guias/limites-de-envio)).

Num plano com cota, cada `POST /connections/{id}/send` confere o uso da organização somado às mensagens que já estão na fila e ainda não saíram:

- a partir de 80% da cota, o envio é aceito com o cabeçalho `X-Usage-Warning: Approaching limit: 85% used`;
- a partir de 110% da cota (uma margem de 10% para requisições simultâneas), o envio é recusado com `429`, o cabeçalho `X-Usage-Percent` e um `error` que diz qual cota passou, por exemplo `Daily message limit exceeded (1100/1000)`. A cota mensal é conferida antes da diária.

Esse `429` não traz `Retry-After`: a cota diária volta à meia-noite UTC e a mensal no primeiro dia do mês. A página [Erros](https://apiwpp.com/docs/guias/erros) mostra como separar esse `429` dos outros.

## Uso diário

`GET /usage/daily` soma, dia a dia, as mensagens enviadas e recebidas de todos os projetos que a chave alcança. Vem uma entrada por dia em UTC, incluindo os dias zerados, do mais antigo ao mais recente; hoje é a última. O parâmetro `days` vai de 1 a 90 (padrão 14).

```bash
curl -s "https://api.apiwpp.com/usage/daily?days=2" \
  -H "Authorization: Bearer $API_KEY"
```

Resposta `200`

```json
{ "days": [ { "date": "2026-09-23", "sent": 42, "received": 17 }, { "date": "2026-09-24", "sent": 12, "received": 5 } ] }
```

## Registro de mensagens

`GET /messages` lista as mensagens enviadas pela API e as recebidas, das mais novas para as mais antigas. As mensagens que você manda direto do celular não entram no registro.

| Parâmetro | Descrição |
| --- | --- |
| `direction` | `out` (enviadas) ou `in` (recebidas). |
| `status` | `queued`, `sent`, `delivered`, `read`, `failed` ou `received`. |
| `tenantId` | Só as mensagens de um projeto. |
| `connectionId` | Só as mensagens de uma conexão. |
| `q` | Busca, sem diferenciar maiúsculas, no contato, no texto, no `jobId`, no `clientRef` e no `messageId`. Um telefone formatado, como `+55 (11) 98888-7777`, também encontra o contato gravado só com dígitos. |
| `limit` | Quantas linhas trazer: padrão 60, no máximo 200. |

**cURL**

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

**Node.js**

```javascript
const params = new URLSearchParams({ status: 'failed', connectionId, limit: '200' })
const res = await fetch(`https://api.apiwpp.com/messages?${params}`, {
  headers: { Authorization: `Bearer ${process.env.API_KEY}` },
})
const { messages, counts } = await res.json()
for (const m of messages) console.log(m.contact, m.clientRef, m.error)
```

Resposta `200`

```json
{
  "messages": [
    {
      "id": "a1b2c3d4-e5f6-4a7b-8c9d-0e1f2a3b4c5d",
      "tenantId": "3f6c2a8e-9d41-4b7a-8c15-2e7d9a0b4c61",
      "connectionId": "8b1d4e7f-2c3a-4f5b-9e6d-7a8b9c0d1e2f",
      "direction": "out",
      "contact": "5511988887777",
      "type": "text",
      "body": "Olá! Sua consulta está confirmada.",
      "status": "delivered",
      "jobId": "c2a4e6f8-1b3d-4f5a-8c7e-9d0b1a2c3e4f",
      "clientRef": "pedido-1234",
      "messageId": "3EB0C767D26A1D8A3F52",
      "error": null,
      "events": [
        { "status": "queued", "at": "2026-09-24T11:59:55.000Z" },
        { "status": "sent", "at": "2026-09-24T12:00:00.000Z" },
        { "status": "delivered", "at": "2026-09-24T12:00:02.000Z" }
      ],
      "createdAt": "2026-09-24T11:59:55.000Z",
      "updatedAt": "2026-09-24T12:00:02.000Z"
    }
  ],
  "counts": { "all": 1, "in": 0, "out": 1 }
}
```

Como ler cada linha:

- `contact` é o telefone do contato, ou a parte do JID antes do `@` quando o endereço não é um telefone (um LID ainda não resolvido ou um grupo).
- Nas enviadas, `type` é `text`, o tipo da mídia (`image`, `audio`, `video`, `document`, `sticker`), `location` ou `template`; nas recebidas, é o tipo de mensagem que chegou. O `body` é uma prévia de até 1000 caracteres: o texto, a legenda, o nome do arquivo ou o nome do local.
- Uma mensagem enviada começa em `queued` e só avança: `sent`, `delivered`, `read`. Confirmações fora de ordem não fazem o status voltar. `failed` vale a qualquer momento, com o motivo em `error`; uma recebida fica em `received`. `events` guarda cada mudança com o horário.
- `counts` aplica todos os filtros menos `direction`, para você saber quantas há em cada direção de uma vez.

> **Dica**
>
> O registro é gravado sem atrasar o envio e o recebimento: se uma gravação falhar, a mensagem segue normalmente e a linha pode faltar. Para integrar o seu sistema, use os webhooks (`message.delivery`, `message.send_failed`, `message.incoming`); o registro serve para consulta e suporte.

## Registro de entregas de webhook

`GET /webhooks/deliveries` traz uma linha por evento de webhook, das mais novas para as mais antigas, com o estado da entrega:

| `state` | O que quer dizer |
| --- | --- |
| `delivered` | O seu endpoint respondeu `2xx`. |
| `retry` | A entrega falhou e está aguardando uma nova tentativa em `nextAttemptAt`. |
| `dead` | As tentativas acabaram sem sucesso. A entrega só sai daqui por um reenvio. |

Os filtros são `state`, `tenantId` e `limit` (padrão 60, no máximo 200). Cada linha traz o `eventType`, a `url` chamada, o `httpStatus` e o `error` da última tentativa, a latência em `latencyMs`, as tentativas feitas (`attempts`) e o máximo (`maxAttempts`, hoje 6), se a entrega foi assinada (`signed`) e o `payload` enviado. Um payload maior que 256 KB não é guardado: no lugar dele vem `{"_truncated": true, "type": "…", "bytes": …}`.

```bash
curl -s "https://api.apiwpp.com/webhooks/deliveries?state=dead&limit=50" \
  -H "Authorization: Bearer $API_KEY"
```

`counts` traz o total por estado ignorando o filtro `state`, e `stats` resume todas as linhas guardadas: `successRate` de 0 a 100 (`null` sem nenhuma linha) e `avgLatencyMs`, a latência média das entregas bem-sucedidas. O guia [Webhooks e assinatura](https://apiwpp.com/docs/guias/webhooks-e-assinatura) explica o prazo de resposta e o calendário das novas tentativas.

### Reenviar

Depois de corrigir o seu endpoint, reenvie o que ficou para trás. O reenvio põe a entrega na fila para agora, com um limite de tentativas novo.

- `POST /webhooks/deliveries/{id}/resend` reenvia uma entrega em `dead` ou em `retry` e responde a linha atualizada. Uma entrega já feita responde `409`, e uma cujo payload não foi guardado (maior que 256 KB) também.
- `POST /webhooks/deliveries/resend-dead` reenvia de uma vez as entregas `dead` de todos os projetos que a chave alcança, até 1000 por chamada, das mais novas para as mais antigas, e responde quantas voltaram para a fila. As que não têm payload guardado continuam `dead`, com o erro `payload not available for resend`. Se havia mais de 1000, chame de novo, enquanto `requeued` vier igual a 1000. Mas as que ficaram `dead` sem corpo guardado voltam a ocupar as 1000 vagas da próxima chamada, que começa sempre pelas mais novas: se `requeued` vier abaixo de 1000 e ainda houver entregas `dead` mais antigas, reenvie essas uma a uma com `POST /webhooks/deliveries/{id}/resend`.

**cURL**

```bash
curl -s -X POST https://api.apiwpp.com/webhooks/deliveries/resend-dead \
  -H "Authorization: Bearer $API_KEY"
```

**Node.js**

```javascript
let requeued
do {
  const res = await fetch('https://api.apiwpp.com/webhooks/deliveries/resend-dead', {
    method: 'POST',
    headers: { Authorization: `Bearer ${process.env.API_KEY}` },
  })
  ;({ requeued } = await res.json())
} while (requeued === 1000)
```

Resposta `200`

```json
{ "requeued": 3 }
```

Um evento reenviado chega de novo ao seu endpoint com o mesmo conteúdo. Como a entrega já é pelo menos uma vez, trate eventos repetidos sem efeito duplicado.

## Por quanto tempo fica guardado

| Dado | Retenção padrão |
| --- | --- |
| Registro de mensagens (`GET /messages`) | 7 dias |
| Registro de entregas de webhook (`GET /webhooks/deliveries`), com os payloads | 7 dias |
| Eventos de conexão, de onde vem o [histórico de heartbeats](https://apiwpp.com/docs/api/projetos/historico-de-heartbeats) | 30 dias |

A limpeza roda a cada 6 horas, então uma linha pode durar algumas horas além do prazo. Uma entrega que passou do prazo não pode mais ser reenviada. Os totais de uso (`GET /tenants/{id}/usage` e `GET /usage/daily`) não entram nessa limpeza. Se você precisa de um histórico mais longo das mensagens, guarde os eventos de webhook no seu sistema.

## Próximos passos

- [Uso do projeto](https://apiwpp.com/docs/api/uso/uso-do-projeto) e [Listar mensagens](https://apiwpp.com/docs/api/registros/listar-mensagens): todos os campos e respostas.
- [Webhooks e assinatura](https://apiwpp.com/docs/guias/webhooks-e-assinatura): receber, verificar e responder os eventos.
- [Limites de envio](https://apiwpp.com/docs/guias/limites-de-envio): o ritmo por número, o aquecimento e os outros `429`.
- [Idempotência](https://apiwpp.com/docs/guias/idempotencia): o `clientRef` que liga o envio ao registro e aos eventos.
