CNPJ na Receita Federal

Consulte dados cadastrais de empresas, como razão social, nome fantasia, situação cadastral, endereço, CNAEs, natureza jurídica, porte e quadro societário.

Informações de entrada

Para realizar uma consulta na API CNPJ na Receita Federal, é necessário informar apenas o CNPJ. Os demais parâmetros são opcionais e permitem controlar o comportamento da consulta, especialmente o uso de cache.

CNPJ: Documento da empresa que será consultada. Pode ser enviado com ou sem pontuação, desde que completo.

Cache: Define por quantos dias uma consulta armazenada em cache ainda pode ser considerada válida. O valor padrão é 7 dias.

Cache Strategy: Define o comportamento da consulta, determinando a prioridade entre dados em cache e consulta em tempo real na Receita Federal.

Optin: Solicita dados ampliados do quadro societário quando esse recurso estiver habilitado para a conta.

Parâmetros obrigatórios

Name
cnpj
Type
string
Description
CNPJ completo da empresa. Pode ser informado com ou sem pontuação.
Exemplo: 15436940000103

Parâmetros opcionais

Name
cache
Type
number
Description
Define por quantos dias uma consulta armazenada em cache ainda pode ser considerada válida. O valor padrão é 7 dias.
Esse parâmetro não altera sozinho a prioridade da requisição. Para priorizar cache, informe também uma estratégia compatível em cache_strategy.

Name
cache_strategy
Type
string
Description
Estratégia utilizada pela API para decidir entre reutilizar cache e consultar online na Receita Federal. O valor padrão é ONLINE_PREFERENCIAL.
Valores aceitos: CACHE_SE_EXISTIR, CACHE_PREFERENCIAL, SO_ONLINE, ONLINE_PREFERENCIAL.

Name
optin
Type
string
Description
Solicita dados ampliados do quadro societário quando esse recurso estiver habilitado para a conta. A disponibilidade depende das permissões e do modelo contratado.

Estratégias de Cache

A API oferece diferentes estratégias para balancear entre disponibilidade, latência e atualização dos dados:

Estratégia	Prioridade	Fallback	Descrição
`CACHE_SE_EXISTIR`	Cache	Online	Utiliza o cache caso exista resultado armazenado para o CNPJ. Em cache miss, tenta consulta em tempo real na Receita Federal.
`CACHE_PREFERENCIAL`	Cache válido	Online	Utiliza o cache quando estiver dentro da validade definida por `cache`. Caso contrário, tenta consulta em tempo real na Receita Federal.
`SO_ONLINE`	Online	Nenhum	Sempre tenta consulta em tempo real na Receita Federal. Não utiliza cache como fallback quando a consulta falha.
`ONLINE_PREFERENCIAL`	Online	Cache	Prioriza a consulta em tempo real na Receita Federal. Se houver falha ou indisponibilidade na consulta oficial, pode utilizar cache existente como fallback. Padrão.

GET/consultas/v2/cnpj-receita-federal/{cnpj}

Receita Federal PJ

Esse endpoint retorna dados cadastrais de CNPJ, priorizando consulta em tempo real na Receita Federal por padrão e aplicando cache conforme a estratégia configurada.

Parâmetros de query string

Name
cache
Type
number
Description
Define por quantos dias uma consulta armazenada em cache ainda pode ser considerada válida. O valor default é 7 dias.

Name
cache_strategy
Type
string
Description
Estratégia de cache a ser utilizada. O valor default é ONLINE_PREFERENCIAL.
Valores aceitos: CACHE_SE_EXISTIR, CACHE_PREFERENCIAL, SO_ONLINE, ONLINE_PREFERENCIAL.

Name
optin
Type
string
Description
Solicita dados ampliados do quadro societário quando habilitado para a conta.

Requisição

GET

/consultas/v2/cnpj-receita-federal/{cnpj}

curl "https://api.sintegrapi.com.br/consultas/v2/cnpj-receita-federal/15436940000103" \
  -H "x-api-key: SUA_API_KEY"

Resposta

  {
      "request_id": "326dd48e-4039-4e27-b339-33ad3bedbefa",
      "success": true,
      "error": false,
      "error_message": null,
      "response": {
          "cnpj": "15436940000103",
          "nome_empresarial": "AMAZON SERVICOS DE VAREJO DO BRASIL LTDA.",
          "situacao_cadastral": "ATIVA"
      }
  }

Exemplos de Uso

Consulta padrão (valores padrão)

GET /consultas/v2/cnpj-receita-federal/15436940000103

Equivalente a:

GET /consultas/v2/cnpj-receita-federal/15436940000103?cache_strategy=ONLINE_PREFERENCIAL&cache=7

Consulta priorizando cache por 30 dias

GET /consultas/v2/cnpj-receita-federal/15436940000103?cache_strategy=CACHE_PREFERENCIAL&cache=30

