RotaISP Conecta: API pública v1

Envio de mensagens do WhatsApp oficial (templates aprovados pela Meta) a partir do ERP do provedor. Autenticação por chave de API (criada no painel do Conecta, em "API e webhook"), idempotência obrigatória e aviso de status assinado (HMAC-SHA256).

Endereço: https://api.conecta.rotaisp.com.br · Especificação OpenAPI: GET /v1/openapi.json

Autenticação

Authorization: Bearer rck_... (ou o cabeçalho X-Api-Key). Escopos: mensagens:enviar, mensagens:ler. A chave aparece uma vez só, ao ser criada no painel; guarde-a como senha. Chave ausente, inválida, revogada ou de provedor suspenso recebe sempre o mesmo 401.

Idempotência

Todo POST /v1/mensagens leva o cabeçalho Idempotency-Key. Repetir o pedido com a mesma chave e o mesmo corpo devolve a mesma mensagem (com Idempotent-Replayed: true), mesmo que os pedidos cheguem ao mesmo tempo; nada é enviado duas vezes. A mesma chave com outro corpo recebe 409.

A chave vale numa janela de 7 dias, contados do aceite do pedido. Depois disso o Conecta apaga o resumo do pedido, e a mesma chave é tratada como um pedido novo: repetir um pedido antigo com a mesma chave gera outra mensagem. Use uma chave nova para cada mensagem (por exemplo, o número da fatura com a data).

Limite de requisições

Há um limite de requisições por minuto para cada chave. Os cabeçalhos RateLimit-Limit e RateLimit-Remaining mostram o limite e o que resta; ao passar dele, 429 com Retry-After (segundos).

Rotas

{
  "numero": "109876543210987",
  "para": "5573999990000",
  "template": "cobranca_pix",
  "idioma": "pt_BR",
  "variaveis": [
    "Maria",
    "R$ 99,90"
  ],
  "documento": {
    "url": "https://erp.provedor.example.com/boletos/48211907.pdf",
    "nomeArquivo": "boleto-48211907.pdf"
  },
  "pix": {
    "codigo": "00020101021226850014br.gov.bcb.pix2563pix.example.com/qr/v2/cobv/9d36b84f5204000053039865802BR6304ABCD",
    "chave": "12345678000199",
    "recebedor": "Provedor Exemplo",
    "referencia": "48211907",
    "descricao": "Fatura Internet",
    "valorCentavos": 9990
  },
  "boleto": {
    "linhaDigitavel": "23793.38128 60000.000003 00000.000400 1 84340000009990"
  }
}

A mensagem (resposta do POST, do GET e do aviso)

Aviso de status (webhook)

Um POST por mudança de status (ENVIADO, ENTREGUE, LIDO ou FALHA). Assinatura: X-Conecta-Assinatura: v1=<hex>, o HMAC-SHA256 com o segredo do webhook sobre <X-Conecta-Timestamp>.<corpo cru>. Recuse assinatura errada e timestamp com mais de 300 s de diferença, e tire duplicata pelo X-Conecta-Evento. Responda 2xx. Sem 2xx (ou sem resposta em 10 s), o aviso é reenviado com espera crescente (1, 5, 15, 60, 180, 720 min), até 7 tentativas; por isso um aviso pode chegar depois de outro mais novo: use a ordem ENVIADO < ENTREGUE < LIDO (FALHA é final).

Aviso de número pausado ou liberado (webhook)

Quando a Meta indica que UM número não pode enviar mensagens (com a conta liberada), o Conecta pausa só esse número: as mensagens por ele ficam na fila (até 24 horas) e os outros números da conta continuam enviando. Chega um aviso com numero.envios PAUSADO e o motivo. A pausa só sai quando um administrador do provedor clica em "Já corrigi, retomar este número" no painel; aí chega o aviso LIBERADO. Mesmos cabeçalhos, mesma assinatura e mesmas novas tentativas do aviso de status.

Conferir a assinatura (Node.js)

const crypto = require("node:crypto");

// corpoCru: o corpo EXATO recebido (Buffer ou string), antes de qualquer JSON.parse.
function avisoDoConectaValido(corpoCru, cabecalhos, segredo, toleranciaSeg = 300) {
  const ts = Number(cabecalhos["x-conecta-timestamp"]);
  const recebida = String(cabecalhos["x-conecta-assinatura"] || "");
  if (!Number.isInteger(ts) || Math.abs(Date.now() / 1000 - ts) > toleranciaSeg) return false;
  const esperada = "v1=" + crypto.createHmac("sha256", segredo).update(ts + ".").update(corpoCru).digest("hex");
  return esperada.length === recebida.length && crypto.timingSafeEqual(Buffer.from(esperada), Buffer.from(recebida));
}