API Reference

🔌 Athix REST API

Todos os endpoints abaixo são servidos pela instância local do Athix. Use a URL base http://localhost:5004 para integrar com o n8n via nó HTTP Request.

Os endpoints retornam JSON (exceto /api/export.csv). Nenhuma autenticação é necessária na rede local.

💡 Como usar no n8n: No nó HTTP Request, configure o campo URL com http://SEU_IP:5004/api/records?pageSize=100. O retorno em data[] contém os leads prontos para usar em automações de e-mail, WhatsApp ou CRM. Use o nó Split In Batches para processar registro a registro.

📐 Estrutura do Registro (Lead)

Todos os campos retornados por /api/records, /api/records/emails e /api/records/phones.

Objeto record

Campo	Tipo	Descrição	Exemplo
cnpj	string	CNPJ bruto (14 dígitos)	00000000000191
razao_social	string	Razão social da empresa	BANCO DO BRASIL SA
nome_fantasia	string	Nome fantasia	BB
situacao_cadastral	string	Situação na Receita Federal	ATIVA
municipio	string	Município sede	CUIABA
uf	string	UF (estado)	MT
cnae_principal	string	Código CNAE principal	6422100
cnae_descricao	string	Descrição do CNAE (IBGE)	Bancos múltiplos, com carteira comercial
cnae_secundarios	array	Lista de CNAEs secundários `{code, description}`	[{"code":"6421200","description":"..."}]
email1	string	E-mail principal (lowercase)	contato@empresa.com.br
email_verified	string	Status de verificação DNS do e-mail	valid \| invalid \| unchecked
telefones	string[]	Telefones formatados	["(65) 33339999"]
whatsapp_phones	array	Todos os celulares `{phone, display}`	[{"phone":"5565999999999","display":"(65) 999999999"}]
whatsapp_phone	string	Melhor número WhatsApp (55DDNNN…)	5565999999999
whatsapp_verified	string	Status verificação WhatsApp	valid \| mobile \| invalid \| unchecked
crm_status	string	Status no CRM interno	novo \| contatado \| interessado \| fechado \| descartado
crm_note	string	Anotação livre no CRM	Ligar segunda-feira
crm_follow_up	string	Data de follow-up agendado	2025-06-01
crm_updated_at	string\|null	ISO timestamp da última atualização CRM	2025-05-10T14:22:00.000Z

📋 Leads / Registros

GET /api/records Listar leads com filtros e paginação ▼

Query Parameters

Parâmetro	Tipo	Req.	Descrição
page	number	opcional	Página (padrão: 1)
pageSize	number	opcional	Registros por página, máx 5000 (padrão: 50)
all	boolean	opcional	Se `true`, retorna todos sem paginação
search	string	opcional	Busca livre por CNPJ, razão social, município, CNAE, e-mail
uf	string	opcional	Filtro por UF (ex: `MT`)
municipio	string	opcional	Filtro por município (case-insensitive)
situacao	string	opcional	Situação cadastral (ex: `ATIVA`)
cnae	string	opcional	Código CNAE (principal ou secundário)
cnaeDescricao	string	opcional	Busca parcial na descrição do CNAE
hasEmail	boolean	opcional	`true` = só com e-mail, `false` = sem e-mail
hasPhone	boolean	opcional	`true` = só com celular para WhatsApp
emailValid	boolean	opcional	`true` = só e-mails verificados como válidos
wpValid	boolean	opcional	`true` = só WhatsApp verificados como válidos
crmStatus	string	opcional	Filtrar por status CRM: `novo` `contatado` `interessado` `fechado` `descartado`
listId	string	opcional	ID de uma lista salva — usa os membros da lista como fonte

Response 200

{
  "total":      1250,
  "page":       1,
  "pageSize":   50,
  "totalPages": 25,
  "data": [
    {
      "cnpj":              "00000000000191",
      "razao_social":     "BANCO DO BRASIL SA",
      "nome_fantasia":    "BB",
      "situacao_cadastral":"ATIVA",
      "municipio":        "CUIABA",
      "uf":               "MT",
      "cnae_principal":   "6422100",
      "cnae_descricao":   "Bancos múltiplos, com carteira comercial",
      "cnae_secundarios": [{ "code": "6421200", "description": "..." }],
      "email1":           "contato@bb.com.br",
      "email_verified":   "valid",
      "telefones":        ["(65) 99999-0001"],
      "whatsapp_phones":  [{ "phone": "5565999990001", "display": "(65) 999990001" }],
      "whatsapp_phone":   "5565999990001",
      "whatsapp_verified":"mobile",
      "crm_status":       "novo",
      "crm_note":         "",
      "crm_follow_up":    "",
      "crm_updated_at":   null
    }
  ]
}

