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.

Custos

Os valores são o total por requisição, não créditos adicionais. A consulta online custa 10 créditos no total, e não 11. A estratégia padrão, SO_CACHE, utiliza apenas o cache; se não houver resultado, retorna erro sem consumo de créditos.

Na estratégia ONLINE_PREFERENCIAL, uma tentativa online pode terminar com a entrega de dados em cache após falha da fonte e manter o custo de 10 créditos. Para consultar exclusivamente pelo custo de cache, utilize SO_CACHE.

Crédito é a unidade de consumo do plano. Consulte o valor dos planos e a tabela de Consumo por consulta.

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

Formato das datas da resposta

O mesmo endpoint aceita o parâmetro opcional date_format na query string. Escolha o formato esperado pela sua integração:

Sem date_format, a resposta utiliza ddMMyyyy. A escolha vale para as datas disponíveis nas respostas online, em cache e em fallback. Campos sem informação continuam ausentes ou nulos. Outros valores de date_format retornam HTTP 400, sem executar a consulta ou consumir créditos.

O parâmetro format continua definindo a estrutura da resposta: SINTEGRAPI (padrão) inclui os dados em serpro_result; SERPRO retorna os dados diretamente, sem esse envelope. O parâmetro date_format funciona com os dois layouts. O campo updated_at é apresentado somente no layout SINTEGRAPI, quando disponível.

A data de nascimento enviada no caminho da requisição permanece em yyyyMMdd, independentemente do formato escolhido para a resposta.

curl -G "https://api.sintegrapi.com.br/consultas/v2/cpf-rfb/12345678901/19910807" \
  --data-urlencode "cache_strategy=SO_CACHE" \
  --data-urlencode "date_format=yyyy-MM-dd" \
  -H "x-api-key: {apiKey}"

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",
    "updated_at": "15092026"
  },
  "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

Integre a consulta de CPF na Receita Federal ao cadastro de pessoas físicas para conferir o documento, o nome e a situação cadastral retornados. O fluxo é implementado com chamadas HTTPS no servidor da integração.

Consulta CPF no TOTVS Protheus, SAP e Dynamics 365

Em projetos com TOTVS Protheus, TOTVS RM, SAP S/4HANA, SAP Business One, Oracle Fusion Cloud ou Microsoft Dynamics 365, associe a resposta ao cadastro da pessoa física pelo CPF. A equipe de integração adapta os campos e as permissões à versão contratada do sistema.

Validação de contatos no Salesforce, HubSpot e Zoho CRM

No Salesforce, HubSpot, Pipedrive ou Zoho CRM, a consulta pode compor uma etapa de conferência do contato antes de avançar o processo comercial. Restrinja o acesso aos dados pessoais às pessoas e rotinas autorizadas e mantenha a API key fora do navegador.

Escolha a estratégia de consulta considerando os custos de cache e online descritos na seção Custos. O resultado cadastral não representa uma análise de crédito. Use o JSON Schema da resposta e trate a ausência de serpro_result antes de mapear campos.

JSON Schema da Resposta

O schema usa JSON Schema Draft 2020-12. Os campos de negócio podem ser omitidos ou nulos quando não há informação disponível ou quando ocorre um erro. Valide também success e error antes de atualizar o cadastro. Propriedades adicionais são aceitas para permitir evolução compatível. O schema descreve o corpo JSON; o código HTTP deve ser tratado separadamente.

Este schema representa o layout padrão format=SINTEGRAPI. As três propriedades de data aceitam ddMMyyyy ou yyyy-MM-dd, conforme o date_format escolhido na requisição; o padrão é ddMMyyyy. Com format=SERPRO, os campos de serpro_result ficam diretamente no corpo e updated_at não é incluído.

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "title": "CPF Receita Federal — Resposta",
  "type": "object",
  "properties": {
    "request_id": { "type": "string", "format": "uuid" },
    "success": {
      "type": "boolean",
      "description": "Resultado funcional da consulta; avalie junto com error."
    },
    "error": {
      "type": "boolean",
      "description": "Indica falha técnica ou de validação."
    },
    "error_message": {
      "type": ["object", "null"],
      "properties": {
        "message": {
          "type": ["string", "null"],
          "description": "Mensagem pública da consulta."
        },
        "code": {
          "type": ["string", "null"],
          "description": "Código público, quando informado."
        }
      }
    },
    "serpro_result": {
      "type": ["object", "null"],
      "description": "Dados cadastrais retornados pela Receita Federal. Presente apenas quando success=true.",
      "properties": {
        "ni": {
          "type": ["string", "null"],
          "description": "Número de Inscrição (CPF) do contribuinte, sem formatação."
        },
        "nome": {
          "type": ["string", "null"],
          "description": "Nome completo da pessoa física."
        },
        "situacao": {
          "type": ["object", "null"],
          "description": "Situação cadastral do CPF.",
          "properties": {
            "codigo": {
              "type": ["string", "null"],
              "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", "null"],
              "description": "Descrição textual da situação cadastral."
            }
          }
        },
        "nascimento": {
          "type": ["string", "null"],
          "pattern": "^([0-9]{8}|[0-9]{4}-[0-9]{2}-[0-9]{2})$",
          "description": "Data de nascimento em ddMMyyyy (padrão) ou yyyy-MM-dd, conforme date_format."
        },
        "data_inscricao": {
          "type": ["string", "null"],
          "pattern": "^([0-9]{8}|[0-9]{4}-[0-9]{2}-[0-9]{2})$",
          "description": "Data de inscrição no CPF em ddMMyyyy (padrão) ou yyyy-MM-dd, conforme date_format."
        },
        "code": { "type": ["string", "null"] },
        "message": { "type": ["string", "null"] },
        "description": { "type": ["string", "null"] },
        "updated_at": {
          "type": ["string", "null"],
          "pattern": "^([0-9]{8}|[0-9]{4}-[0-9]{2}-[0-9]{2})$",
          "description": "Data de atualização do cadastro em ddMMyyyy (padrão) ou yyyy-MM-dd, conforme date_format, quando informada."
        }
      }
    },
    "cache": {
      "type": ["boolean", "null"],
      "description": "Indicação de cache apresentada pela consulta."
    }
  },
  "required": ["request_id", "success", "error"],
  "additionalProperties": true
}