Documentação da API

API Comportamental
IACRM v1

REST API completa para integrar inteligência comportamental neural, análise de sentimento, gestão de leads, campanhas omnichannel e automações em qualquer sistema.

BASE URL https://api.iacrm.com.br/api/v1
🔐
Autenticação
JWT Bearer token ou API Key via header Authorization
📦
Formato
JSON em todas as requisições e respostas. UTF-8 obrigatório.
Latência
P95 < 150ms. Análise de sentimento: < 500ms. IA generativa: < 3s.
Autenticação

A API suporta dois métodos: JWT (para usuários do painel) e API Key (para integrações externas). Todas as requisições devem incluir o header Authorization.

JWT BearerObtido via POST /auth/login. Válido por 7 dias. Para usuários do painel admin.
API KeyGerada no painel em Configurações → API Keys. Não expira. Para integrações externas e automações.
HeaderAuthorization: Bearer {TOKEN_OU_API_KEY}
Multi-tenantO tenant é resolvido automaticamente a partir do token — nunca envie tenant_id no body.
JAVASCRIPT
// Autenticação via API Key (recomendado para integrações)
const headers = {
  'Authorization': 'Bearer sk_live_sua_api_key_aqui',
  'Content-Type': 'application/json'
};

// Autenticação via login (painel admin)
const login = async () => {
  const resp = await fetch('https://api.iacrm.com.br/api/crm/auth/login', {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify({ email: 'seu@email.com', senha: 'senha' })
  });
  const { data } = await resp.json();
  return data.token; // JWT válido por 7 dias
};
Rate Limits

Limites por plano para garantir estabilidade. Respostas com status 429 incluem o header Retry-After com o tempo de espera em segundos.

1.000req/hora · Free
5.000req/hora · Pro
IlimitadoEnterprise
RESPONSE HEADERS
X-RateLimit-Limit: 5000
X-RateLimit-Remaining: 4847
X-RateLimit-Reset: 1714000000
Retry-After: 60  // apenas em respostas 429
Erros

Todas as respostas de erro retornam JSON com o campo error descrevendo o problema.

200Sucesso
201Recurso criado
400Parâmetros inválidos
401Não autorizado
403Sem permissão
404Não encontrado
429Rate limit atingido
500Erro interno
ERROR RESPONSE
{
  "ok": false,
  "error": "nome_empresa obrigatório"
}
Auth — Login

Autentica um usuário do painel e retorna JWT com dados do tenant.

POST /api/crm/auth/login Autenticar usuário
BODY PARAMS
CampoTipoReqDescrição
emailstring*E-mail do usuário
senhastring*Senha do usuário
RESPOSTA
JSON
{
  "ok": true,
  "data": {
    "token": "eyJ...",
    "user": { "id": "uuid", "nome": "João", "papel": "admin" },
    "tenant": { "id": "uuid", "nome": "Empresa", "plano": "pro" }
  }
}
Leads

Gerencie o pipeline de leads com filtros, busca e paginação.