GET /api/records/emails Lista e-mails para campanhas ▼

Query Parameters

Aceita os mesmos filtros de /api/records (exceto paginação).

Response 200

{
  "total": 320,
  "data": [
    {
      "cnpj":         "00000000000191",
      "email":        "contato@bb.com.br",
      "razao_social": "BANCO DO BRASIL SA"
    }
  ]
}

GET /api/records/phones Lista telefones/WhatsApp ▼

Query Parameters

Aceita os mesmos filtros de /api/records.

Response 200

{
  "total": 410,
  "data": [
    {
      "cnpj":         "00000000000191",
      "razao_social": "BANCO DO BRASIL SA",
      "phone":        "5565999990001",
      "display":      "(65) 999990001",
      "all_phones":   ["(65) 99999-0001"]
    }
  ]
}

GET /api/export.csv Exportar leads como CSV ▼

Query Parameters

Parâmetro	Tipo	Req.	Descrição
fields	string	opcional	Campos separados por vírgula. Padrão: `cnpj,razao_social,email,phones,municipio,uf`. Valores possíveis: `cnpj` `razao_social` `nome_fantasia` `email` `email_verified` `cnae` `cnae_descricao` `phones` `whatsapp` `whatsapp_verified` `municipio` `uf`

Response

Retorna arquivo text/csv para download direto.

GET /api/options Valores únicos para filtros ▼

Response 200

{
  "ufs":       ["GO", "MT", "SP"],
  "municipios":["CAMPO VERDE", "CUIABA", "SINOP"],
  "situacoes": ["ATIVA", "BAIXADA", "INAPTA"]
}

🗂️ Datasets

GET /api/datasets Lista datasets (local + Digital Ocean) ▼

Response 200

{
  "active": "datasets/mt/cuiaba.json",
  "local": [
    { "key": "datasets/mt/cuiaba.json", "label": "cuiaba.json", "source": "local" }
  ],
  "remote": [
    { "key": "br/mt/cuiaba.json", "label": "cuiaba.json", "source": "spaces" }
  ]
}

GET /api/datasets/tree Árvore hierárquica estado/cidade ▼

Response 200

{
  "active": "datasets/mt/cuiaba.json",
  "tree": {
    "mt": {
      "cuiaba": { "key": "datasets/mt/cuiaba.json", "source": "local" },
      "sinop":  { "key": "br/mt/sinop-mt.json",   "source": "spaces" }
    },
    "go": {
      "ipora":  { "key": "datasets/go/ipora.json",  "source": "local" }
    }
  }
}

POST /api/datasets/switch Ativar dataset (baixa do DO se necessário) ▼

Request Body (JSON)

Campo	Tipo	Req.	Descrição
key	string	obrig.	Caminho do dataset (ex: `br/mt/cuiaba.json` ou `datasets/mt/cuiaba.json`)

Response 200

{ "ok": true, "loaded": "datasets/mt/cuiaba.json", "records": 5430 }

📌 Listas Salvas

GET /api/lists Retorna todas as listas salvas ▼

Response 200

[
  {
    "id":         "list_abc123",
    "name":       "Clientes MT - Ativas",
    "createdAt":  "2025-05-01T10:00:00.000Z",
    "count":      87,
    "members": {
      "00000000000191": { /* snapshot do lead */ }
    }
  }
]

POST /api/lists/save Criar / atualizar lista ▼

Request Body (JSON)

Campo	Tipo	Req.	Descrição
name	string	obrig.	Nome da lista
cnpjs	string[]	obrig.	Array de CNPJs para adicionar
listId	string	opcional	ID de lista existente (para atualizar)

Response 200

{ "ok": true, "id": "list_abc123", "added": 5, "skipped": 1 }

DELETE /api/lists/:id Remover lista salva ▼

URL Parameter

Parâmetro	Tipo	Req.	Descrição
id	string	obrig.	ID da lista (ex: `list_abc123`)

Response 200

{ "ok": true }

🗂️ CRM

GET /api/crm/all Todos os status CRM ▼

Response 200

{
  "00000000000191": {
    "status":       "contatado",
    "note":         "Ligar segunda",
    "followUpDate": "2025-06-01",
    "updatedAt":    "2025-05-10T14:22:00.000Z"
  }
}

GET /api/crm/status/:cnpj Status CRM de um CNPJ ▼

URL Parameter