A API utilizará o cache se ele tiver até 30 dias de idade. Caso contrário, tentará uma nova consulta em tempo real na Receita Federal.

Consulta reutilizando qualquer cache existente

GET /consultas/v2/cnpj-receita-federal/15436940000103?cache_strategy=CACHE_SE_EXISTIR

Se houver cache para o CNPJ, ele será retornado sem validação de idade. Em cache miss, a API tentará a consulta em tempo real na Receita Federal.

Consulta sempre online

GET /consultas/v2/cnpj-receita-federal/15436940000103?cache_strategy=SO_ONLINE

A API tentará consultar diretamente a base oficial da Receita Federal em tempo real. Se falhar, não utiliza cache como fallback.

Consulta online com fallback para cache

GET /consultas/v2/cnpj-receita-federal/15436940000103?cache_strategy=ONLINE_PREFERENCIAL&cache=7

A API tentará primeiro a consulta em tempo real na Receita Federal. Se houver falha ou indisponibilidade na consulta oficial, poderá retornar cache existente.

Consulta com dados ampliados de sócios

GET /consultas/v2/cnpj-receita-federal/15436940000103?optin=socios_detalhados

Quando a conta possui o recurso habilitado, a resposta pode incluir dados ampliados do quadro societário.

Observações Importantes

O parâmetro cache não força a criação de um novo cache. Ele define apenas a idade máxima aceita para considerar um cache válido em estratégias aplicáveis.
O valor padrão de cache_strategy é ONLINE_PREFERENCIAL, portanto a API prioriza consulta em tempo real na Receita Federal quando a estratégia não é enviada.
Em ONLINE_PREFERENCIAL, o fallback depende da existência de cache prévio para o CNPJ consultado.
Em SO_ONLINE, qualquer indisponibilidade na consulta oficial da Receita Federal é retornada como falha, sem reaproveitamento de cache.
Em CACHE_PREFERENCIAL, se o cache estiver expirado, sem data válida ou inexistente, a API tenta consulta em tempo real na Receita Federal.
Em CACHE_SE_EXISTIR, qualquer cache armazenado pode ser reutilizado, independentemente da idade.
Após resposta online válida, os dados do CNPJ são atualizados no cache. Respostas incompletas, erros e timeouts não devem atualizar o cache.

Exemplo de resposta

{
  "request_id": "326dd48e-4039-4e27-b339-33ad3bedbefa",
  "success": true,
  "error": false,
  "error_message": null,
  "response": {
    "cnpj": "15436940000103",
    "identificador_matriz_filial": "Matriz",
    "data_de_abertura": "2012-04-02",
    "nome_empresarial": "AMAZON SERVICOS DE VAREJO DO BRASIL LTDA.",
    "nome_fantasia": "AMAZON.COM.BR",
    "atividade_economica_principal": {
      "codigo": "4761001",
      "descricao": "Comércio varejista de livros"
    },
    "atividades_economicas_secundarias": [],
    "natureza_juridica": {
      "codigo": "2062",
      "descricao": "Sociedade Empresária Limitada"
    },
    "logradouro": "PRES JUSCELINO KUBITSCHEK",
    "numero": "2041",
    "complemento": "ANDAR 18 20 21 22 E 23",
    "bairro": "VILA NOVA CONCEICAO",
    "cep": "04543011",
    "municipio": "SAO PAULO",
    "uf": "SP",
    "endereco_eletronico": "CONTATO@EMPRESA.COM.BR",
    "telefone": "1141302000",
    "situacao_cadastral": "ATIVA",
    "data_da_situacao_cadastral": "2012-04-02",
    "porte": "DEMAIS",
    "socios": []
  }
}

Campos sem informação disponível podem ser retornados como null, string vazia ou coleção vazia, conforme o campo do contrato.

Códigos HTTP comuns

Código	Significado
`200`	Requisição processada. Consulte `success`, `error` e `error_message` no corpo da resposta.
`400`	CNPJ inválido, estratégia inválida ou falha ao processar a consulta.
`401`	Chave de API ausente ou inválida.
`402`	Saldo insuficiente para realizar a consulta.
`429`	Limite de requisições excedido.
`500`	Erro interno inesperado.

Consulte também a página de erros da API para orientações gerais de tratamento.

Boas práticas

Para dados recentes com maior disponibilidade, mantenha o padrão ONLINE_PREFERENCIAL.
Para impedir qualquer resposta de cache, utilize SO_ONLINE.
Para reduzir latência em rotinas menos sensíveis à atualização, utilize CACHE_PREFERENCIAL com uma validade adequada ao seu processo.
Não envie cache esperando que ele, isoladamente, altere a prioridade da consulta; defina também cache_strategy quando quiser priorizar cache.
Trate timeouts e erros transitórios com retentativas controladas e backoff exponencial.
Não presuma que uma falha online sempre terá fallback: o cache pode não existir para o CNPJ consultado.