GET /api/crm/leads Listar leads
QUERY PARAMS
CampoTipoReqDescrição
statusstringnovo | contatado | qualificado | convertido | perdido
origemstringmanual | site | api | whatsapp | indicacao
buscastringBusca por nome, email ou whatsapp
limitintegerPadrão: 100. Máx: 500
offsetintegerPara paginação. Padrão: 0
JAVASCRIPT
const leads = await fetch('https://api.iacrm.com.br/api/v1/leads?status=novo&limit=50', {
  headers: { 'Authorization': 'Bearer SUA_API_KEY' }
});
const { data, total } = await leads.json();
// data: array de leads, total: contagem total
POST /api/crm/leads Criar lead
BODY PARAMS
CampoTipoReqDescrição
nome_empresastring*Nome da empresa do lead
emailstringE-mail de contato
whatsappstringNúmero WhatsApp (com DDD)
cidadestringCidade
ufstringEstado (ex: SP, SE)
segmentostringSegmento do lead
origemstringOrigem da captação. Padrão: "manual"
tagsstring[]Array de tags
dados_extraobjectJSON livre para campos personalizados
JAVASCRIPT
const resp = await fetch('https://api.iacrm.com.br/api/v1/leads', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer SUA_API_KEY',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    nome_empresa: 'Agência Criativa Ltda',
    email: 'contato@agencia.com.br',
    whatsapp: '79999290865',
    cidade: 'Aracaju',
    uf: 'SE',
    origem: 'site',
    tags: ['site', 'formulario'],
    dados_extra: { utm_source: 'google', utm_campaign: 'crm' }
  })
});
const { data } = await resp.json();
console.log(data.id); // UUID do lead criado
PUT /api/crm/leads/:id Atualizar lead
PATH PARAMS
CampoTipoReqDescrição
iduuid*UUID do lead
BODY PARAMS (parcial — envie apenas os campos a atualizar)
CampoTipoDescrição
statusstringnovo | contatado | qualificado | convertido | perdido
score_comportamentointeger0–100. Score neural de comportamento
tagsstring[]Substitui array de tags atual
dados_extraobjectMerge com dados_extra existente
WhatsApp

Envio de mensagens, templates e análise de sentimento via Meta Cloud API.

POST /api/crm/whatsapp/enviar Enviar mensagem
CampoTipoReqDescrição
telefonestring*Número com DDD (sem + ou espaços)
mensagemstring*Texto da mensagem livre
JAVASCRIPT
await fetch('https://api.iacrm.com.br/api/v1/whatsapp/send', {
  method: 'POST',
  headers: { 'Authorization': 'Bearer SUA_API_KEY', 'Content-Type': 'application/json' },
  body: JSON.stringify({
    telefone: '79999290865',
    mensagem: 'Olá! Vi seu interesse em nosso CRM. Posso ajudar?'
  })
});
GET /api/crm/whatsapp/contatos Listar contatos
CampoTipoDescrição
etiquetastringnovo | lead | cliente | vip | bloqueado
buscastringBusca por nome ou telefone
limitintegerPadrão: 50
POST /api/crm/whatsapp/sentimento Análise neural de sentimento
CampoTipoReqDescrição
textostringTexto a analisar. Se omitido, usa últimas msgs do contato
contato_iduuidID do contato WhatsApp para análise automática
RESPOSTA — 7 DIMENSÕES NEURAIS
JSON
{
  "ok": true,
  "data": {
    "interesse": 82,         // 0-100
    "urgencia": 58,           // 0-100
    "hesitacao": 35,          // 0-100
    "confianca": 71,          // 0-100
    "entusiasmo": 64,         // 0-100
    "frustracao": 12,         // 0-100
    "intencao_compra": 76,    // 0-100
    "perfil": "hot",           // hot | warm | cold
    "acao_recomendada": "Abordar agora com proposta",
    "confianca_modelo": 91    // precisão da análise
  }
}
Conteúdo IA Generativa

Geração automática de posts, e-mails, artigos e newsletters com Google Gemini.

POST /api/crm/conteudo/gerar Gerar conteúdo com IA
CampoTipoReqDescrição
plataformastring*instagram | linkedin | blog | email | twitter | facebook | tiktok
temastring*Tema do conteúdo a gerar
tomstringprofissional | descontraido | tecnico | inspiracional
publicostringDescrição do público-alvo
ctastringCall-to-action desejado
Jornadas Adaptativas

Inicie e gerencie automações que se adaptam ao sentimento neural em tempo real.

