API Documentation

Integre dados empresariais no seu sistema em minutos.

Base URL: https://api.datasocio.com.br

Autenticacao

Obrigatorio: Todas as requisicoes exigem autenticacao via API key ou JWT token no header Authorization. Requisicoes sem autenticacao retornam 401.

# API Key (recomendado para integracao)
curl -H "Authorization: Bearer vd_live_abc123..." \
https://api.datasocio.com.br/v1/empresas/33000167000101

# JWT Token (sessao do frontend)
curl -H "Authorization: Bearer eyJhbG..." \
https://api.datasocio.com.br/v1/search?q=petrobras

Crie sua conta e API key em datasocio.com.br/register ou no painel de billing.

Rate Limits e Creditos

Plano	Preco	Req/min	Creditos/mes
Gratuito	R$0	10	100
Profissional	R$197/mes	60	5.000
Enterprise	R$997/mes	300	Ilimitado

Headers: X-RateLimit-Limit, X-RateLimit-Remaining, X-Quota-Used, X-Quota-Limit

Formatos de Data

Tipo	Formato	Exemplo
Datas (geral)	dd/MM/yyyy	14/01/1991
data_ajuizamento (processos)	yyyy-MM-dd	2023-05-10
Timestamps	ISO 8601	2026-04-05T12:00:00.000Z

Campos como dataAbertura, dataEntrada usam dd/MM/yyyy. O campo dataDistribuicao em processos usa yyyy-MM-dd. Campos como computedAt usam ISO 8601.

Creditos por Operacao

Cada operacao consome creditos do seu plano mensal. O custo e informado no header X-Credits-Cost e no campo meta.creditsCost de responses paginados.

Operacao	Creditos	Observacao
Busca basica (/v1/search, /v1/empresas/filtrar)	0	Gratuito
Busca com fields=full	1 por resultado	100 resultados = 100 creditos
Detalhe empresa (/v1/empresas/:cnpj)	1	Dados completos
Socios (/v1/empresas/:cnpj/socios)	1	Quadro societario
Compliance (/v1/compliance/:id)	1	Sancoes CGU, divida ativa (por documento completo)
Processos judiciais	1	e-SAJ ou DataJud
Chat IA (/v1/chat)	1	DeepSeek
Empresas similares	1	Mesmo CNAE+porte+UF
Enrichment (redes sociais)	2	Instagram, Google, RA
Grafo de relacionamentos	2	Ate 3 niveis
Batch enrich (por CNPJ)	1	Ate 100 CNPJs
Autocomplete (CNAEs, cidades)	0	Gratuito
Health check	0	Gratuito

Endpoints (34)

GET/v1/search

Buscar empresas por nome, CNPJ ou socio

Parametro	Obrigatorio	Descricao
q	Sim	Termo de busca: nome da empresa, CNPJ (8-14 digitos) ou nome de socio
type	Nao	Tipo: 'empresa' (default) ou 'socio'
uf	Nao	Filtro por estado (ex: SP, RJ, MG)
cnae	Nao	Filtro por CNAE (ex: 4754 ou 4754701)
situacao	Nao	Filtro: 'ativa', 'baixada', 'suspensa', 'inapta', 'todas' (default: todas)
porte	Nao	Filtro: 'ME' (Micro), 'EPP', '01', '03', '05' (Demais)
cidade	Nao	Filtro por cidade (ex: SAO PAULO)
aberturaFrom	Nao	Data minima de abertura (yyyy-MM-dd)
aberturaTo	Nao	Data maxima de abertura (yyyy-MM-dd)
simples	Nao	Optante Simples: 'sim' ou 'nao'
page	Nao	Pagina (default: 1)
limit	Nao	Resultados por pagina (default: 20, max: 100)

/v1/search?q=restaurante&uf=SP&porte=ME&situacao=ativa&aberturaFrom=2024-01-01&limit=5

Response:

{
  "data": [{
    "cnpj": "33000167000101",
    "cnpjFormatado": "33.000.167/0001-01",
    "razaoSocial": "PETROLEO BRASILEIRO S A PETROBRAS",
    "nomeFantasia": "PETROBRAS",
    "situacao": "Ativa",
    "dataAbertura": "28/09/1953",
    "cnaePrincipal": "0600001",
    "cnaeDescricao": "Extracao de petroleo e gas natural",
    "uf": "RJ",
    "municipio": "RIO DE JANEIRO",
    "porte": "Demais",
    "capitalSocial": "R$ 205.431.960.490,52"
  }, ...],
  "meta": { "total": 42, "page": 1, "pages": 3, "limit": 20 }
}

