---
title: "Notificações transacionais por API de WhatsApp | D-API"
description: "Notificações transacionais por API de WhatsApp: fila, envio assíncrono, confirmação por webhook e idempotência para o cliente não receber aviso duplicado."
url: https://d-api.cloud/api-whatsapp-notificacoes-transacionais
---

Por caso de uso

# Notificações transacionais pela API de WhatsApp

Notificação transacional é a mensagem que nasce de um evento do seu sistema: pedido pago, senha trocada, status alterado. Para ela chegar uma vez, rápido e sem travar a aplicação, o envio precisa sair do request, passar por uma fila e ser confirmado por webhook.

Por Time de engenharia D-APIAtualizado em 24 de set de 20265 min de leitura

## Transacional não é campanha

A diferença não é o texto, é o gatilho. Uma campanha é decidida por uma pessoa e vai para uma lista. Uma notificação transacional é decidida pelo sistema, vai para uma pessoa e só existe porque algo aconteceu com ela. Exemplos típicos:

-   Pedido recebido, pagamento aprovado ou recusado, nota fiscal emitida.
-   Redefinição de senha, novo acesso à conta, alteração de e-mail.
-   Mudança de status em chamado, proposta, processo ou entrega.
-   Vencimento de plano, cartão expirando, limite de uso atingido.

Como o cliente espera esses avisos, a taxa de leitura no WhatsApp tende a ser alta e o risco de denúncia, baixo. Por outro lado, a tolerância a erro também é baixa: aviso de pagamento que chega duas vezes gera chamado, e aviso que não chega gera desconfiança. O desenho técnico existe para evitar esses dois casos.

## A arquitetura que aguenta volume

