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úmeroO que significa
R$ 48,50 por mêsGere o link da fatura de R$ 48,50 por mês desta instância.
10 segundosResponda 2xx em até 10 segundos.

Início rápido

Siga os quatro passos abaixo e mande a primeira mensagem em poucos minutos.

  1. Crie a conta no painel e copie a chave de teste (certu_sk_test_...) ou de produção (certu_sk_...).
  2. Crie uma instância com POST /instances.
  3. Pegue o QR code com GET /instances/{id}/qr e leia no celular, em Aparelhos conectados.
  4. Quando o webhook instance.connected chegar, mande a primeira mensagem com POST /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.

A chave de teste (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.

LimiteValor
Chamadas por minuto, por chave60
Chaves por conta5

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."
}
HTTPcodeO que fazer
400invalid_bodyCorrija o campo citado na mensagem.
402trial_limitO teste vale pra uma instância por conta. Assine a primeira pra criar outras.
401chave_invalidaConfira a chave e o prefixo Bearer.
402payment_requiredO teste acabou ou a assinatura venceu. Assine no painel.
404instance_not_foundConfira o id da instância.
409instance_not_connectedPeça um QR novo e conecte de novo.
412terms_requiredAceite os termos no painel antes de assinar.
422number_not_on_whatsappO número de destino não tem WhatsApp.
429limiteEspere o Retry-After e tente de novo.
429trial_daily_limitNo 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.

POST/instances
CampoTipoDescrição
namestringNome pra você reconhecer. Ex.: loja-centro.
webhook_urlstring, opcionalURL HTTPS que recebe os eventos desta instância.
eventsarray, opcionalEventos 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.

GET/instances
GET/instances/{id}
{
  "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.

GET/instances/{id}/qr
{
  "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.

POST/instances/{id}/pairing-code
{ "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.

POST/instances/{id}/restart
POST/instances/{id}/logout
DELETE/instances/{id}

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.

POST/instances/{id}/subscribe
{ "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.

POST/instances/{id}/messages/text
CampoTipoDescrição
tostringNúmero de destino. Ex.: 5548999990000.
textstringTexto da mensagem. Aceita *negrito* e _itálico_.
reply_tostring, opcionalId 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.

POST/instances/{id}/messages/image
POST/instances/{id}/messages/video
POST/instances/{id}/messages/document
{
  "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".

POST/instances/{id}/messages/audio
{ "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.

POST/instances/{id}/messages/location
{
  "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.

GET/instances/{id}/numbers/{phone}
{ "phone": "5548999990000", "exists": true }

Configurar os webhooks

Defina uma URL por tipo de evento. Deixe null pra não receber aquele tipo.

GET/instances/{id}/webhooks
PUT/instances/{id}/webhooks
CampoRecebe
receivedMensagem que chegou no número (message.received).
sentResultado de cada envio pela API, enviado ou falhou (message.sent).
statusMensagem enviada foi entregue, lida ou ouvida (message.status).
connectedO número conectou (instance.connected).
disconnectedO número caiu (instance.disconnected).
presenceO contato está digitando, gravando ou online (chat.presence).
qrExiste 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.

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.

POST/instances/{id}/webhooks/test
{ "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.

EventoQuando
message.receivedChegou mensagem no número.
message.sentUma mensagem foi enviada pela API: status é sent ou failed.
message.statusMensagem enviada foi entregue ou lida.
chat.presenceO contato está digitando, gravando ou online.
instance.qrExiste um QR code novo pra ler.
instance.connectedO número conectou.
instance.disconnectedO 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));
}
Use a API pra conversar com quem já fala com você: atendimento, avisos de pedido, cobrança, agendamento. Disparo em massa pra lista fria leva o número a ser banido pelo WhatsApp e vai contra os termos da Certu.