GET/v1/empresas/filtrar

Buscar empresas por filtros (sem texto de busca). Suporta fields=full para dados completos.

Parametro	Obrigatorio	Descricao
cnae	Nao	CNAE principal (ex: 4754 = moveis)
uf	Nao	Estado (ex: SP)
cidade	Nao	Nome da cidade (ex: BAURU)
cidadeCodigo	Nao	Codigo IBGE do municipio
situacao	Nao	'ativa', 'baixada', 'suspensa', 'inapta', 'todas' ou codigo (02, 08...)
porte	Nao	'ME', 'EPP', '01', '03', '05' (Demais). Aceita codigo ou alias.
fundacao	Nao	Abertas nos ultimos N anos (1, 3, 5, 10). Alias: 'abertura'
fields	Nao	'full' = retorna dados completos (endereco, socios, natureza juridica). Cobra 1 credito/resultado. Sem fields = dados basicos (0 creditos).
deduplicate	Nao	Excluir CNPJs ja enviados ao usuario (default: true). Rastreia por user_id. Use false para ver todos.
page	Nao	Pagina (default: 1)
limit	Nao	Limite (default: 20, max: 100)

/v1/empresas/filtrar?cnae=5611&uf=SP&cidade=BAURU&situacao=ativa&fundacao=1&fields=full&limit=5

Response:

{
  "data": [{
    "cnpj": "65670822000125",
    "cnpjFormatado": "65.670.822/0001-25",
    "razaoSocial": "ANA FLAVIA SIQUEIRA BUENO ESPETINHOS LTDA",
    "nomeFantasia": null,
    "situacao": "Ativa",
    "dataAbertura": "13/03/2026",
    "cnaePrincipal": "5611201",
    "cnaeDescricao": "Restaurantes e similares",
    "uf": "SP",
    "municipio": "BAURU",
    "porte": "ME",
    "capitalSocial": "R$ 50.000,00",
    "telefone": "(14) 32371236",
    "email": "restaurante@email.com",
    // Campos extras com fields=full:
    "naturezaJuridica": "Sociedade Empresária Limitada",
    "contato": { "telefone1": "(14) 32371236", "telefone2": null, "email": "..." },
    "endereco": { "tipoLogradouro": "RUA", "logradouro": "PEDRO LIRA", "numero": "195", "complemento": null, "bairro": "CENTRO", "cep": "17015020", "cidade": "BAURU", "uf": "SP" },
    "socios": [{ "nome": "ANA FLAVIA SIQUEIRA BUENO", "cpfCnpj": "***123456**", "qualificacao": "Socio-Administrador" }]
  }],
  "meta": {
    "total": 18,
    "page": 1,
    "pages": 4,
    "limit": 5,
    "fields": "full",
    "creditsPerResult": 1,
    "creditsCost": 5,
    "deduplicated": true,
    "filtros": { "cnae": "5611", "uf": "SP", "cidade": "BAURU", "situacao": "02" }
  }
}

GET/v1/empresas/:cnpj

Dados completos de uma empresa

Parametro	Obrigatorio	Descricao
cnpj	Sim	CNPJ com 14 digitos (com ou sem formatacao)

/v1/empresas/33000167000101

Response:

{
  "data": {
    "cnpj": "33000167000101",
    "cnpjFormatado": "33.000.167/0001-01",
    "razaoSocial": "PETROLEO BRASILEIRO S.A. PETROBRAS",
    "nomeFantasia": "PETROBRAS",
    "situacao": "Ativa",
    "naturezaJuridica": "Sociedade de Economia Mista",
    "capitalSocial": "R$ 205.431.960.490,52",
    "porte": "Demais",
    "dataAbertura": "28/09/1953",
    "cnaePrincipal": "0600001",
    "cnaeDescricao": "Extracao de petroleo e gas natural",
    "cnaesSecundarios": [
      { "codigo": "0600002", "descricao": "..." },
      ...
    ],
    "uf": "RJ",
    "municipio": "RIO DE JANEIRO",
    "endereco": {
      "tipoLogradouro": "AVENIDA",
      "logradouro": "REPUBLICA DO CHILE",
      "numero": "65",
      "complemento": null,
      "bairro": "CENTRO",
      "cep": "20031912",
      "cidade": "RIO DE JANEIRO",
      "uf": "RJ"
    },
    "contato": {
      "telefone1": "(21) 3224-1234",
      "telefone2": null,
      "fax": null,
      "email": "petrobras@petrobras.com.br"
    },
    "simples": {
      "opcaoSimples": false,
      "opcaoMei": false
    },
    "inscricoesEstaduais": [ ... ],
    "suframa": null,
    "socios": [
      {
        "nome": "MAGDA MARIA DE REGINA CHAMBRIARD",
        "cpfCnpj": "***038788**",
        "qualificacao": "Diretor",
        "dataEntrada": "14/06/2024",
        "faixaEtaria": "61-70"
      },
      ...
    ]
  }
}