Integração com CRMs e ERPs

O retorno estruturado deste endpoint foi projetado para facilitar integrações com plataformas empresariais de grande porte. Os campos seguem nomenclatura consistente e tipagem previsível, o que reduz o esforço de mapeamento em ferramentas como Salesforce, SAP S/4HANA, Microsoft Dynamics 365, HubSpot, Zoho CRM, Oracle Fusion Cloud e outros sistemas corporativos.

Para integrações via iPaaS, o schema da resposta pode ser importado diretamente no MuleSoft Anypoint, Dell Boomi, Workato, Make (Integromat) e Azure Logic Apps, eliminando a necessidade de configuração manual de cada campo.

Use o JSON Schema abaixo para:

Validar automaticamente as respostas antes de persistir no banco de dados ou CRM
Gerar classes e modelos de dados com ferramentas como Quicktype ou json-schema-to-typescript
Configurar mapeamentos de campos em conectores de integração
Documentar contratos de API internos nos seus processos de onboarding

JSON Schema da Resposta

JSON Schema

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "title": "CNPJ Receita Federal — Resposta",
  "type": "object",
  "properties": {
    "request_id": {
      "type": "string",
      "format": "uuid",
      "description": "Identificador único da requisição."
    },
    "success": {
      "type": "boolean",
      "description": "Indica se a consulta foi processada com sucesso."
    },
    "error": {
      "type": "boolean",
      "description": "Indica se ocorreu um erro na consulta."
    },
    "error_message": {
      "type": ["string", "null"],
      "description": "Mensagem de erro, quando aplicável."
    },
    "response": {
      "type": "object",
      "description": "Dados cadastrais retornados pela Receita Federal.",
      "properties": {
        "cnpj": {
          "type": "string",
          "description": "CNPJ consultado, sem formatação."
        },
        "identificador_matriz_filial": {
          "type": "string",
          "enum": ["Matriz", "Filial"],
          "description": "Indica se o estabelecimento é a matriz ou uma filial."
        },
        "data_de_abertura": {
          "type": "string",
          "format": "date",
          "description": "Data de abertura da empresa no formato YYYY-MM-DD."
        },
        "nome_empresarial": {
          "type": "string",
          "description": "Razão social da empresa."
        },
        "nome_fantasia": {
          "type": ["string", "null"],
          "description": "Nome fantasia da empresa, quando informado."
        },
        "atividade_economica_principal": {
          "type": "object",
          "description": "CNAE principal da empresa.",
          "properties": {
            "codigo": { "type": "string", "description": "Código CNAE." },
            "descricao": { "type": "string", "description": "Descrição da atividade econômica." }
          },
          "required": ["codigo", "descricao"]
        },
        "atividades_economicas_secundarias": {
          "type": "array",
          "description": "Lista de CNAEs secundários.",
          "items": {
            "type": "object",
            "properties": {
              "codigo": { "type": "string" },
              "descricao": { "type": "string" }
            },
            "required": ["codigo", "descricao"]
          }
        },
        "natureza_juridica": {
          "type": "object",
          "description": "Natureza jurídica da empresa.",
          "properties": {
            "codigo": { "type": "string", "description": "Código da natureza jurídica." },
            "descricao": { "type": "string", "description": "Descrição da natureza jurídica." }
          },
          "required": ["codigo", "descricao"]
        },
        "logradouro": { "type": "string", "description": "Nome da rua/avenida do endereço." },
        "numero": { "type": "string", "description": "Número do endereço." },
        "complemento": { "type": ["string", "null"], "description": "Complemento do endereço." },
        "bairro": { "type": "string", "description": "Bairro do endereço." },
        "cep": { "type": "string", "description": "CEP do endereço, sem formatação." },
        "municipio": { "type": "string", "description": "Nome do município." },
        "uf": { "type": "string", "description": "Sigla do estado (UF)." },
        "endereco_eletronico": {
          "type": ["string", "null"],
          "description": "E-mail de contato da empresa, quando disponível."
        },
        "telefone": {
          "type": ["string", "null"],
          "description": "Telefone de contato, quando disponível."
        },
        "situacao_cadastral": {
          "type": "string",
          "description": "Situação cadastral atual (ex: ATIVA, BAIXADA, SUSPENSA)."
        },
        "data_da_situacao_cadastral": {
          "type": "string",
          "format": "date",
          "description": "Data da última atualização da situação cadastral."
        },
        "porte": {
          "type": "string",
          "description": "Porte da empresa (ex: MICRO EMPRESA, EMPRESA DE PEQUENO PORTE, DEMAIS)."
        },
        "socios": {
          "type": "array",
          "description": "Quadro societário da empresa.",
          "items": { "type": "object" }
        }
      }
    }
  },
  "required": ["request_id", "success", "error"]
}