O erro mais comum é chamar a [API de WhatsApp](https://d-api.cloud/) dentro do request que processa o pagamento. Se a chamada demorar, o checkout demora. Se falhar, o pagamento fica num estado estranho. O fluxo recomendado separa as responsabilidades:

1.  **O domínio publica um evento**, por exemplo `pagamento.aprovado`, e segue a vida. Nada de WhatsApp aqui.
2.  **Um consumidor lê o evento da fila**, monta a mensagem a partir de um modelo e calcula a chave de idempotência.
3.  **O worker envia para a D-API com** `async: true`. A API responde na hora com um `commandId` e executa o envio em segundo plano.
4.  **O resultado chega no webhook** `command.result`. O worker grava o `commandId` junto da notificação e o webhook atualiza o registro.
5.  **Entrega e leitura chegam depois**, pelos eventos `message.delivered` e `message.read`, se você quiser exibir isso no painel.

A chamada do worker fica assim:

```
curl -X POST https://api.d-api.cloud/api/v1/messages/send/text \
  -H "Authorization: SUA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "sessionId": "loja-notificacoes",
    "to": "5511999999999",
    "text": "Pagamento aprovado. Seu pedido 48213 já está em separação.",
    "async": true
  }'
```

Se o seu sistema preferir consultar em vez de esperar o evento, o resultado também fica disponível em `GET /api/v1/commands/{commandId}` por cerca de uma hora. Para entrega garantida, a própria documentação recomenda o webhook. Quem já usa RabbitMQ pode receber os eventos direto numa fila, configurada por sessão.

## Idempotência: a notificação que não pode chegar duas vezes

Filas entregam pelo menos uma vez, não exatamente uma vez. Um worker que cai depois de enviar e antes de confirmar vai reprocessar a mesma mensagem. A proteção é do seu lado, e é simples:

-   **Chave derivada do evento, não do horário.** Algo como `pedido:48213:pago`. O mesmo evento sempre gera a mesma chave.
-   **Restrição de unicidade no banco.** Grave a chave numa tabela de notificações com índice único antes de chamar a API. Se a gravação falhar por duplicidade, o envio já aconteceu ou está em curso.
-   **Estado explícito.** `pendente`, `enviado` com o `commandId`, `confirmado` ou `falhou`. Retentativa só para o que está em `falhou`, com intervalo crescente e limite de tentativas.
-   **Webhook também é idempotente.** A D-API reenvia um webhook até 7 vezes se o seu servidor não responder, e deduplica eventos numa janela curta. Seu handler deve aceitar o mesmo evento repetido sem efeito colateral.

Os detalhes de formato e reenvio dos eventos estão em [webhook de WhatsApp](https://d-api.cloud/webhook-api-whatsapp).

## API oficial ou não oficial para notificações

Os dois caminhos funcionam para transacional, com regras diferentes. Na D-API eles usam a mesma integração, então a escolha pode ser revista sem reescrever o worker.

|  | Não oficial (QR) | Oficial (Cloud API) |
| --- | --- | --- |
| Primeira mensagem para o cliente | Texto livre | Template aprovado, em geral categoria utilidade |
| Rota de envio | `messages/send/text` e demais | `messages/send/template` fora da janela de conversa |
| Custo | Por conexão na D-API | Taxa por conexão mais cobrança da Meta por template, que varia por categoria e país |
| Mudar o texto | Imediato | Novo template, sujeito à aprovação da Meta |

No template oficial, as partes variáveis vão em `bodyVariables`, e o nome e o idioma do template são obrigatórios. Para aprofundar a escolha, veja [API oficial vs não oficial](https://d-api.cloud/api-whatsapp-oficial-vs-nao-oficial) e a página da [API oficial de WhatsApp](https://d-api.cloud/api-oficial-de-whatsapp).

## Boas práticas de conteúdo

-   Identifique a empresa na primeira linha. O cliente precisa saber quem fala antes de ler o resto.
-   Uma notificação, um assunto. Não aproveite aviso de pagamento para oferecer produto.
-   Inclua o identificador que o cliente reconhece: número do pedido, protocolo, final do cartão.
-   Agrupe eventos próximos. Três mudanças de status em dois minutos viram uma mensagem só.
-   Respeite horário. Aviso que não é urgente pode esperar a manhã seguinte.

Dois casos específicos têm guias próprios: [código de verificação](https://d-api.cloud/api-whatsapp-codigo-de-verificacao) e [rastreio de pedidos](https://d-api.cloud/api-whatsapp-rastreio-de-pedidos). Se as notificações vão sair de sistemas internos como ERP ou monitoramento, veja também [API de WhatsApp para operação interna](https://d-api.cloud/api-whatsapp-para-operacao-interna). O trial de 3 dias dá para montar o fluxo completo, do evento ao webhook de confirmação.

## Perguntas frequentes

### O que é uma notificação transacional no WhatsApp?

É uma mensagem disparada por um evento na vida do cliente, e não por uma campanha: pedido confirmado, pagamento aprovado, senha redefinida, entrega a caminho. Ela é esperada, individual e tem valor informativo imediato.

### Posso enviar notificação transacional pela API não oficial?

Pode, e é um dos usos mais comuns. O cuidado é enviar só para quem tem relação com a sua empresa e espera aquele aviso. Volume alto para quem não conhece o número é o que leva a bloqueio, não o tipo de API.

### Na API oficial preciso de template para notificação?

Sim, quando a conversa é iniciada pela empresa. Avisos de pedido, pagamento e conta normalmente entram na categoria utilidade da Meta, e o template precisa estar aprovado antes do primeiro envio. A aprovação é decisão da Meta.

### Como evito que o cliente receba a mesma notificação duas vezes?

Gere uma chave única para cada notificação a partir do evento, como pedido 123 pago, e grave essa chave antes de enviar. Se o evento chegar de novo, a chave já existe e o envio é ignorado.

### Como sei se a notificação foi entregue?

Ao enviar com async true você recebe um commandId, e o resultado do envio chega no webhook command.result. Depois disso, os eventos message.delivered e message.read informam entrega e leitura.

Teste a API de WhatsApp da D-API3 dias grátis, sem cartão.[Começar trial grátis](https://app.d-api.cloud/register)

## Continue lendo

-   [Por caso de usoCódigo de verificação (OTP)](https://d-api.cloud/api-whatsapp-codigo-de-verificacao)
-   [Por caso de usoConfirmação de agendamento](https://d-api.cloud/api-whatsapp-confirmacao-de-agendamento)
-   [Por caso de usoCobrança pelo WhatsApp](https://d-api.cloud/api-whatsapp-cobranca)
-   [Por caso de usoRastreio de pedidos](https://d-api.cloud/api-whatsapp-rastreio-de-pedidos)

## Teste a API de WhatsApp da D-API

Trial de 3 dias com acesso completo. Sem cartão, sem fidelidade.

[Começar trial grátis](https://app.d-api.cloud/register)[Ver documentação](https://docs.d-api.cloud/)