Parâmetro	Tipo	Req.	Descrição
cnpj	string	obrig.	CNPJ da empresa (14 dígitos, sem formatação)

Response 200

{
  "cnpj":        "00000000000191",
  "status":      "contatado",
  "note":        "Ligar segunda",
  "followUpDate":"2025-06-01",
  "updatedAt":   "2025-05-10T14:22:00.000Z"
}

POST /api/crm/status Atualizar status CRM de um lead ▼

💡 n8n: Use este endpoint para atualizar o CRM automaticamente após enviar um e-mail ou mensagem. Exemplo: após enviar WhatsApp, faça POST aqui com status: "contatado".

Request Body (JSON)

Campo	Tipo	Req.	Descrição
cnpj	string	obrig.	CNPJ da empresa
status	string	obrig.	`novo` `contatado` `interessado` `fechado` `descartado`
note	string	opcional	Anotação livre
followUpDate	string	opcional	Data de follow-up (YYYY-MM-DD)

Response 200

{ "ok": true, "cnpj": "00000000000191", "status": "contatado" }

📣 Campanhas

GET /api/campaigns Listar todas as campanhas ▼

Response 200

[
  {
    "id":         "camp_xyz789",
    "name":       "Promoção Maio",
    "channel":    "email",
    "status":     "running",
    "sentCount":  150,
    "totalCount": 320,
    "createdAt":  "2025-05-01T08:00:00.000Z"
  }
]

PATCH /api/campaigns/:id/status Pausar / retomar campanha ▼

Request Body (JSON)

Campo	Tipo	Req.	Descrição
status	string	obrig.	`paused` ou `running`

Response 200

{ "ok": true, "id": "camp_xyz789", "status": "paused" }

✉️ Email

POST /api/email/send Enviar e-mail imediatamente ▼

Request Body (JSON)

Campo	Tipo	Req.	Descrição
to	string	obrig.	E-mail do destinatário
subject	string	obrig.	Assunto do e-mail
html	string	obrig.	Corpo HTML do e-mail
smtpAccountId	string	opcional	ID da conta SMTP (usa ativa se omitido)

Response 200

{ "ok": true, "messageId": "<abc@smtp>" }

POST /api/email/schedule Agendar campanha de e-mail em massa ▼

Request Body (JSON)

Campo	Tipo	Req.	Descrição
subject	string	obrig.	Assunto do e-mail
html	string	obrig.	Template HTML (suporta `{{razao_social}}` etc.)
recipients	array	obrig.	Array de `{email, razao_social, cnpj}`
intervalMs	number	opcional	Intervalo em ms entre envios (padrão: 2000)
smtpAccountId	string	opcional	ID da conta SMTP

Response 200

{ "ok": true, "jobId": "job_123abc", "total": 320 }

GET /api/email/jobs Status dos jobs de envio em andamento ▼

Response 200

[
  {
    "id":       "job_123abc",
    "status":   "running",
    "sent":     45,
    "total":    320,
    "errors":   2,
    "subject":  "Promoção Maio",
    "startedAt":"2025-05-01T09:00:00.000Z"
  }
]

POST /api/email/verify Verificar existência de e-mails (DNS MX) ▼

Request Body (JSON)

Campo	Tipo	Req.	Descrição
emails	string[]	obrig.	Array de e-mails (máx 200)

Response 200

{
  "verified": {
    "contato@empresa.com.br": "valid",
    "invalido@dominio.xyz":   "invalid"
  }
}

📱 WhatsApp

POST /api/whatsapp/verify Verificar números WhatsApp ▼

Request Body (JSON)

Campo	Tipo	Req.	Descrição
phones	string[]	obrig.	Array de números no formato internacional (55DDNNN…), máx 200

Response 200

{
  "verified": {
    "5565999990001": "valid",
    "5511333330000": "mobile"
  }
}

🏭 CNAE

GET /api/cnaes/resolve Obter descrição de um código CNAE ▼

Query Parameters

Parâmetro	Tipo	Req.	Descrição
code	string	obrig.	Código CNAE (ex: `6422100`)

Response 200

{ "code": "6422100", "description": "Bancos múltiplos, com carteira comercial", "source": "IBGE subclasse" }

GET /api/cnaes/suggest Autocompletar CNAEs do dataset ativo ▼

Query Parameters

Parâmetro	Tipo	Req.	Descrição
q	string	obrig.	Termo de busca (código ou parte da descrição)

Response 200

[
  { "code": "6422100", "description": "Bancos múltiplos, com carteira comercial" },
  { "code": "6421200", "description": "Bancos comerciais" }
]