GET/v1/empresas/:cnpj/enrichment

Dados enriquecidos: redes sociais, reputacao, website

Parametro	Obrigatorio	Descricao
cnpj	Sim	CNPJ com 14 digitos

/v1/empresas/33000167000101/enrichment

Response:

{
  "data": {
    "status": "available",
    "website": {
      "domain": "petrobras.com.br",
      "reachable": true,
      "title": "Petrobras",
      "phones": ["2132241234", "8003001001"],
      "emails": ["contato@petrobras.com.br", "ouvidoria@petrobras.com.br"],
      "whatsapp": "552132241234"
    },
    "socialMedia": {
      "instagram": { "handle": "petrobras", "followers": 4200000, "bio": "Energia para mover o Brasil", "verified": true },
      "linkedin": "petrobras",
      "facebook": "petrobras",
      "twitter": "petaborasbr",
      "youtube": "@petrobras"
    },
    "reclameAqui": {
      "score": 7.2,
      "totalComplaints": 1842,
      "resolvedPct": 82.4,
      "wouldBuyAgain": 56.7,
      "status": "Bom"
    },
    "riskScore": {
      "overall": 847,
      "cadastral": 950,
      "financial": 850,
      "reputation": 720,
      "social": 650,
      "factors": { "situacao": "02", "idadeAnos": 73, "capitalSocial": 205431960490.52 },
      "computedAt": "2026-04-05T12:00:00.000Z"
    }
  }
}

GET/v1/empresas/:cnpj/risk

Score de risco detalhado (0-1000)

Parametro	Obrigatorio	Descricao
cnpj	Sim	CNPJ

/v1/empresas/33000167000101/risk

Response:

{
  "data": {
    "overall": 847,
    "cadastral": 950,
    "financial": 850,
    "reputation": 720,
    "social": 650,
    "factors": {
      "situacao": "02",
      "idadeAnos": 73,
      "capitalSocial": 205431960490.52,
      "reclameAqui": 7.2,
      "website": true,
      "instagram": true,
      "linkedin": true
    },
    "computedAt": "2026-04-05T12:00:00.000Z"
  }
}

GET/v1/empresas/:cnpj/similares

Empresas similares (mesmo CNAE, porte, UF)

Parametro	Obrigatorio	Descricao
cnpj	Sim	CNPJ da empresa referencia
limit	Nao	Quantidade (default: 20, max: 100)

/v1/empresas/33000167000101/similares?limit=5

GET/v1/empresas/:cnpj/graph

Grafo de relacionamentos societarios

Parametro	Obrigatorio	Descricao
cnpj	Sim	CNPJ
depth	Nao	Profundidade: 1, 2 ou 3 (default: 1)

/v1/empresas/33000167000101/graph?depth=2

Response:

{
  "data": {
    "nodes": [
      { "id": "emp-33000167", "label": "PETROLEO BRASILEIRO S.A.", "type": "empresa", "cnpj": "33.000.167/0001-01" },
      { "id": "pes-1", "label": "MAGDA MARIA DE REGINA CHAMBRIARD", "type": "pessoa", "cpf": "***038788**" },
      { "id": "emp-03500167", "label": "TRANSPETRO S.A.", "type": "empresa" },
      ...
    ],
    "edges": [
      { "source": "pes-1", "target": "emp-33000167", "label": "Diretor" },
      { "source": "pes-1", "target": "emp-03500167", "label": "Conselheiro" },
      ...
    ]
  },
  "meta": { "cnpj": "33.000.167/0001-01", "depth": 2, "totalNodes": 5, "totalEdges": 4 }
}

GET/v1/compliance/:identifier