POST /api/crm/jornadas Iniciar jornada
CampoTipoReqDescrição
tipostring*boas_vindas | nutricao | reativacao | pos_venda | upsell | nps
emailstringE-mail do contato para a jornada
whatsappstringTelefone WhatsApp
lead_iduuidVincular a um lead existente
passosobject[]Sequência personalizada de passos
JAVASCRIPT — EXEMPLO COMPLETO
// Iniciar jornada de boas-vindas com passos customizados
await fetch('/api/crm/jornadas', {
  method: 'POST',
  headers: { 'Authorization': 'Bearer TOKEN', 'Content-Type': 'application/json' },
  body: JSON.stringify({
    tipo: 'boas_vindas',
    email: 'cliente@empresa.com',
    whatsapp: '79999290865',
    passos: [
      { canal: 'whatsapp', conteudo: 'Bem-vindo! 🎉', intervalo_horas: 0 },
      { canal: 'email', assunto: 'Primeiros passos', conteudo: '<p>...</p>', intervalo_horas: 24 },
      { canal: 'whatsapp', conteudo: 'Como está indo? Precisa de ajuda?', intervalo_horas: 72 }
    ]
  })
});
Campanhas Omnichannel

Crie e dispare campanhas em múltiplos canais com segmentação por cluster IA.

POST /api/crm/campanhas Criar campanha
CampoTipoReqDescrição
nomestring*Nome da campanha
tipostring*email | whatsapp | sms | multi
conteudostringCorpo da mensagem ou HTML
agendado_paradatetimeISO 8601. Se omitido, cria como rascunho
POST /api/crm/campanhas/:id/disparar Disparar campanha

Dispara a campanha imediatamente para todos os destinatários segmentados. O disparo é assíncrono — a requisição retorna imediatamente enquanto o envio acontece em background.

NPS / CES / CSAT

Pesquisas de satisfação com análise semântica automática das respostas abertas.

GET /api/crm/nps Listar campanhas NPS

Retorna todas as campanhas NPS com total de respostas e score calculado automaticamente.

POST /api/crm/nps/:id/responder Registrar resposta
CampoTipoReqDescrição
notainteger*0 a 10
comentariostringResposta aberta
emailstringE-mail do respondente
Dashboard

KPIs consolidados de toda a plataforma em uma única chamada.

GET /api/crm/dashboard KPIs da plataforma
RESPONSE JSON
{
  "data": {
    "leads": { "total": 2847, "porStatus": { "novo": 312 }, "scoreMedio": 64 },
    "clientes": { "total": 89, "ativos": 76, "mrr": 48320 },
    "pipeline": { "total": 143, "valor": 284000, "porEtapa": { "proposta": 28 } },
    "whatsapp": { "totalContatos": 1247, "naoLidas": 34 },
    "jornadas": { "ativas": 67, "total": 189 },
    "nps": { "score": 72 }
  }
}
Insights Comportamentais

Análise comportamental da base e consultas em linguagem natural para a IA.

POST /api/crm/insights/ia Perguntar para a IA
CampoTipoReqDescrição
perguntastring*Pergunta de negócio em linguagem natural
JAVASCRIPT
const r = await fetch('/api/crm/insights/ia', {
  method: 'POST',
  headers: { 'Authorization': 'Bearer TOKEN', 'Content-Type': 'application/json' },
  body: JSON.stringify({
    pergunta: 'Qual segmento de cliente tem a maior taxa de conversão?'
  })
});
const { data } = await r.json();
console.log(data.resposta); // resposta IA em texto
Webhooks

Configure uma URL para receber eventos em tempo real. O IACRM envia um POST com payload JSON assinado com HMAC-SHA256.

Header de validaçãoX-Webhook-Secret: {seu_secret}
EventoX-Webhook-Event: lead.novo
Timeout5 segundos. Retorne HTTP 200 imediatamente e processe de forma assíncrona.
PAYLOAD EXEMPLO
{
  "evento": "lead.novo",
  "dados": {
    "id": "uuid-do-lead",
    "nome_empresa": "Agência XYZ",
    "email": "contato@agencia.com"
  },
  "timestamp": "2026-04-25T14:30:00Z",
  "tenant_id": "uuid-do-tenant"
}
Eventos de Webhook

