# CorpData > API de dados cadastrais de empresas brasileiras (base pública da Receita Federal, > 70+ milhões de CNPJs) com enriquecimento por bureau parceiro. Usada para gerar > listas de prospecção B2B, validar e enriquecer cadastros. Especificação completa: https://corpdata.com.br/api/v1/openapi.json Documentação navegável: https://corpdata.com.br/docs/api ## Autenticação Todas as chamadas exigem uma chave de API no header: Authorization: Bearer cd_live_... A chave é gerada no painel (Integrações) e exibida uma única vez. Alternativamente aceita-se o header `X-API-Key`. Nunca use a chave no navegador: ela dá acesso à conta e aos créditos. ## Base https://corpdata.com.br/api/v1 ## Endpoints ### GET /empresas Busca segmentada. Exige ao menos um filtro. Custo: 1 crédito por registro entregue. Filtros: ufs, municipios, bairros, ddds, cnaes, cnaes_secundarios, naturezas, situacao_cadastral, portes, mei, simples, abertura_de, abertura_ate, com_telefone, com_telefone_movel, com_email, divida, capital_min, capital_max. Multi-seleção repete a chave: ?ufs=ES&ufs=SP Paginação: limite (padrão 50, máximo 200) e pagina. Use apenas_total=true para obter só a contagem SEM consumir crédito. ### GET /empresas/{cnpj} Ficha cadastral completa. Custo: 1 crédito. Reconsulta do mesmo CNPJ no mesmo dia não cobra novamente. O CNPJ é validado pelos dígitos verificadores. ### POST /mailing Cria exportação assíncrona. Corpo: { filtros, quantidade, formato }. formato: csv ou xlsx. quantidade: 1 a 50000. Devolve job_id. A cobrança ocorre na conclusão, pela quantidade entregue — job que falha não cobra. ### GET /mailing/{job_id} Status do job. Quando status = concluido, traz arquivo_url para download. Custo: 1 crédito por lead entregue, cobrado uma única vez (polling não duplica). ### GET /mailing/{job_id}/arquivo Baixa o arquivo da exportacao concluida (ZIP com CSV ou XLSX). Sem custo — a exportacao ja foi cobrada na conclusao. Resposta binaria. ### GET /enriquecimento/{cnpj} Dados complementares do bureau: porte e operação, atividades secundárias, complementos cadastrais, quadro societário ampliado e sinais de risco. Custo: 5 créditos. Aceita apenas CNPJ. Requer credenciamento LGPD aprovado. Dados pessoais de terceiros são descartados no servidor; o CPF de sócio vem completo (socios[].cpf). ## Pessoa física (CPF) Liberação individual por contrato. Exige o escopo `pessoas:read` E habilitação da chave — ter o escopo não basta. ### POST /pessoas/consultar Corpo: { cpf, finalidade, justificativa }. Custo: 15 créditos por consulta, cobrados a cada chamada (inclusive do mesmo CPF). É POST, não GET /pessoas/{cpf}: CPF não trafega em URL, porque o caminho da requisição fica registrado em log de servidor, proxy, CDN e no header Referer. A finalidade define quais campos voltam — o conjunto é contratado por cliente. Finalidades disponíveis para esta chave: - ANALISE_CREDITO — Análise de crédito - KYC_CADASTRO — Cadastro (KYC) - COBRANCA_DIVIDA_PROPRIA — Cobrança de dívida própria - PREVENCAO_FRAUDE — Prevenção à fraude A justificativa é obrigatória (mínimo 15 caracteres), entra na auditoria e não pode conter CPF, telefone ou e-mail. ### POST /pessoas/consultar-async Abre a consulta e devolve job_id na hora (ms), sem esperar o bureau. O resultado sai em GET /pessoas/jobs/{job_id}. Feito para volume: dispare varias sem prender uma conexao em cada. Criar o job nao consome credito; a cobranca ocorre no processamento, uma vez. ### GET /pessoas/jobs/{job_id} Estado e resultado do job. A primeira chamada que encontra o job pendente e quem executa a consulta. status: pendente | processando | concluido | erro. Quando concluido, traz dados (o dossie) UMA vez e apaga — guarde do seu lado. ### POST /pessoas/lote Corpo: { cpfs: [...], finalidade, justificativa }. Sempre responde 200, com um item por CPF e o status de cada um: um CPF inválido não derruba o lote. CPF rejeitado na validação não consome crédito. O tamanho máximo do lote é o do seu contrato. Bloco não liberado fica AUSENTE da resposta. Ausência significa "não contratado", não "não encontrado". Erros específicos: 403 PF_NAO_HABILITADA, 403 FINALIDADE_NAO_CONTRATADA, 422 FINALIDADE_INVALIDA, 422 JUSTIFICATIVA_INVALIDA, 422 CPF_INVALIDO, 404 SEM_DADOS, 502 FORNECEDOR_INDISPONIVEL. Exemplo: curl -X POST -H "Authorization: Bearer $CORPDATA_KEY" \ -H "Content-Type: application/json" \ -d '{"cpf":"12345678909","finalidade":"ANALISE_CREDITO","justificativa":"Proposta 4471 em analise"}' \ "https://corpdata.com.br/api/v1/pessoas/consultar" ## Escopos Cada chave carrega escopos; sem o escopo, a resposta é 403 SEM_ESCOPO. - empresas:read: Consultar e buscar empresas - mailing:read: Estimar volume e acompanhar exportações - mailing:export: Gerar exportações de mailing (consome créditos) - enriquecimento:read: Enriquecer CNPJ pelo bureau (consome créditos) - pessoas:read: Consultar pessoa física por CPF (consome créditos) - credito:read: Relatório de crédito por CPF/CNPJ (consome créditos) - sms:otp: Enviar e conferir códigos de verificação por SMS (consome créditos de SMS) ## Limites - 120 requisições por minuto, por chave - Limite diário conforme o plano contratado - Cabeçalhos de resposta: X-RateLimit-Limit-Minute, X-RateLimit-Limit-Day, X-RateLimit-Remaining-Day, X-Creditos-Consumidos ## Erros Formato: { "erro": { "code": "...", "mensagem": "...", "detalhe": "..." } } Programe sobre o campo code (estável), não sobre a mensagem. - 401 SEM_CHAVE, CHAVE_INVALIDA, CHAVE_REVOGADA - 402 SEM_CREDITOS - 403 SEM_ESCOPO, CREDENCIAMENTO_PENDENTE - 404 NAO_ENCONTRADO - 422 PARAMETRO_INVALIDO - 429 LIMITE_MINUTO, LIMITE_DIARIO - 503 API_DESATIVADA ## Exemplos Dimensionar antes de gastar (grátis): curl -H "Authorization: Bearer $CORPDATA_KEY" \ "https://corpdata.com.br/api/v1/empresas?ufs=ES&situacao_cadastral=02&apenas_total=true" Buscar 50 empresas ativas do ES com telefone: curl -H "Authorization: Bearer $CORPDATA_KEY" \ "https://corpdata.com.br/api/v1/empresas?ufs=ES&situacao_cadastral=02&com_telefone=true&limite=50" Consultar um CNPJ: curl -H "Authorization: Bearer $CORPDATA_KEY" \ "https://corpdata.com.br/api/v1/empresas/00000000000191" Exportar mailing: curl -X POST -H "Authorization: Bearer $CORPDATA_KEY" \ -H "Content-Type: application/json" \ -d '{"filtros":{"ufs":["ES"],"situacao_cadastral":["02"]},"quantidade":1000,"formato":"csv"}' \ "https://corpdata.com.br/api/v1/mailing" Acompanhar até concluir: curl -H "Authorization: Bearer $CORPDATA_KEY" \ "https://corpdata.com.br/api/v1/mailing/JOB_ID" Baixar o arquivo quando concluir: curl -H "Authorization: Bearer $CORPDATA_KEY" \ -o export.zip "https://corpdata.com.br/api/v1/mailing/JOB_ID/arquivo" Enriquecer um CNPJ: curl -H "Authorization: Bearer $CORPDATA_KEY" \ "https://corpdata.com.br/api/v1/enriquecimento/00000000000191" ## Observações - Situação cadastral vai com zero à esquerda: "02" é ativa. - A base é atualizada periodicamente a partir dos arquivos públicos da Receita Federal. - Contagens em base de 70M+ podem vir aproximadas; o campo aproximado indica isso. - Uso dos dados é responsabilidade do contratante, conforme a LGPD e o termo aceito no credenciamento.