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
statusstring—novo | contatado | qualificado | convertido | perdido
origemstring—manual | site | api | whatsapp | indicacao
buscastring—Busca por nome, email ou whatsapp
limitinteger—Padrão: 100. Máx: 500
offsetinteger—Para 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
emailstring—E-mail de contato
whatsappstring—Número WhatsApp (com DDD)
cidadestring—Cidade
ufstring—Estado (ex: SP, SE)
segmentostring—Segmento do lead
origemstring—Origem da captação. Padrão: "manual"
tagsstring[]—Array de tags
dados_extraobject—JSON 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
textostring—Texto a analisar. Se omitido, usa últimas msgs do contato
contato_iduuid—ID 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
tomstring—profissional | descontraido | tecnico | inspiracional
publicostring—Descrição do público-alvo
ctastring—Call-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
emailstring—E-mail do contato para a jornada
whatsappstring—Telefone WhatsApp
lead_iduuid—Vincular 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
conteudostring—Corpo da mensagem ou HTML
agendado_paradatetime—ISO 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
comentariostring—Resposta aberta
emailstring—E-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?"
  }'