Documentação da API
Conecte um número de WhatsApp por QR code e controle tudo por HTTP. URL base: https://certu.com.br/api/v1. Todo corpo é JSON.
Quais são os 7 fatos principais?
- Conecte um número de WhatsApp por QR code e controle tudo por HTTP.
- Siga os quatro passos abaixo e mande a primeira mensagem em poucos minutos.
- Crie a conta no painel e copie a chave de teste (certu_sk_test_...) ou de produção (certu_sk_...).
- Mande a chave no cabeçalho Authorization em toda requisição.
- Respeite os limites abaixo pra manter o seu número e o servidor saudáveis.
- Passou do limite, a API responde 429 com o cabeçalho Retry-After em segundos.
- Leia o campo error pra decidir o que fazer; o message é só pra humanos. { "error": "instance_not_connected", "message": "This instance is not connected.
Quais são os números principais?
| Número | O que significa |
|---|---|
| R$ 48,50 por mês | Gere o link da fatura de R$ 48,50 por mês desta instância. |
| 10 segundos | Responda 2xx em até 10 segundos. |
Início rápido
Siga os quatro passos abaixo e mande a primeira mensagem em poucos minutos.
- Crie a conta no painel e copie a chave de teste (
certu_sk_test_...) ou de produção (certu_sk_...). - Crie uma instância com
POST /instances. - Pegue o QR code com
GET /instances/{id}/qre leia no celular, em Aparelhos conectados. - Quando o webhook
instance.connectedchegar, mande a primeira mensagem comPOST /instances/{id}/messages/text.
Autenticação
Mande a chave no cabeçalho Authorization em toda requisição.
Authorization: Bearer certu_sk_4f9c...
A chave vale para todas as instâncias da conta. Guarde a chave no servidor, nunca no navegador ou no app. Se ela vazar, apague no painel e crie outra: a antiga para de funcionar na hora.
certu_sk_test_) não envia nada de verdade: devolve respostas simuladas pra você montar a integração sem conectar um número.Limites
Respeite os limites abaixo pra manter o seu número e o servidor saudáveis.
| Limite | Valor |
|---|---|
| Chamadas por minuto, por chave | 60 |
| Chaves por conta | 5 |
Passou do limite, a API responde 429 com o cabeçalho Retry-After em segundos.
Erros
Leia o campo error pra decidir o que fazer; o message é só pra humanos.
{
"error": "instance_not_connected",
"message": "This instance is not connected. Read the QR code again."
}
| HTTP | code | O que fazer |
|---|---|---|
| 400 | invalid_body | Corrija o campo citado na mensagem. |
| 402 | trial_limit | O teste vale pra uma instância por conta. Assine a primeira pra criar outras. |
| 401 | chave_invalida | Confira a chave e o prefixo Bearer. |
| 402 | payment_required | O teste acabou ou a assinatura venceu. Assine no painel. |
| 404 | instance_not_found | Confira o id da instância. |
| 409 | instance_not_connected | Peça um QR novo e conecte de novo. |
| 412 | terms_required | Aceite os termos no painel antes de assinar. |
| 422 | number_not_on_whatsapp | O número de destino não tem WhatsApp. |
| 429 | limite | Espere o Retry-After e tente de novo. |
| 429 | trial_daily_limit | No teste, cada instância manda até 100 mensagens por dia. Assine pra tirar o teto. |
Criar instância
Crie uma instância pra cada número que você vai conectar.
| Campo | Tipo | Descrição |
|---|---|---|
name | string | Nome pra você reconhecer. Ex.: loja-centro. |
webhook_url | string, opcional | URL HTTPS que recebe os eventos desta instância. |
events | array, opcional | Eventos que você quer receber. Padrão: todos. |
curl -X POST https://certu.com.br/api/v1/instances \
-H "Authorization: Bearer certu_sk_..." \
-H "Content-Type: application/json" \
-d '{"name": "loja-centro", "webhook_url": "https://seu-sistema.com/wa"}'
{
"id": "inst_8f2a",
"name": "loja-centro",
"status": "waiting_qr",
"phone": null,
"trial_ends_at": "2026-11-20T14:02:11Z",
"webhook_secret": "whsec_9d1e..."
}
Guarde o webhook_secret: ele aparece só nesta resposta e serve pra conferir a assinatura dos eventos.
Listar e consultar
Consulte o status de uma instância ou de todas da conta.
{
"id": "inst_8f2a",
"name": "loja-centro",
"status": "connected",
"phone": "5548999990000",
"connected_at": "2026-11-17T14:05:40Z"
}
Valores de status: waiting_qr, connecting, connected, disconnected, paused (teste acabou ou assinatura vencida).
QR code
Peça o QR code e mostre na sua tela; ele troca sozinho a cada poucos segundos, então peça de novo quando expires_in zerar.
{
"qr": "data:image/png;base64,iVBORw0KGgo...",
"expires_in": 20
}
Prefira o webhook instance.qr a ficar consultando: ele avisa cada QR novo assim que ele existe.
Código de pareamento
Use o código de 8 letras quando não dá pra apontar a câmera pro QR.
{ "phone": "5548999990000" }
→ { "code": "K7QM-2XPA" }
No celular: Aparelhos conectados → Conectar aparelho → Conectar com número de telefone.
Reiniciar, desconectar, apagar
Reinicie a instância quando ela parar de responder sem desconectar o número.
logout desconecta o número e mantém a instância pra conectar outro. DELETE desconecta, apaga a instância e encerra a cobrança dela no fim do ciclo.
Assinar a instância
Gere o link da fatura de R$ 48,50 por mês desta instância.
{ "payment_url": "https://www.asaas.com/i/...", "price_brl": 48.5 }
A fatura aceita PIX, boleto ou cartão, e chega todo mês no e-mail de cobrança. A instância libera assim que o pagamento confirma. Antes da primeira assinatura, aceite os termos de uso no painel: sem o aceite, a API responde 412 terms_required. Chamar de novo devolve o mesmo link, sem criar outra cobrança.
Mandar texto
Mande o número com código do país e DDD, só dígitos.
| Campo | Tipo | Descrição |
|---|---|---|
to | string | Número de destino. Ex.: 5548999990000. |
text | string | Texto da mensagem. Aceita *negrito* e _itálico_. |
reply_to | string, opcional | Id da mensagem que você está respondendo. |
curl
curl -X POST https://certu.com.br/api/v1/instances/inst_8f2a/messages/text \
-H "Authorization: Bearer certu_sk_..." \
-H "Content-Type: application/json" \
-d '{"to": "5548999990000", "text": "Seu pedido saiu para entrega."}'
Node.js
const res = await fetch(
"https://certu.com.br/api/v1/instances/inst_8f2a/messages/text",
{
method: "POST",
headers: {
Authorization: `Bearer ${process.env.CERTU_API_KEY}`,
"Content-Type": "application/json",
},
body: JSON.stringify({ to: "5548999990000", text: "Seu pedido saiu para entrega." }),
}
);
const msg = await res.json(); // { id: "msg_3Kd9x", status: "sent" }
Python
import os, requests
r = requests.post(
"https://certu.com.br/api/v1/instances/inst_8f2a/messages/text",
headers={"Authorization": f"Bearer {os.environ['CERTU_API_KEY']}"},
json={"to": "5548999990000", "text": "Seu pedido saiu para entrega."},
)
print(r.json()) # {'id': 'msg_3Kd9x', 'status': 'sent'}
Imagem, vídeo, documento
Mande a mídia por URL pública ou em base64.
{
"to": "5548999990000",
"url": "https://seu-sistema.com/boleto-123.pdf",
"filename": "boleto-123.pdf",
"caption": "Segue o boleto de novembro."
}
No lugar de url, mande base64 com o arquivo e mimetype.
Áudio de voz
Mande o áudio como mensagem de voz, com a bolinha azul de "gravado agora".
{ "to": "5548999990000", "url": "https://seu-sistema.com/aviso.mp3" }
Aceita mp3, ogg e m4a. A conversão pro formato do WhatsApp é automática.
Localização
Mande um ponto no mapa com nome e endereço.
{
"to": "5548999990000",
"latitude": -27.5954,
"longitude": -48.5480,
"name": "Loja Centro",
"address": "Rua Felipe Schmidt, 100, Florianópolis"
}
Número tem WhatsApp?
Confira antes de mandar, pra não gastar chamada com número sem WhatsApp.
{ "phone": "5548999990000", "exists": true }
Configurar os webhooks
Defina uma URL por tipo de evento. Deixe null pra não receber aquele tipo.
| Campo | Recebe |
|---|---|
received | Mensagem que chegou no número (message.received). |
sent | Resultado de cada envio pela API, enviado ou falhou (message.sent). |
status | Mensagem enviada foi entregue, lida ou ouvida (message.status). |
connected | O número conectou (instance.connected). |
disconnected | O número caiu (instance.disconnected). |
presence | O contato está digitando, gravando ou online (chat.presence). |
qr | Existe um QR code novo pra ler (instance.qr). |
{
"received": "https://seu-sistema.com/wa/recebidas",
"sent": "https://seu-sistema.com/wa/enviadas",
"status": "https://seu-sistema.com/wa/status",
"connected": null,
"disconnected": "https://seu-sistema.com/wa/alertas",
"presence": null,
"qr": null,
"notify_sent_by_me": false,
"filters": {
"ignore_groups": true,
"ignore_types": ["sticker", "reaction"],
"disabled": []
}
}
Mande só os campos que quer mudar: o resto fica como está. Use "all": "https://..." pra pôr a mesma URL em todos de uma vez.
notify_sent_by_me: manda proreceivedtambém as mensagens que o próprio número enviou (pelo celular ou pela API), com"from_me": true.filters.ignore_groups: não manda mensagem de grupo proreceived.filters.ignore_types: não manda estes tipos proreceived:text,image,video,audio,document,sticker,location,contact,reaction,other.filters.disabled: desliga tipos de webhook sem apagar a URL.
Responda 2xx em até 10 segundos. Sem resposta, reenviamos em 1 min, 5 min, 30 min, 2 h, 6 h e 24 h.
Testar um webhook
Mande um evento de exemplo agora pra conferir se o seu servidor recebe.
{ "type": "received" }
→ { "delivered": true, "status_code": 200, "url": "https://seu-sistema.com/wa/recebidas" }
O evento de teste chega assinado como os de verdade e com "test": true no corpo.
Eventos
Receba um POST com o mesmo formato em todos os eventos.
| Evento | Quando |
|---|---|
message.received | Chegou mensagem no número. |
message.sent | Uma mensagem foi enviada pela API: status é sent ou failed. |
message.status | Mensagem enviada foi entregue ou lida. |
chat.presence | O contato está digitando, gravando ou online. |
instance.qr | Existe um QR code novo pra ler. |
instance.connected | O número conectou. |
instance.disconnected | O número desconectou (saiu no celular, ficou sem internet por muito tempo ou foi banido). |
{
"event": "message.received",
"instance_id": "inst_8f2a0c1d9e",
"created_at": "2026-11-17T14:10:02Z",
"data": {
"id": "3EB0C8A1F2",
"from": "5548999990000",
"chat": "5548999990000",
"from_me": false,
"name": "Ana",
"is_group": false,
"timestamp": 1763388602,
"type": "text",
"text": "Oi, meu pedido já saiu?",
"has_media": false
}
}
O formato antigo (PUT /instances/{id}/webhook com url e events) continua valendo: ele vira a URL de todos os tipos que não têm URL própria.
Conferir a assinatura
Confira a assinatura de todo evento antes de confiar nele.
Cada requisição traz o cabeçalho Iz-Signature: t=1763388602,v1=5a3f.... Calcule um HMAC-SHA256 com o webhook_secret da instância sobre {t}.{corpo cru} e compare com v1. Recuse eventos com t mais velho que 5 minutos.
import crypto from "node:crypto";
function assinaturaValida(rawBody, header, secret) {
const { t, v1 } = Object.fromEntries(header.split(",").map(p => p.split("=")));
if (Math.abs(Date.now() / 1000 - Number(t)) > 300) return false;
const esperado = crypto.createHmac("sha256", secret).update(`${t}.${rawBody}`).digest("hex");
return crypto.timingSafeEqual(Buffer.from(esperado), Buffer.from(v1));
}