Guia de Integração

1. Criar a chave de API

1. Entre no Anil CRM e vá em Configurações → Chaves de API.
2. Clique em Nova chave, dê um nome que diga para que ela serve (ERP produção, integração teste) e marque só os escopos que a integração realmente precisa.
3. Copie a chave agora. Ela aparece uma única vez e não pode ser recuperada depois — nem por quem a criou. Se perder, revogue e crie outra.

2. Autenticar

Mande a chave no cabeçalho Authorization, em toda requisição.

curl https://api.msgflowapp.com.br/v1/me \
  -H "Authorization: Bearer anil_live_xxxxxxxx_sua_chave_aqui"

A resposta confirma a credencial e mostra o alcance dela:

{
  "tenantId": "...",
  "tenant": {                  // a organização desta chave, por extenso
    "id": "...",
    "name": "Difafá Cosméticos",
    "slug": "difafa-cosmeticos"
  },
  "key": { "id": "...", "name": "ERP produção", "prefix": "anil_live_xxxxxxxx" },
  "scopes": ["contacts:read", "messages:send"],
  "channelIds": [],            // vazio = todos os canais
  "owner": { "id": "...", "role": "ADMIN" }
}

Chame este endpoint primeiro, sempre. Ele é a resposta rápida para "por que deu 401?" e para "esta chave é da empresa certa?".

Fixar a organização esperada (opcional)

Se você administra mais de uma empresa, um risco real é usar a chave de uma no ambiente de outra — e a requisição funcionar, agindo no lugar errado sem nenhum sinal. Para fechar isso, mande junto o cabeçalho X-Anil-Org com o slug da organização que você espera:

curl https://api.msgflowapp.com.br/v1/me   -H "Authorization: Bearer SUA_CHAVE"   -H "X-Anil-Org: difafa-cosmeticos"

Se a chave for de outra empresa, a requisição para com 403 e a mensagem diz quais são as duas. O slug sai do slug em /v1/me.

É opcional e compatível: integração que não manda o cabeçalho continua funcionando igual. Vale a pena quando o mesmo código roda contra empresas diferentes, ou entre ambientes de teste e produção.

3. Escopos

O escopo diz o que a chave faz; o papel de quem a emitiu diz até onde ela enxerga. Os dois se somam. Chamar uma rota sem o escopo dela devolve 403 nomeando o que falta.

4. Endpoints

Contatos

A listagem aceita search, labelId, page e limit.

Conversas e atendimento

assign recebe { "userId": "..." }. transfer-sector recebe { "sectorId": "..." }, ou null para tirar do setor. Para desatribuir use /unassign — não um null no assign.

Mensagens

/download devolve { url, fileName } — uma URL assinada e temporária, não os bytes. Baixe a partir dela.

Etiquetas

Relatórios

/reports/filters devolve os canais, setores e atendentes disponíveis — use para montar os filtros das outras rotas de relatório.

Organização e campanhas (leitura)

5. Abrir conversa com um número novo

Toda mensagem sai dentro de uma conversa. Se a pessoa já falou com você, a conversa existe — pegue o id dela em GET /v1/conversations e pule para o envio.

Se ela nunca falou com você, abra a conversa primeiro:

curl -X POST https://api.msgflowapp.com.br/v1/conversations \
  -H "Authorization: Bearer SUA_CHAVE" \
  -H "Content-Type: application/json" \
  -d '{
    "channelId": "uuid-do-canal",
    "phone": "5517999998888",
    "name": "Nadine"
  }'

Responde 201 com a conversa. Use o id dela para enviar. O channelId — ou seja, por qual número seu a conversa vai sair — você pega em GET /v1/channels. O name é opcional e só vale se o contato ainda não existir.

6. Enviar mensagem

curl -X POST https://api.msgflowapp.com.br/v1/conversations/CONV_ID/messages \
  -H "Authorization: Bearer SUA_CHAVE" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: pedido-4821-confirmado" \
  -d '{"content": "Seu pedido saiu para entrega!"}'

Para imagem, áudio ou documento veja enviar mídia.

7. Enviar mídia

São dois passos: você pede uma URL de upload, manda o arquivo direto para o storage, e depois envia a mensagem citando a chave que recebeu. O arquivo nunca passa pela API — por isso funciona com arquivo grande.

Passo 1 — pedir a URL

curl -X POST https://api.msgflowapp.com.br/v1/media/upload-url \
  -H "Authorization: Bearer SUA_CHAVE" \
  -H "Content-Type: application/json" \
  -d '{"filename": "boleto.pdf", "contentType": "application/pdf"}'

# → { "uploadUrl": "https://...", "mediaKey": "...", "expiresInSec": 300 }

Passo 2 — subir o arquivo

curl -X PUT "$UPLOAD_URL" \
  -H "Content-Type: application/pdf" \
  --data-binary @boleto.pdf