Listas restritivas por DOCUMENTO completo. Cada fonte casa pelo CNPJ/CPF inteiro ou sai como nao verificada, com o motivo — nunca 'limpo' por omissao. status: bloqueio > alerta > incompleto > limpo ('limpo' so se todas as fontes foram verificadas). Sem score. PJ: sancoes CGU (CEIS/CNEP/CEPIM/Acordos de Leniencia) e divida ativa da Uniao (PGFN); OFAC sai nao verificada (a lista nao publica CNPJ). PF: sancoes CGU (CEIS/CNEP); PGFN, PEP e OFAC saem nao verificadas (nenhuma publica o CPF completo).

Parametro	Obrigatorio	Descricao
identifier	Sim	CNPJ (14 digitos, DV valido) ou CPF completo (11 digitos, DV valido). Tudo que nao e CNPJ valido passa antes pela guarda de identidade (sem credencial 401, sem X-Finalidade 428); logado, nome ou documento invalido → 400. CPF exige credencial de usuario (API key ou JWT) e o header X-Finalidade (due_diligence, credito, prevencao_fraude, defesa_em_processo, verificacao_propria ou pesquisa_juridica); a consulta e registrada
type	Nao	'pj' ou 'pf' — so confirma o tipo; contradiz o documento → 400

/v1/compliance/33000167000101

Response:

{
  "identifier": "33000167000101",
  "type": "pj",
  "status": "incompleto",
  "summary": "...",
  "fontes": [
    { "fonte": "Sanções CGU (CEIS/CNEP/CEPIM/Acordos de Leniência)", "verificada": true, "status": "limpo", "motivo": "Casado pelo CNPJ completo.", "detalhes": null, "ocorrencias": 0 },
    { "fonte": "Dívida Ativa da União (PGFN)", "verificada": true, "status": "limpo", "motivo": "Casado pelo CNPJ completo.", "detalhes": null, "ocorrencias": 0 },
    { "fonte": "Sanções OFAC (EUA)", "verificada": false, "status": "nao_verificado", "motivo": "A lista SDN não publica CNPJ; casar só pelo nome não dá certeza.", "detalhes": null, "ocorrencias": 0 }
  ]
}

GET/v1/pessoas/:nome

Sociedades de um socio pessoa fisica no QSA da Receita, pelo nome EXATO + CPF mascarado (nome sozinho somaria homonimos). So empresas: sem processos, PEP, sancoes ou score. Exige credencial de usuario (API key ou JWT) e o header X-Finalidade (due_diligence, credito, prevencao_fraude, defesa_em_processo, verificacao_propria ou pesquisa_juridica); a consulta e registrada.

Parametro	Obrigatorio	Descricao
nome	Sim	Nome completo como no QSA (URL encoded)
cpf	Sim	CPF mascarado como no QSA: *XXXXXX (6 digitos do meio). Ausente ou em outro formato → 400

/v1/pessoas/MAGDA%20MARIA%20DE%20REGINA%20CHAMBRIARD?cpf=***038788**

Response:

{
  "data": {
    "nome": "MAGDA MARIA DE REGINA CHAMBRIARD",
    "totalEmpresas": 3,
    "empresasAtivas": 2,
    "empresas": [
      {
        "cnpj": "33000167000101",
        "cnpjBasico": "33000167",
        "razaoSocial": "PETROLEO BRASILEIRO S.A.",
        "nomeFantasia": "PETROBRAS",
        "qualificacao": "Diretor",
        "dataEntrada": "2024-06-14",
        "situacao": "Ativa",
        "uf": "RJ",
        "municipio": "RIO DE JANEIRO",
        "capitalSocial": "R$ 205.431.960.490,52",
        "capitalSocialNumero": 205431960490.52,
        "porte": "Demais",
        "cnaePrincipal": "0600001",
        "cnaeDescricao": "Extracao de petroleo e gas natural"
      },
      ...
    ],
    "cpfMasked": "***038788**"
  }
}

GET/v1/processos/buscar

Consulta ao vivo em 8 tribunais e-SAJ. Por cpf ou por nome, exige credencial de usuario (API key ou JWT) e o header X-Finalidade (due_diligence, credito, prevencao_fraude, defesa_em_processo, verificacao_propria ou pesquisa_juridica); a consulta e registrada (sem isso: 401/428). Por nome o tribunal casa por PEDACO do nome: a lista traz homonimos e nao e 'os processos desta pessoa' — e, como na base propria, sai sem Justica do Trabalho, Militar, classe ou assunto criminal e processo sem classe informada.

Parametro	Obrigatorio	Descricao
cpf	Nao	CPF (obrigatorio se nao enviar nome)
nome	Nao	Nome da parte (obrigatorio se nao enviar cpf)
tribunal	Nao	Filtrar por tribunal (ex: TJSP)