Todos os eventos que o IACRM pode disparar para sua URL configurada.

lead.novoNovo lead criado (manual ou via API)
lead.atualizadoStatus, score ou dados do lead atualizados
lead.convertidoLead marcado como convertido em cliente
pipeline.movidoNegócio movido para outra etapa
pipeline.fechadoNegócio fechado como ganho ou perdido
whatsapp.mensagem_recebidaNova mensagem recebida no inbox WhatsApp
jornada.concluidaJornada automática finalizada
nps.respondidoResposta de NPS registrada com score atualizado
sentimento.alertaScore de urgência ou frustração acima do threshold
SDK JavaScript

Cliente leve para Node.js e browser. Instale via npm ou copie o arquivo.

@iacrm/sdk
Wrapper oficial com TypeScript types, retry automático e helpers para análise de sentimento.
npm install @iacrm/sdk
JAVASCRIPT / NODE.JS
import { IACRM } from '@iacrm/sdk';

const crm = new IACRM({ apiKey: 'sk_live_sua_key' });

// Criar lead
const lead = await crm.leads.create({
  nome_empresa: 'Startup XYZ',
  email: 'ceo@startup.com',
  origem: 'site'
});

// Analisar sentimento
const analise = await crm.sentimento.analisar({
  texto: 'Estou muito interessado mas preciso de aprovação do board'
});
console.log(analise.perfil); // "warm"
console.log(analise.acao_recomendada); // "Enviar business case"

// Iniciar jornada
await crm.jornadas.iniciar({
  tipo: 'boas_vindas',
  email: lead.email,
  lead_id: lead.id
});
SDK Python
iacrm-python
Cliente Python com suporte a async/await e tipagem com dataclasses.
pip install iacrm
PYTHON
from iacrm import IACRM

crm = IACRM(api_key="sk_live_sua_key")

# Criar lead
lead = crm.leads.create(
    nome_empresa="Empresa ABC",
    email="contato@empresa.com",
    whatsapp="79999290865"
)

# Análise de sentimento
resultado = crm.sentimento.analisar(
    texto="Preciso urgente de uma solução, estamos perdendo clientes"
)
print(resultado.urgencia)  # 89
print(resultado.perfil)    # "hot"

# Listar leads com filtro
leads = crm.leads.listar(status="qualificado", limit=50)
for lead in leads.data:
    print(lead.nome_empresa, lead.score_comportamento)
Exemplos cURL

Chamadas diretas via terminal para testar a API rapidamente.

BASH — CRIAR LEAD
curl -X POST https://api.iacrm.com.br/api/v1/leads \
  -H "Authorization: Bearer SUA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "nome_empresa": "Empresa Teste",
    "email": "teste@empresa.com",
    "whatsapp": "79999290865",
    "origem": "api"
  }'
BASH — ANÁLISE DE SENTIMENTO
curl -X POST https://api.iacrm.com.br/api/crm/whatsapp/sentimento \
  -H "Authorization: Bearer SEU_JWT" \
  -H "Content-Type: application/json" \
  -d '{"texto": "Tenho interesse mas o budget está apertado esse trimestre"}'
BASH — GERAR CONTEÚDO IA
curl -X POST https://api.iacrm.com.br/api/v1/conteudo/gerar \
  -H "Authorization: Bearer SUA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "plataforma": "linkedin",
    "tema": "Como IA comportamental aumenta vendas em 340%",
    "tom": "profissional"
  }'
BASH — DISPARAR WHATSAPP
curl -X POST https://api.iacrm.com.br/api/v1/whatsapp/send \
  -H "Authorization: Bearer SUA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "telefone": "79999290865",
    "mensagem": "Olá! Vimos seu interesse no IACRM. Posso apresentar uma demo?"
  }'