Use PUT, e o mesmo Content-Type que você informou no passo 1. A URL vale 5 minutos.

Passo 3 — enviar

curl -X POST https://api.msgflowapp.com.br/v1/conversations/CONV_ID/messages/media \
  -H "Authorization: Bearer SUA_CHAVE" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: boleto-4821" \
  -d '{
    "type": "DOCUMENT",
    "mediaKey": "a-key-do-passo-1",
    "fileName": "boleto.pdf",
    "caption": "Segue o boleto"
  }'

8. Template — falar depois das 24h

No canal Oficial, se o contato não te responde há mais de 24 horas, mensagem comum é recusada com 422. O único jeito de falar com ele é um template aprovado pela Meta.

curl -X POST https://api.msgflowapp.com.br/v1/conversations/CONV_ID/messages/template \
  -H "Authorization: Bearer SUA_CHAVE" \
  -H "Content-Type: application/json" \
  -d '{
    "templateName": "confirmacao_pedido",
    "languageCode": "pt_BR",
    "bodyParams": ["Nadine", "4821"]
  }'

bodyParams preenche {{1}}, {{2}}… na ordem. O template precisa estar aprovado na Meta antes.

9. Campanhas — o caminho seguro para volume

Criar

curl -X POST https://api.msgflowapp.com.br/v1/campaigns \
  -H "Authorization: Bearer SUA_CHAVE" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Promo de setembro",
    "channelId": "uuid-do-canal",
    "contentMode": "TEXT",
    "messageText": "Oi {nome}! Temos novidade.",
    "recipientSource": "SEGMENT",
    "segmentLabelIds": ["uuid-da-etiqueta"],
    "minDelaySec": 30,
    "maxDelaySec": 60,
    "sendWeekdays": [1,2,3,4,5],
    "sendHours": [9,10,11,14,15,16],
    "dailyLimit": 200
  }'

Ela nasce em DRAFT — criar não dispara. Confira e então dispare:

curl -X POST https://api.msgflowapp.com.br/v1/campaigns/ID/dispatch \
  -H "Authorization: Bearer SUA_CHAVE"

10. Idempotência

Rede falha e bibliotecas HTTP repetem requisição sozinhas. Sem proteção, um retry de "enviar mensagem" vira mensagem duplicada no WhatsApp de uma pessoa real — dano visível e que não dá para desfazer.

Mande o cabeçalho Idempotency-Key com um valor único por operação (o id do pedido no seu sistema serve bem). Repetir a mesma chave devolve o mesmo resultado, sem executar de novo.

11. Limites de uso

O limite é por chave, não por IP — sua integração sai de um servidor só e não seria justo dividir balde com terceiros. Janela de 1 minuto.

12. Erros

Todo erro devolve JSON no formato { "error": "mensagem" }.

13. Webhooks

Em vez de ficar perguntando "tem novidade?", receba um POST assim que algo acontece. Cadastre o endpoint em Configurações → Webhooks e guarde o segredo que aparece na criação — ele também só é mostrado uma vez.

Validar a assinatura

Toda entrega leva a assinatura do corpo. Valide sempre — sem isso qualquer um que descubra sua URL pode postar nela.

// Node.js — assine o corpo CRU, antes de qualquer parse
const assinatura = 'sha256=' + crypto
  .createHmac('sha256', SEU_SEGREDO)
  .update(`${timestamp}.${corpoCru}`)
  .digest('hex')

// compare com o cabeçalho recebido, em tempo constante
crypto.timingSafeEqual(Buffer.from(assinatura), Buffer.from(recebido))

Entrega e retentativa

Responda 2xx rápido — processe depois, em fila sua. Falhou, tentamos 5 vezes com espera crescente. Depois de 10 falhas seguidas o endpoint é desativado automaticamente e você recebe aviso na tela; é só arrumar e reativar, que o contador zera. O histórico de cada entrega fica visível em Configurações → Webhooks.

14. Conectar ao Claude (MCP)

O Anil expõe um servidor MCP, o padrão que o Claude usa para falar com sistemas externos. Com ele você conversa com o CRM em linguagem natural: "quantas conversas estão na fila do setor de vendas?", "resume o atendimento do contato X".

No Claude, adicione um conector com:

Autentique com a mesma chave de API, no cabeçalho Authorization: Bearer. A URL exata da sua organização aparece em Configurações → Chaves de API, ao lado da chave — copie as duas do mesmo lugar.

O endereço antigo /mcp, sem a organização, continua funcionando para quem já tem um conector configurado.

São 29 ferramentas: ler contatos, conversas, mensagens, relatórios e campanhas; aplicar etiqueta; atribuir e finalizar atendimento; enviar mensagem e template; abrir conversa; e criar, disparar, pausar ou cancelar campanha.