/v1/processos/buscar?cpf=52998224725
X-Finalidade: due_diligence

GET/v1/processos/brasil

Buscar processos na base propria do DataSocio (DataJud de 91 tribunais: TJs, TRFs, TRTs, TREs, TJMs, STJ, TST, TSE e STM; STF nao incluso). Por nome: processos em que a GRAFIA EXATA aparece como parte — documentos que citam o nome, nao 'os processos desta pessoa' (homonimos) —, sem Justica do Trabalho, Justica Militar, classe ou assunto criminal (furto, trafico, violencia domestica...) nem processo sem classe informada. Em cada processo, partes traz SO a parte cuja grafia casou, sem advogados (as demais partes nao saem por nome). Processos de familia/ECA/violencia domestica e nomes com pedido LGPD nao aparecem.

Parametro	Obrigatorio	Descricao
nome	Nao	Nome da parte, grafia completa (obrigatorio se nao enviar cpf). Nome de uma palavra muito comum responde 422.
cpf	Nao	CPF — exige credencial de usuario (API key ou JWT) e o header X-Finalidade (due_diligence, credito, prevencao_fraude, defesa_em_processo, verificacao_propria ou pesquisa_juridica); a consulta e registrada
cnpj	Nao	Indisponivel: qualquer valor responde 422 { motivo: 'cnpj_indisponivel' } (a ligacao empresa-processo pela razao social saiu; volta so por CNPJ citado no documento)
limit	Nao	Maximo de processos (default: 50, max: 200), mais recentes primeiro

/v1/processos/brasil?nome=JOAO+CARLOS+DA+SILVA+PEREIRA

GET/v1/processos/por-nome

Documentos publicos (processos e publicacoes de diario) que citam a grafia do nome — mesmo contrato de /v1/documentos/nome/:nome. Lista plana: nao agrega nem atribui a uma pessoa (homonimos). Mesmas exclusoes de /v1/processos/brasil por nome; em processo, o trecho traz so a parte cuja grafia casou (papel e assunto), sem as demais partes nem advogados.

Parametro	Obrigatorio	Descricao
nome	Sim	Nome e sobrenome (minimo 5 letras, 2 palavras)
page	Nao	Pagina (default: 1)

/v1/processos/por-nome?nome=JOAO+CARLOS+DA+SILVA+PEREIRA

Response:

{
  "data": [{ "tipo": "processo", "numero": "...", "tribunal": "TJSP", "classe": "...", "data": "2025-03-10", "trecho": null, "fonte": "..." }, ...],
  "meta": { "total": 12, "page": 1, "por_pagina": 20, "paginas": 1, "limitado": false, "parcial": false }
}

GET/v1/processos/por-cpf-parcial

Processos de UMA pessoa por vinculo de documento: so publicacoes do DJEN em que os 6 digitos do meio do CPF e o nome completo EXATO da parte aparecem juntos, com um unico destinatario e um unico CPF na publicacao. Sem vinculo assim, lista vazia (nao ha camada 'provavel'). Exige credencial de usuario (API key ou JWT) e o header X-Finalidade (due_diligence, credito, prevencao_fraude, defesa_em_processo, verificacao_propria ou pesquisa_juridica); a consulta e registrada.

Parametro	Obrigatorio	Descricao
cpf6	Sim	6 digitos do meio do CPF
nome	Sim	Nome completo exato da parte
limit	Nao	Maximo (default: 50, max: 200)

/v1/processos/por-cpf-parcial?cpf6=982247&nome=JOAO+CARLOS+DA+SILVA+PEREIRA
X-Finalidade: due_diligence

GET/v1/perfil/:slug

Perfil agregado de pessoa fisica pelo nome. Com mais de uma pessoa com o mesmo nome a API nao escolhe: responde ambiguo: true e a lista de candidatos (nome, UF, CPF mascarado) — repita com ?cpf6= do escolhido. Exige credencial de usuario (API key ou JWT) e o header X-Finalidade (due_diligence, credito, prevencao_fraude, defesa_em_processo, verificacao_propria ou pesquisa_juridica); a consulta e registrada.

Parametro	Obrigatorio	Descricao
slug	Sim	Nome em slug (ex: joao-carlos-da-silva)
cpf6	Nao	6 digitos do meio do CPF — desambigua entre homonimos (outro formato → 400)
uf	Nao	UF principal

