Documentação da API Unnica

A API REST da Unnica permite integrar seu sistema externo com o CRM, enviar mensagens via WhatsApp oficial, consultar leads, disparar eventos e construir aplicações em cima da plataforma. Abaixo o guia rápido para devs começarem em 10 minutos.

Base URL e versão

Base URL da API pública: https://api.unnica.com.br/v1

Todas as requisições devem ser feitas sobre HTTPS. Versão atual v1, com depreciação anunciada com no mínimo 12 meses de antecedência.

Autenticação

A API usa Bearer Token. Gere seu token no painel em Settings, seção API Tokens. O token é exibido uma única vez, anote em lugar seguro. Inclua no header de cada requisição:

Authorization: Bearer SEU_TOKEN_AQUI
Content-Type: application/json

Tokens têm escopo (read-only, read-write, admin) e podem ser revogados a qualquer momento pelo dashboard. Para operações críticas, recomendamos rotação de token a cada 90 dias.

Rate Limits

Plano Starter: 60 requisições por minuto por token
Plano Pro: 300 requisições por minuto
Plano Business: 1.500 requisições por minuto
Plano Enterprise: limite customizado conforme contrato

Excedeu o limite? A resposta será HTTP 429 com header Retry-After indicando segundos para tentar de novo. Use exponential backoff.

Endpoints principais

Contatos

GET /contatos: lista contatos com paginação
POST /contatos: cria contato novo
GET /contatos/:id: consulta contato específico
PUT /contatos/:id: atualiza contato
DELETE /contatos/:id: soft-delete de contato

Leads e negócios

GET /leads: lista leads filtrados por etapa de funil
POST /leads: cria lead novo
PUT /leads/:id/etapa: move lead para outra etapa
POST /leads/:id/fechar: marca como ganho ou perdido

Mensagens WhatsApp

POST /mensagens/texto: envia texto simples
POST /mensagens/template: envia template aprovado
POST /mensagens/midia: envia imagem, vídeo, PDF ou áudio
GET /conversas/:id/mensagens: histórico da conversa

Disparo em massa

POST /bulk-dispatch: cria campanha de disparo em massa
GET /bulk-dispatch/:id: consulta status e resultados
POST /bulk-dispatch/:id/cancelar: cancela campanha em execução

Webhooks

Você cadastra URLs para receber eventos em tempo real da plataforma. Eventos disponíveis:

message.received: mensagem nova do cliente
message.sent: mensagem enviada pelo sistema
message.status: entrega, leitura, falha
lead.created: novo lead no CRM
lead.stage_changed: movimentação no funil
contact.created e contact.updated
conversation.assigned: atendente alocado
payment.received: pagamento confirmado (se integrado)

Eventos vêm assinados com HMAC SHA-256 no header X-Unnica-Signature. Valide a assinatura antes de processar. Timeout do webhook: 10 segundos. Retries exponenciais por 24 horas em caso de falha 5xx.

Exemplo: enviar mensagem em Node.js

const response = await fetch("https://api.unnica.com.br/v1/mensagens/texto", {
  method: "POST",
  headers: {
    "Authorization": "Bearer " + process.env.UNNICA_TOKEN,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    telefone: "5511999998888",
    texto: "Ola, sua compra foi confirmada.",
    tags: ["pos-venda", "pedido-12345"],
  }),
});

const data = await response.json();
console.log(data.mensagem_id);

Exemplo: enviar mensagem em Python

import requests
import os

response = requests.post(
    "https://api.unnica.com.br/v1/mensagens/texto",
    headers={
        "Authorization": f"Bearer {os.environ['UNNICA_TOKEN']}",
        "Content-Type": "application/json",
    },
    json={
        "telefone": "5511999998888",
        "texto": "Ola, sua compra foi confirmada.",
        "tags": ["pos-venda", "pedido-12345"],
    },
)

data = response.json()
print(data["mensagem_id"])

Exemplo: receber webhook em PHP

<?php
$body = file_get_contents("php://input");
$signature = $_SERVER["HTTP_X_UNNICA_SIGNATURE"] ?? "";
$secret = getenv("UNNICA_WEBHOOK_SECRET");

$expected = hash_hmac("sha256", $body, $secret);
if (!hash_equals($expected, $signature)) {
    http_response_code(401);
    exit;
}

$event = json_decode($body, true);
if ($event["type"] === "message.received") {
    // processa mensagem nova
}

http_response_code(200);
echo "ok";

Erros e códigos HTTP

200 OK: sucesso
201 Created: recurso criado
400 Bad Request: payload malformado ou campo inválido
401 Unauthorized: token ausente ou inválido
403 Forbidden: token sem escopo necessário
404 Not Found: recurso inexistente
429 Too Many Requests: rate limit atingido
500 Internal Server Error: erro nosso, reporte imediatamente

Changelog

Mudanças na API são publicadas no changelog em api.unnica.com.br/changelog. Breaking changes são anunciadas com 6 meses de antecedência para parceiros e com 12 meses antes de deprecar endpoint antigo.

Suporte para devs

Canal técnico dedicado: dev-support@unnica.com.br. SLA de resposta 24h úteis. Para clientes Enterprise, canal direto com engenheiro no Slack privado.

Próximos passos

Criar conta grátis e gerar token de API
Ver integrações prontas antes de construir do zero
Falar com time comercial para cenário enterprise