Como o seu sistema se integra ao Canal API Oficial
Guia de uma página para quem vai programar a integração. Referência completa em /docs. Endereço da API: https://canalapioficial.solucoesdeia.com.
O que vocês recebem de nós
- Um número de WhatsApp conectado à API oficial da Meta, na conta Meta de vocês. A Meta cobra direto no meio de pagamento de vocês; nós não cobramos por mensagem.
- Uma credencial:
client_ideclient_secret. O segredo é mostrado uma vez só. Guarde no cofre de segredos do seu sistema, nunca no código ou no navegador. - Opcionalmente, uma credencial de teste (modo sandbox): funciona igual, mas nada vai para a Meta e os status são simulados.
1. Pegar o token de acesso
Troque a credencial por um token que vale 1 hora. Reaproveite o token até perto de vencer; quando receber 401, peça outro.
curl -s -X POST https://canalapioficial.solucoesdeia.com/oauth/token \
-d grant_type=client_credentials \
-d client_id=SEU_CLIENT_ID \
-d client_secret=SEU_CLIENT_SECRET
# resposta
{"access_token":"cat_live_...","token_type":"Bearer","expires_in":3600,"scope":"messages:send messages:read ..."}Cada credencial tem escopos (o que pode fazer), limite por minuto e, se quiserem, lista de IPs. Uma credencial revogada para de funcionar na hora.
2. Conferir os templates
Mensagem que começa a conversa precisa de template aprovado pela Meta. GET /v1/templates?status=approved lista os aprovados e GET /v1/templates/{id}/schema diz quais variáveis cada um pede, de que tipo e quais são obrigatórias. Templates novos: POST /v1/templates (a aprovação chega no webhook template.status).
3. Enviar
curl -s -X POST https://canalapioficial.solucoesdeia.com/v1/messages \
-H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
-d '{
"to": "5561999990000",
"client_message_id": "reserva-4471-confirmacao",
"template": {
"name": "confirmacao_reserva",
"language": "pt_BR",
"variables": { "nome": "Carla", "checkin": "2026-12-20", "valor": 128000 },
"buttons": { "url_suffix": "4471" }
},
"metadata": { "reserva": "4471" }
}'
# resposta 202
{"id":"0d7e...","status":"queued","to":"5561999990000","client_message_id":"reserva-4471-confirmacao", ...}- Variáveis com tipo: valores em dinheiro vão em centavos (128000 = R$ 1.280,00) e datas em AAAA-MM-DD; nós formatamos do jeito do template.
- client_message_id: use o id do seu sistema. Se a rede cair e vocês repetirem, a resposta volta igual com
idempotent_replayed: truee nada é enviado duas vezes. - Testar antes:
POST /v1/messages?dry_run=truevalida tudo e devolve a categoria, o custo estimado da Meta e quanto o número ainda pode enviar hoje. - Texto livre (sem template) só dentro de 24 horas depois da última mensagem do cliente. Botões: até 3. Lista: até 10 opções.
- Documento no cabeçalho:
header.document.url+filename, ou suba antes emPOST /v1/mediae use omedia_id.
4. Receber os eventos no seu sistema
Cadastre o endereço do seu sistema em POST /v1/webhooks (ou peça para nós). Mandamos um POST para cada evento: message.queued, message.sent, message.delivered, message.read, message.failed (com o código de erro da Meta), message.received, button.clicked, contact.opted_out, template.status.
Responda 200 em até 8 segundos e processe depois. Se o seu sistema estiver fora, tentamos de novo em 1 min, 5 min, 30 min, 2 h e 6 h; nada se perde e dá para reenviar depois.
// Node.js: conferir a assinatura do webhook
import { createHmac, timingSafeEqual } from "node:crypto";
function assinaturaValida(corpoCru, cabecalhos, segredo) {
const ts = cabecalhos["x-canal-timestamp"];
const esperado = "v1=" + createHmac("sha256", segredo).update(ts + "." + corpoCru).digest("hex");
const veio = cabecalhos["x-canal-signature"] ?? "";
const recente = Math.abs(Date.now() / 1000 - Number(ts)) < 300; // até 5 minutos
return recente && veio.length === esperado.length && timingSafeEqual(Buffer.from(veio), Buffer.from(esperado));
}Recuse (401) qualquer chamada com assinatura errada ou horário com mais de 5 minutos de diferença. Se preferirem não receber webhook, tudo fica guardado e pode ser consultado em GET /v1/messages.
5. Disparo por evento (opcional)
Em vez de montar a mensagem, o sistema de vocês avisa o que aconteceu e nós usamos o template configurado para aquele evento (POST /v1/event-triggers):
curl -s -X POST https://canalapioficial.solucoesdeia.com/v1/events \
-H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
-d '{"event":"checkout_realizado","to":"5561999990000","client_message_id":"checkout-4471",
"variables":{"nome":"Carla","total":245000,"link_pagamento":"pix-4471"}}'Regras que evitam problema
- Quem responde SAIR (ou PARAR) deixa de receber: o envio volta
contact_opted_out. Registrem também pelo seu sistema emPOST /v1/contacts/{telefone}/opt-out. - Enviado não é entregue: confiem em
message.deliveredemessage.read. - O número tem um limite diário de contatos novos (começa em 250 e sobe com a verificação da empresa e boa qualidade). Marketing em excesso derruba a qualidade.
- Erro 131042 é problema de pagamento na conta Meta de vocês: confiram o cartão no Gerenciador de Negócios. Nós avisamos quando aparecer.