/v1/perfil/joao-carlos-da-silva
X-Finalidade: due_diligence
(homonimos → repetir com ?cpf6=982247)

Response:

{
  "data": {
    "nome": "JOAO CARLOS DA SILVA",
    "uf": null,
    "encontrado": true,
    "ambiguo": true,
    "candidatos": [
      { "nome_display": "JOAO CARLOS DA SILVA", "uf_principal": "SP", "cpf_mascarado": "***.982.247-**" },
      { "nome_display": "JOAO CARLOS DA SILVA", "uf_principal": "MG", "cpf_mascarado": "***.104.551-**" }
    ]
  }
}

POST/v1/batch/enrich

Enriquecimento em lote — retorna dados completos de ate 100 CNPJs em 1 request. Cobra 1 credito por CNPJ encontrado.

Parametro	Obrigatorio	Descricao
cnpjs	Sim	Array de CNPJs: ["33000167000101", "60746948000112"]. Max 100.

POST /v1/batch/enrich
Body: { "cnpjs": ["33000167000101", "60746948000112"] }

Response:

{
  "data": [
    { "cnpj": "33000167000101", "razaoSocial": "PETROLEO BRASILEIRO S A PETROBRAS", "situacao": "Ativa", "endereco": {...}, "contato": {...}, "socios": [...], ... },
    { "cnpj": "60746948000112", "razaoSocial": "BANCO BRADESCO S.A.", ... }
  ],
  "meta": { "total": 2, "encontrados": 2, "erros": 0 }
}

POST/v1/chat

IA conversacional sobre empresas (DeepSeek)

Parametro	Obrigatorio	Descricao
message	Sim	Pergunta em linguagem natural
context.cnpj	Nao	CNPJ para contexto

POST /v1/chat
Body: { "message": "Qual o risco da Petrobras?", "context": { "cnpj": "33000167000101" } }

GET/v1/maps/stats

Estatisticas de empresas por UF

/v1/maps/stats

GET/v1/maps/heatmap

Densidade de empresas por municipio

Parametro	Obrigatorio	Descricao
uf	Nao	Filtrar por estado
cnae	Nao	Filtrar por CNAE
situacao	Nao	Filtrar: 'ativa' (default: todas)

/v1/maps/heatmap?uf=SP&cnae=62&situacao=ativa

POST/v1/monitoring

Monitorar CNPJ para mudancas

Parametro	Obrigatorio	Descricao
cnpj	Sim	CNPJ a monitorar
webhookUrl	Nao	URL para receber alertas
email	Nao	Email para receber alertas
fields	Nao	Campos a monitorar (default: ["situacao_cadastral","socios","endereco"])

POST /v1/monitoring
Body: { "cnpj": "33000167000101", "webhookUrl": "https://meusite.com/webhook", "fields": ["situacao_cadastral","socios"] }

GET/v1/filtros/cnaes

Autocomplete de CNAEs por texto

Parametro	Obrigatorio	Descricao
q	Sim	Texto para buscar (ex: 'moveis', 'restaurante')

/v1/filtros/cnaes?q=moveis

GET/v1/filtros/cidades

Autocomplete de cidades por texto (busca em 5.572 municipios)

Parametro	Obrigatorio	Descricao
q	Sim	Texto (min 2 chars)

/v1/filtros/cidades?q=sao+jose&uf=SP

GET/v1/empresas/:cnpj/socios

Quadro societario completo de uma empresa

Parametro	Obrigatorio	Descricao
cnpj	Sim	CNPJ com 14 digitos

/v1/empresas/33000167000101/socios

Response:

{
  "data": [
    {
      "nome": "MAGDA MARIA DE REGINA CHAMBRIARD",
      "cpfCnpj": "***038788**",
      "qualificacao": "Diretor",
      "dataEntrada": "14/06/2024",
      "faixaEtaria": "61-70"
    },
    {
      "nome": "FERNANDO ANTONIO RIBEIRO SOARES MELGAREJO",
      "cpfCnpj": "***521577**",
      "qualificacao": "Diretor",
      "dataEntrada": "02/01/2023",
      "faixaEtaria": "51-60"
    },
    ...
  ],
  "meta": { "total": 9, "cnpj": "33.000.167/0001-01" }
}

POST/v1/empresas/:cnpj/enrich

Disparar enriquecimento manual (Pro/Enterprise)

Parametro	Obrigatorio	Descricao
cnpj	Sim	CNPJ

POST /v1/empresas/33000167000101/enrich

GET/v1/processos/tribunais

