Conceitos

O vocabulário da plataforma e o que ele implica na prática.

Tenant, instância, chave

Tenant  (sua organização)
├── Chave de API  (ten_...)      credencial de acesso; pode ter várias
├── Chave de API  (ten_...)
├── Instância  INST-A1B2C3       um número de WhatsApp
├── Instância  INST-D4E5F6       outro número
└── Instância  INST-G7H8I9

Tenant é a fronteira de isolamento. Toda chave pertence a um tenant, e por ela você só enxerga os recursos daquele tenant. Tentar acessar uma instância de outro devolve 404, não 403: não confirmamos a existência de recursos alheios.

Instância é um número de WhatsApp conectado. Cada uma mantém sua própria sessão, seu próprio histórico e seu próprio webhook. Quantas você pode ter depende do plano.

Chave de API é a credencial. As chaves criadas no painel têm acesso total (*) e enxergam exatamente as mesmas coisas: a separação existe para você poder revogar uma integração sem derrubar as outras. Vale criar uma por sistema integrado. A chave que um app conectado recebe por OAuth é diferente: ela só tem os scopes que você aprovou no consentimento (veja OAuth 2.1).

Note o que isso implica: não existe chave por instância. Uma chave do tenant alcança todas as instâncias dele, e o que separa uma integração da outra é a disciplina de uma chave por sistema. Criar, rotacionar e revogar é em Chaves de API, no painel.

Ciclo de vida de uma instância

 criada ──> connecting ──> qr ──> connected ──┬──> disconnected ──> (reconecta)
                                              └──> error

Estado	O que significa
`connecting`	O motor está subindo. Transitório, dura segundos.
`qr`	Há um QR code aguardando leitura. Expira e é regenerado.
`connected`	Pareada e operante. É o único estado em que dá para enviar.
`disconnected`	Sem sessão ativa. A sessão no disco pode ter sido preservada.
`error`	Falha que exigiu parar. Reconectar costuma resolver.

Um detalhe do contrato: o endpoint /qr reporta qr_code onde os outros reportam qr. É um apelido histórico mantido por compatibilidade, e vale apenas naquela resposta. Se você compara status, trate os dois como o mesmo estado.

O que causa desconexão

Fora o comando explícito, uma instância pode cair porque o celular ficou muito tempo sem internet, porque o usuário removeu o aparelho conectado pelo WhatsApp, ou porque a plataforma encerrou uma sessão ociosa. Instâncias sem atividade são liberadas depois de cerca de 30 minutos, e reconectar depois disso normalmente não exige QR novo, porque a sessão fica no disco.

Desconectar não é remover

São operações diferentes, e a distinção importa:

POST /instances/{id}/disconnect: encerra a conexão e preserva a sessão. Para voltar, basta reconectar. É o que você quer para uma pausa.
DELETE /instances/{id}: faz logout no WhatsApp, apaga a sessão e remove o registro. Irreversível: voltar exige escanear um QR novo.

Identificadores de mensagem

Uma mensagem tem dois identificadores, e eles servem para coisas diferentes:

messageId: o ID atribuído pelo WhatsApp, no formato true_5511123456789@c.us_3EB0ABC123. É estável e cruza os limites do sistema: aparece na resposta do envio, nos eventos de webhook e nas consultas de histórico. É por ele que você deduplica.
id: o ID interno, sequencial, do registro no nosso banco. Útil para paginação, inútil fora daqui.

O externalId que aparece nos eventos de webhook é o mesmo valor do messageId.

Idempotência

O envio direto (POST .../messages/send) não é idempotente: duas chamadas iguais mandam duas mensagens. Se a sua chamada falhou por timeout de rede, você não sabe se a mensagem saiu.

Quando essa dúvida é inaceitável, use a fila (POST .../messages/queue/send), que exige uma idempotencyKey. Repetir a mesma chave nunca duplica a mensagem, o servidor reconhece que já processou e devolve o resultado anterior.

A chave deve vir do seu domínio, não de um gerador aleatório por tentativa. pedido-4711- confirmacao protege; um UUID novo a cada retry não protege nada, porque cada tentativa vira uma mensagem diferente aos olhos do servidor.

Formato de número

Só dígitos: código do país, DDD e número, sem +, espaço, parênteses ou traço.

✅ 5511123456789
❌ +55 11 12345-6789
❌ (11) 12345-6789

São aceitos de 10 a 15 dígitos. Números fora desse padrão são recusados com 400 antes de qualquer tentativa de envio.

Modo de operação da instalação

A plataforma roda em dois modos, e isso muda o que existe:

Completo: signup público, planos, cobrança e limites por plano. É o modo de apidevzap.com.
Cliente único: uma instalação dedicada a um cliente só. Não há cobrança nem paywall, e os limites de plano não se aplicam.

Para quem integra, a API v1 é idêntica nos dois modos: mesmos endpoints, mesmos formatos. A diferença aparece só nos erros 403 de plano, que no modo cliente único simplesmente não acontecem.

Guia verificado em 05/08/2026 contra a API v1.

← Todos os guias