Documentação da API de CNPJ e Empresas

API do sistema · escrita

Criar e atualizar contatos e empresas

Em Configurações → API, escolha finalidade Sistema e permissão Leitura e escrita. As chaves existentes permanecem de leitura; crie uma chave nova para habilitar gravações. Chaves de prospecção não podem gravar. O acesso continua limitado à conta e à visão do titular.

Use a chave em um backend ou automação protegida; não a publique no código do navegador. O corpo de cada pedido aceita até 64 KiB. Envie JSON, Authorization e Idempotency-Key em todo POST/PATCH. A mesma chave de idempotência deve ser reutilizada ao repetir o mesmo pedido após falha de rede; outro corpo com a mesma chave retorna 409. O cache HTTP dura 24 horas. GET não exige esse header.

1. Cadastrar a empresa pelo CNPJ

curl -X POST "https://leadcnpj.com.br/api/v1/sistema/crm/empresas" \
  -H "Authorization: Bearer leadcnpj_system_..." \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: empresa-erp-001" \
  -d '{"cnpj":"11222333000181","razao_social":"Empresa Exemplo Ltda","nome_fantasia":"Exemplo","email":"comercial@example.com","telefone":"1133334444","site":"https://example.com","cidade":"São Paulo","uf":"SP"}'

Apenas cnpj é obrigatório. CNPJ numérico com 14 dígitos, com ou sem pontuação no corpo, e dígitos verificadores válidos. Não consulta ou enriquece automaticamente dados da Receita: os campos enviados formam um cadastro privado da integração. Não cria um contato fictício. O mesmo CNPJ em outra conta é um cadastro independente.

{
  "data": {
    "id": 42, "cnpj": "11222333000181",
    "razao_social": "Empresa Exemplo Ltda", "nome_fantasia": "Exemplo",
    "email": "comercial@example.com", "telefone": "1133334444",
    "site": "https://example.com", "cidade": "São Paulo", "uf": "SP",
    "criado_em": "2026-10-16 09:00:00", "atualizado_em": "2026-10-16 09:00:00"
  },
  "meta": {"creditos_consumidos": 0, "consultado_em": "2026-10-16T09:00:00-03:00", "timezone": "America/Sao_Paulo"}
}

Retorna 201. Se já cadastrada, retorna 409; consulte ou atualize pelo CNPJ. O cadastro privado da empresa fica disponível pelos endpoints de empresas da integração; não substitui automaticamente os campos de empresa já copiados em contatos do CRM.

2. Atualizar ou consultar a empresa

curl -X PATCH "https://leadcnpj.com.br/api/v1/sistema/crm/empresas/11222333000181" \
  -H "Authorization: Bearer leadcnpj_system_..." \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: empresa-erp-001-v2" \
  -d '{"nome_fantasia":"Novo nome","email":"novo@example.com","telefone":null}'

curl "https://leadcnpj.com.br/api/v1/sistema/crm/empresas/11222333000181" \
  -H "Authorization: Bearer leadcnpj_system_..."

PATCH retorna 200 com o objeto atualizado no mesmo formato da criação. Campos permitidos: razao_social, nome_fantasia, email, telefone, site, cidade e uf. No caminho, use CNPJ sem pontuação. O CNPJ identifica o cadastro e não pode ser alterado. Campos omitidos são preservados; null limpa um campo opcional.

3. Incluir um contato no CRM

curl -X POST "https://leadcnpj.com.br/api/v1/sistema/crm/leads" \
  -H "Authorization: Bearer leadcnpj_system_..." \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: contato-erp-ana-001" \
  -d '{"id_externo":"erp:contato:ana-001","nome":"Ana Souza","email":"ana@example.com","whatsapp":"5511999990000","cargo":"Gerente","setor":"Comercial","cnpj_empresa":"11222333000181","nome_empresa":"Empresa Exemplo Ltda","status":"novo","temperatura":"morno"}'

{
  "data": {"id":123,"id_externo":"erp:contato:ana-001","reutilizado":false},
  "meta": {"creditos_consumidos":0,"consultado_em":"2026-10-16T09:00:00-03:00","timezone":"America/Sao_Paulo"}
}

Retorna 201. nome e id_externo são obrigatórios. Use um id_externo estável por contato e integração; prefixe com o nome do sistema. Aceita de 1 a 100 letras ASCII, números ou . _ : @ -. Repetir o mesmo cadastro normalizado e id_externo retorna 200 com reutilizado=true e o mesmo ID, inclusive com outra chave da mesma conta. Um corpo diferente com esse identificador retorna 409: use PATCH pelo ID retornado.

O contato é criado no CRM, com o titular como responsável e origem api. O limite de contatos ativos do plano é respeitado. A gravação não consome créditos nem dispara o agente ou mensagens. Sem CNPJ, o contato é cadastrado como autônomo. CNPJ não exige cadastro prévio no endpoint de empresas. Várias pessoas podem compartilhar o mesmo CNPJ; e-mail igual na mesma empresa e conta gera conflito.

4. Atualizar um contato

curl -X PATCH "https://leadcnpj.com.br/api/v1/sistema/crm/leads/123" \
  -H "Authorization: Bearer leadcnpj_system_..." \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: contato-erp-ana-001-v2" \
  -d '{"email":"ana.novo@example.com","cargo":"Diretora","status":"qualificado","temperatura":"quente","telefone":null}'

{
  "data": {"id":123,"id_externo":null,"reutilizado":false},
  "meta": {"creditos_consumidos":0,"consultado_em":"2026-10-16T09:05:00-03:00","timezone":"America/Sao_Paulo"}
}

Retorna 200. Consulte todos os campos publicados com GET /sistema/crm/leads/123. PATCH aceita nome, email, telefone, whatsapp, cargo, setor, cnpj_empresa, nome_empresa, status e temperatura. Não aceita troca de responsável, grupo, origem, CPF, tags, notas internas ou campos desconhecidos. A temperatura enviada é uma classificação manual e não será sobrescrita pelo score. Use cnpj_empresa vazio para desvincular a empresa; atualize também nome_empresa se necessário.

Omissão preserva o valor existente. null limpa campos opcionais, mas não é aceito para nome, cnpj_empresa, status ou temperatura. Não há PUT nem DELETE nesta versão. Inclusões e atualizações são de um registro por pedido; não use um array para importação em massa.

Erros e recuperação

401: chave inválida ou revogada.
403: chave de leitura, perda de permissão ou limite de contatos ativos atingido.
404: recurso não existe ou não está na visão do titular.
409: cadastro duplicado, identificador externo reutilizado com outro corpo ou conflito de idempotência.
422: campo inválido, desconhecido, CNPJ inválido, contato suprimido ou ausência de Idempotency-Key.
429: limite de chamadas. Aguarde antes de repetir.
503: migração ou verificação de supressões indisponível. Nenhum cadastro é gravado quando a transação falha.