Listar os tribunais cobertos: baseLocal = presente na base propria (/v1/processos/brasil e /v1/processos/banco); tempoReal = consulta ao vivo no e-SAJ (/v1/processos/buscar)

/v1/processos/tribunais

POST/v1/batch/csv

Enriquecimento via upload CSV (coluna cnpj obrigatoria)

Parametro	Obrigatorio	Descricao
body	Sim	Texto CSV com header contendo coluna 'cnpj'. Max 100 linhas.

POST /v1/batch/csv
Content-Type: text/plain

cnpj
33000167000101
60746948000112

GET/v1/maps/empresas

Empresas por regiao (dados para mapa)

Parametro	Obrigatorio	Descricao
uf	Sim	Estado (ex: SP)
cidade	Nao	Nome da cidade
cnae	Nao	Filtro por CNAE
situacao	Nao	Filtro: 'ativa'
limit	Nao	Max resultados (default: 200, max: 1000)

/v1/maps/empresas?uf=SP&cidade=SAO+PAULO&cnae=62&situacao=ativa&limit=100

GET/v1/health

Status da API (publico, sem autenticacao)

/v1/health

Response:

{ "status": "ok", "timestamp": "..." }

POST/auth/register

Criar conta + plano gratuito + primeira API key

Parametro	Obrigatorio	Descricao
email	Sim	Email valido
name	Sim	Nome (min 2 chars)
password	Sim	Senha (min 8 chars)

POST /auth/register
Body: { "email": "user@email.com", "name": "Joao", "password": "minhasenha" }

Response:

{ "user": { "id": "...", "email": "..." }, "token": "eyJ...", "apiKey": "vd_live_..." }

POST/auth/login

Parametro	Obrigatorio	Descricao
email	Sim	Email
password	Sim	Senha

POST /auth/login
Body: { "email": "user@email.com", "password": "minhasenha" }

Response:

{ "user": {...}, "token": "eyJ...", "subscription": {...}, "apiKeys": [...] }

GET/auth/me

Validar sessao e obter dados do usuario logado

GET /auth/me
Authorization: Bearer eyJ...

GET/auth/api-keys

Listar API keys do usuario (sem revelar valor)

GET /auth/api-keys

POST/auth/api-keys

Gerar nova API key

Parametro	Obrigatorio	Descricao
name	Nao	Nome da key (default: 'Nova Key')

POST /auth/api-keys
Body: { "name": "Minha Key" }

Response:

{ "apiKey": "vd_live_...", "prefix": "vd_live_xxxx", "message": "Guarde — ela so aparece uma vez!" }

DELETE/auth/api-keys/:id

Revogar uma API key

Parametro	Obrigatorio	Descricao
id	Sim	ID da key (UUID)

DELETE /auth/api-keys/8e9383e4-d70d-4676-...

GET/auth/usage

Uso de creditos do mes atual

GET /auth/usage

Response:

{ "plan": "free", "used": 42, "limit": 100, "remaining": 58, "resetDate": "2026-05-01" }

Codigos de Erro

Codigo	Significado
400	Parametros invalidos ou ausentes
401	Autenticacao ausente ou token invalido
403	Creditos esgotados ou plano insuficiente
404	Recurso nao encontrado (CNPJ inexistente)
429	Rate limit excedido — aguarde X-RateLimit-Reset
500	Erro interno do servidor

Exemplo completo

// Node.js — Buscar empresas
const response = await fetch(
  'https://api.datasocio.com.br/v1/search?q=petrobras&limit=5',
  { headers: { 'Authorization': 'Bearer vd_live_...' } }
);
const { data, meta } = await response.json();
console.log(data[0].razaoSocial);  // "PETROLEO BRASILEIRO S A PETROBRAS"
console.log(meta.total);           // 42

// Filtrar por CNAE + cidade (sem texto de busca)
const res2 = await fetch(
  'https://api.datasocio.com.br/v1/empresas/filtrar?cnae=4754&uf=SP&cidade=BAURU&situacao=ativa&fundacao=1',
  { headers: { 'Authorization': 'Bearer vd_live_...' } }
);
// → 18 lojas de moveis abertas em Bauru no ultimo ano

// Compliance check
const res3 = await fetch(
  'https://api.datasocio.com.br/v1/compliance/33000167000101',
  { headers: { 'Authorization': 'Bearer vd_live_...' } }
);
// → { status: "limpo" | "alerta" | "bloqueio" | "incompleto", summary, fontes: [...] }

