CPF na Receita Federal

Nossa API permite consultar dados cadastrais completos de pessoas físicas diretamente na Receita Federal do Brasil. Obtenha informações como nome completo, situação cadastral, data de nascimento e data de inscrição no CPF, com possibilidade de utilizar cache ou realizar consultas online em tempo real.

Informações de entrada

Para consultar um CPF, utilize os seguintes parâmetros:

CPF: O número do Cadastro de Pessoa Física (CPF) que deseja consultar.

Data de Nascimento: Informação opcional e recomendada. Quando uma estratégia exigir consulta online, a API usará a data informada pelo cliente ou tentará obter uma data previamente armazenada em cache para o CPF.

Cache: define o tempo máximo, em dias, para reutilização de uma resposta previamente obtida pela plataforma. O cache é mantido de forma centralizada pela Sintegrapi para otimizar desempenho, reduzir custos e evitar consultas repetidas às fontes de dados. O uso do cache não concede a nenhum cliente acesso a informações de outro cliente, nem permite identificar quem realizou consultas anteriores.

Cache Strategy: Define o comportamento da consulta (prioridade entre cache e online). Este é o parâmetro que determina o modo de execução da consulta.

Parâmetros Obrigatórios

Parâmetros Opcionais

Estratégias de Cache

A API oferece diferentes estratégias para balancear entre performance, custo e atualização dos dados:

Quando usar a estratégia SO_CACHE

• Ideal para validações rápidas.
• Pode ser utilizada quando a data de nascimento não está disponível.
• Indicada para cenários de alto volume com foco em redução de custos.
• Nunca realiza consultas online junto à Receita Federal.
• Retorna apenas registros previamente armazenados em cache.
• Caso o CPF não exista em cache, retorna não encontrado.

Observações Importantes

• Recomendamos sempre informar a data de nascimento nas consultas de CPF. Essa é a melhor prática para aumentar a taxa de sucesso nas estratégias que podem consultar a Receita Federal online.
• A presença ou ausência da data de nascimento não define sozinha se a consulta será em cache ou online. Quem define o comportamento é o parâmetro cache_strategy.
• Quando a estratégia envolver consulta online (SO_ONLINE, ONLINE_PREFERENCIAL, CACHE_PREFERENCIAL ou CACHE_SE_EXISTIR em caso de cache miss), a API tentará usar a data de nascimento enviada na requisição.
• Se a data de nascimento não for informada pelo cliente, a API tentará utilizar uma data de nascimento previamente armazenada em cache para o CPF consultado.
• Se existir uma data de nascimento válida em cache, a consulta online será executada normalmente.
• Se não houver data de nascimento disponível em cache e ela também não tiver sido informada na requisição, a consulta online não poderá ser realizada e a API retornará erro informando que a data de nascimento é obrigatória para consulta online.
• Consultas online possuem custo superior às consultas em cache.
• Consulte a página /preços para verificar os valores atualizados.
• Para cenários de alto volume, recomenda-se utilizar cache sempre que possível.
• A situação cadastral retornada pela Receita Federal permite validar a regularidade do CPF consultado.
• A API retorna informações como CPF, nome completo, situação cadastral, data de nascimento e data de inscrição no CPF.

Consulta CPF Receita Federal

curl -G https://api.sintegrapi.com.br/consultas/v2/cpf-rfb/12345678901/19910807?cache_strategy=CACHE_PREFERENCIAL \
  -H "x-api-key: {apiKey}"

{
  "serpro_result": {
    "ni": "12345678901",
    "nome": "JOAO DA SILVA",
    "situacao": {
      "codigo": "0",
      "descricao": "REGULAR"
    },
    "nascimento": "07081991",
    "data_inscricao": "16122024"
  },
  "request_id": "63cae3c7-21b1-4735-b689-7300af6813e1",
  "success": true,
  "error": false
}

Retornos Possíveis no Campo situacao (Situações Cadastrais)

Respostas de Erro

A API retorna diferentes tipos de resposta dependendo da situação encontrada:

CPF Não Encontrado

Quando o CPF não é localizado (seja em cache ou online):

{
  "request_id": "f1bba1c4-fc11-44e6-a9f9-8a816d3df148",
  "success": false,
  "error": false,
  "error_message": {
    "message": "CPF Não localizado",
    "code": "404"
  }
}

CPF Inválido

Quando o CPF informado possui formato inválido ou dígitos verificadores incorretos:

{
  "request_id": "73975659-b432-4ef4-a461-f654b2143776",
  "success": false,
  "error": true,
  "error_message": {
    "message": "CPF inválido."
  }
}

Códigos de Erro Comuns

Integração com CRMs e ERPs

O retorno estruturado deste endpoint é compatível com os principais sistemas de gestão e automação empresarial. Os campos seguem tipagem previsível e nomenclatura consistente, facilitando o mapeamento em plataformas como Salesforce, SAP S/4HANA, Microsoft Dynamics 365, HubSpot, Zoho CRM e Oracle Fusion Cloud.

Para integrações via iPaaS, o schema da resposta pode ser importado diretamente em ferramentas como MuleSoft Anypoint, Dell Boomi, Workato, Make (Integromat) e Azure Logic Apps, acelerando a criação de fluxos de validação de cadastro de pessoas físicas.

Use o JSON Schema abaixo para:

• Validar automaticamente as respostas antes de persistir no CRM ou banco de dados
• Gerar classes e DTOs com ferramentas como Quicktype
• Configurar mapeamentos de campos em conectores de integração
• Documentar contratos de API internos

JSON Schema da Resposta

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "title": "CPF 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": ["object", "null"],
      "description": "Objeto com detalhes do erro, quando aplicável.",
      "properties": {
        "message": { "type": "string", "description": "Mensagem descritiva do erro." },
        "code": { "type": "string", "description": "Código do erro (ex: 404)." }
      }
    },
    "serpro_result": {
      "type": ["object", "null"],
      "description": "Dados cadastrais retornados pela Receita Federal. Presente apenas quando success=true.",
      "properties": {
        "ni": {
          "type": "string",
          "description": "Número de Inscrição (CPF) do contribuinte, sem formatação."
        },
        "nome": {
          "type": "string",
          "description": "Nome completo da pessoa física."
        },
        "situacao": {
          "type": "object",
          "description": "Situação cadastral do CPF.",
          "properties": {
            "codigo": {
              "type": "string",
              "enum": ["0", "2", "3", "4", "5", "8", "9"],
              "description": "Código da situação: 0=Regular, 2=Suspensa, 3=Titular Falecido, 4=Pendente de Regularização, 5=Cancelada por Multiplicidade, 8=Nula, 9=Cancelada de Ofício."
            },
            "descricao": {
              "type": "string",
              "description": "Descrição textual da situação cadastral."
            }
          },
          "required": ["codigo", "descricao"]
        },
        "nascimento": {
          "type": "string",
          "description": "Data de nascimento no formato ddMMaaaa."
        },
        "data_inscricao": {
          "type": "string",
          "description": "Data de inscrição no CPF no formato ddMMaaaa."
        }
      },
      "required": ["ni", "nome", "situacao"]
    }
  },
  "required": ["request_id", "success", "error"]
}