// Chat IA
const res4 = await fetch(
  'https://api.datasocio.com.br/v1/chat',
  {
    method: 'POST',
    headers: { 'Authorization': 'Bearer vd_live_...', 'Content-Type': 'application/json' },
    body: JSON.stringify({ message: 'Quantos socios tem a Petrobras?' })
  }
);
// → { reply: "A Petrobras tem 9 sócios..." }

Changelog

v1.5.02026-10-22

/v1/compliance: contrato novo — status limpo|alerta|bloqueio|incompleto + fontes[{fonte, verificada, status, motivo, detalhes, ocorrencias}]; score e riskLevel sairam. So CNPJ ou CPF completo. Tudo que nao e CNPJ valido (CPF, nome, documento invalido) passa antes pela guarda de identidade: sem credencial de usuario → 401, sem X-Finalidade → 428; so quem passou nela recebe o 400 de nome/documento invalido
/v1/processos/buscar: busca por nome tambem exige credencial de usuario + X-Finalidade
/v1/processos/brasil: cnpj responde 422 cnpj_indisponivel; nome sem Justica do Trabalho, Militar, classe/assunto criminal e processo sem classe
/v1/processos/brasil e /v1/processos/banco por nome: partes traz so a parte cuja grafia casou, advogados vazio
/v1/pessoas/:nome: cpf (***XXXXXX**) obrigatorio; so sociedades (processos, PEP, sancoes e score sairam)
/v1/processos/por-cpf-parcial: so vinculo por documento (cpf6 + nome completo exato + vinculo unico); camadas inferidas removidas
/v1/processos/por-nome: so a lista de documentos que citam o nome (o modo agregado saiu)
/v1/perfil/:slug: homonimos → ambiguo: true + candidatos; escolha com ?cpf6=
Removido: /v1/enrich/cpf-from-name

v1.4.02026-04-05

fields=full no /v1/empresas/filtrar — dados completos inline (endereco, socios, natureza juridica)
Tabela de creditos por operacao adicionada a documentacao
meta.creditsCost e meta.creditsPerResult documentados
Response do POST /v1/batch/enrich documentado com exemplo completo
Deduplicacao: detalhado que rastreia por user_id
Param porte aceita alias ME/EPP alem de codigos 01/03/05
Response completo do /v1/empresas/filtrar documentado com todos os campos
Rate limit: 20 req/min para frontend anonimo
Compliance, chat, processos, similares, estimativa agora cobram 1 credito

v1.3.12026-04-05

Documentacao reescrita: 33 endpoints documentados com params detalhados
Corrigido: depth default no graph era 2 na docs, 1 no codigo (agora correto: 1)
Corrigido: situacao aceita ativa/baixada/suspensa/inapta/todas (antes so ativa/02)
Corrigido: header X-Credits -> X-Quota (alinhado com codigo)
Adicionados endpoints faltantes: socios, enrich, tribunais, batch/csv, maps/empresas, auth/*, health
Removido param uf de filtros/cidades (nao tinha efeito no codigo)

v1.3.02026-04-05

Autenticacao obrigatoria em todos os endpoints (antes era opcional)
JWT nunca expira (antes expirava em 7 dias)
Novo endpoint: /v1/compliance/:identifier
Novo endpoint: /v1/empresas/:cnpj/estimativa
Novo endpoint: /v1/empresas/:cnpj/similares
Novo endpoint: /v1/maps/stats e /v1/maps/heatmap
Novo endpoint: /v1/chat (IA conversacional)
Novo endpoint: /v1/batch/enrich e /v1/batch/csv
CNAEs secundarios com descricao no detalhe da empresa
Inscricoes Estaduais e SUFRAMA no detalhe da empresa
Capital social e CNAE na listagem de sociedades
Busca por nome otimizada (FTS + trgm, 50x mais rapida)
Busca por filtros aceita situacao=ativa (texto) alem de 02 (codigo)

v1.2.02026-04-03

Rebrand: VeriData -> DataSocio
8 tribunais e-SAJ integrados
DataJud (35 tribunais) integrado
Enriquecimento de partes dos processos

v1.0.02026-04-01

Lancamento inicial
67M empresas da Receita Federal
Busca por CNPJ, nome, socio
Score de risco
API keys e planos

SDKs

Node.js / TypeScript

npm install @datasocio/sdkEm breve

Python

pip install datasocioEm breve

PHP

composer require datasocio/sdkEm breve

Precisa de ajuda?

Entre em contato: api@datasocio.com.br