CPF na Receita Federal

Consulte nome, situação cadastral, data de nascimento e data de inscrição de um CPF, conforme os dados disponíveis. O mesmo endpoint permite consultar registros em cache ou buscar dados online na Receita Federal via SERPRO. Por padrão, a consulta usa somente o cache.

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, nunca faz uma tentativa online. Se não houver cadastro no cache, retorna HTTP 404 sem consumo de créditos, mesmo quando a data de nascimento foi informada. Nas demais estratégias, consulte as regras e os exemplos de erros abaixo.

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.

Como a consulta funciona

1. Envie uma requisição GET com o CPF no caminho e sua chave no header x-api-key. A consulta precisa estar habilitada para sua conta; entre em contato com a equipe comercial se receber uma negativa de acesso.
2. Escolha cache_strategy. Se o parâmetro for omitido, a API procura somente no cache (SO_CACHE). Informar a data de nascimento não muda essa escolha.
3. Quando a estratégia exigir acesso online, é necessário haver uma data de nascimento informada na requisição ou disponível no cadastro em cache, além de saldo suficiente para a modalidade online. Sem esses requisitos, a consulta online não é executada.
4. A resposta segue o layout de format e o formato de datas de date_format. Confira o status HTTP, os indicadores disponíveis e os campos do cadastro antes de utilizá-los na integração.

A consulta online utiliza a versão 3 do SERPRO. A rota da Sintegrapi continua /consultas/v2/cpf-rfb/{cpf}/{data_nascimento?}, com os mesmos layouts e campos. Envie a data em yyyyMMdd; a conversão para o formato exigido pela fonte é feita pela Sintegrapi.

O SERPRO pode fornecer um cadastro parcial, por exemplo sem data de inscrição. Quando há cadastro utilizável, a Sintegrapi mantém HTTP 200 e o custo da modalidade online; campos sem informação continuam ausentes ou nulos, conforme o contrato existente. Não preencha esses campos com valores fictícios na integração.

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 a idade máxima aceita para um registro na estratégia CACHE_PREFERENCIAL. Não é um prazo de armazenamento nem altera a idade dos dados aceitos nas outras estratégias. O cache é compartilhado para reutilizar dados cadastrais; a resposta não identifica 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:

O padrão geral sem date_format é 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.

Integrações legadas com um formato de compatibilidade acordado para a conta podem manter esse formato fixo, inclusive quando date_format é enviado. Confirme com o suporte antes de alterar uma integração com esse acordo.

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/CPF_VALIDO/19910807" \
  --data-urlencode "cache_strategy=SO_CACHE" \
  --data-urlencode "format=SINTEGRAPI" \
  --data-urlencode "date_format=yyyy-MM-dd" \
  -H "x-api-key: {apiKey}"

Estratégias de Cache

A estratégia define quando a API pode sair do cache e tentar a consulta online:

Exemplo: cache_strategy=CACHE_PREFERENCIAL&cache=7 aceita um cadastro atualizado nos últimos sete dias. O mesmo cache=7 não limita a idade de um resultado em SO_CACHE nem do fallback de ONLINE_PREFERENCIAL. O fallback não é uma nova consulta à fonte e pode conter dados antigos.

A modalidade online, inclusive SO_ONLINE, pode reutilizar uma resposta recente por até 24 horas. Uma resposta cadastral válida reutilizada mantém o custo da modalidade online; esse mecanismo é independente do cadastro usado por SO_CACHE. O retorno de menor de idade com código 451 preserva HTTP 451 e não consome créditos, inclusive quando identificado em uma resposta armazenada.

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, não há dados cadastrais para entregar e a API não tenta online.

Data de nascimento e consulta online

A data de nascimento é opcional na URL. Quando a estratégia exigir uma tentativa online, a API considera a data enviada; se não houver, procura a data no cadastro em cache. Sem nenhuma dessas informações, retorna HTTP 400 sem consumo de créditos e não executa a consulta online.

Para uma consulta atendida pelo cache, não é necessário enviar a data. A presença desse parâmetro não força a consulta online e não altera o custo por si só.

Consulta CPF Receita Federal

curl -G "https://api.sintegrapi.com.br/consultas/v2/cpf-rfb/CPF_VALIDO/19910807" \
  --data-urlencode "cache_strategy=CACHE_PREFERENCIAL" \
  --data-urlencode "cache=7" \
  --data-urlencode "format=SINTEGRAPI" \
  --data-urlencode "date_format=ddMMyyyy" \
  -H "x-api-key: {apiKey}"

{
  "serpro_result": {
    "ni": "12345678901",
    "nome": "PESSOA FICTICIA DE EXEMPLO",
    "nome_social": "NOME SOCIAL FICTICIO DE EXEMPLO",
    "situacao": {
      "codigo": "0",
      "descricao": "REGULAR"
    },
    "nascimento": "07081991",
    "data_inscricao": "16122024",
    "updated_at": "15092026"
  },
  "request_id": "63cae3c7-21b1-4735-b689-7300af6813e1",
  "success": true,
  "error": false,
  "cache": true
}

{
  "serpro_result": {
    "ni": "12345678901",
    "nome": "PESSOA FICTICIA DE EXEMPLO",
    "nome_social": "NOME SOCIAL FICTICIO DE EXEMPLO",
    "situacao": { "codigo": "0", "descricao": "REGULAR" },
    "nascimento": "1991-08-07",
    "data_inscricao": "2024-12-16",
    "updated_at": "2026-09-15"
  },
  "request_id": "63cae3c7-21b1-4735-b689-7300af6813e1",
  "success": true,
  "error": false,
  "cache": true
}

{
  "ni": "12345678901",
  "nome": "PESSOA FICTICIA DE EXEMPLO",
  "nome_social": "NOME SOCIAL FICTICIO DE EXEMPLO",
  "situacao": { "codigo": "0", "descricao": "REGULAR" },
  "nascimento": "1991-08-07",
  "data_inscricao": "2024-12-16"
}

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

Como interpretar a resposta e os erros

Esta rota possui diferenças entre o status HTTP, os indicadores e a presença de dados. Os exemplos abaixo descrevem o comportamento atual. request_id varia a cada chamada; os identificadores apresentados são ilustrativos.

Ausência de cadastro no cache

Em cache_strategy=SO_CACHE, quando o CPF não existe no cache, a API retorna HTTP 404 sem consumo de créditos. Informar a data de nascimento não aciona uma consulta online. Com format=SINTEGRAPI, a resposta contém success=false, error=true e a mensagem de ausência no cache:

{
  "serpro_result": {
    "code": "404",
    "message": "CPF não encontrado em cache."
  },
  "request_id": "11111111-1111-4111-8111-111111111111",
  "success": false,
  "error": true,
  "error_message": {
    "message": "CPF não encontrado em cache.",
    "code": "404"
  },
  "cache": true
}

Com format=SERPRO, o mesmo cenário retorna HTTP 404, preservando o layout selecionado e incluindo o motivo:

{
  "code": "404",
  "message": "CPF não encontrado em cache."
}

Esse retorno indica ausência na base de cache e não comprova a inexistência do CPF na Receita Federal. cache=true identifica o caminho utilizado, não a presença de dados. Nenhuma tentativa online é feita e a reserva inicial de um crédito é devolvida.

Consulta online sem data de nascimento disponível

Se a estratégia precisar consultar online e não houver data de nascimento na URL nem uma data disponível no cadastro em cache, a API retorna HTTP 400 sem consumo de créditos. A tentativa online não é feita. Por exemplo: cache_strategy=SO_ONLINE&cache=0, sem o segmento data_nascimento e sem cadastro em cache.

Com format=SINTEGRAPI, o erro contém a orientação para informar a data:

{
  "serpro_result": {
    "code": "400",
    "message": "Não é possível consultar online sem data de nascimento. Informe a data na requisição, pois ela não está disponível no cache."
  },
  "request_id": "11111111-1111-4111-8111-111111111111",
  "success": false,
  "error": true,
  "error_message": {
    "message": "Não é possível consultar online sem data de nascimento. Informe a data na requisição, pois ela não está disponível no cache.",
    "code": "400"
  },
  "cache": true
}

Com format=SERPRO, a mesma mensagem fica na raiz:

{
  "code": "400",
  "message": "Não é possível consultar online sem data de nascimento. Informe a data na requisição, pois ela não está disponível no cache."
}

Para permitir a tentativa online, envie a data no caminho: /consultas/v2/cpf-rfb/CPF_VALIDO/19910807?cache_strategy=SO_ONLINE&cache=0. O formato de entrada continua yyyyMMdd.

cache=0 não dispensa a data de nascimento, não impede o uso de uma data já conhecida no cadastro e não desativa a reutilização de respostas recentes por 24 horas na modalidade online. O parâmetro limita a idade do cadastro somente em CACHE_PREFERENCIAL. Nesse erro, cache=true indica que a chamada não chegou à etapa online; não significa que um cadastro foi encontrado.

Data de nascimento inválida para consulta online

Quando for necessário tentar online, a data enviada deve ser uma data existente em yyyyMMdd. Por exemplo, 20000230 e 2000-04-03 são rejeitadas com HTTP 400 e custo zero, antes de acessar a fonte. Corrija a data na URL; o parâmetro date_format altera apenas as datas da resposta.

{
  "serpro_result": {
    "code": "400",
    "message": "Data de Nascimento inválida. Utilize o formato yyyyMMdd (sem hífens)."
  },
  "request_id": "11111111-1111-4111-8111-111111111111",
  "success": false,
  "error": true,
  "error_message": {
    "message": "Data de Nascimento inválida. Utilize o formato yyyyMMdd (sem hífens).",
    "code": "400"
  },
  "cache": true
}

Com format=SERPRO, o mesmo erro é apresentado na raiz:

{
  "code": "400",
  "message": "Data de Nascimento inválida. Utilize o formato yyyyMMdd (sem hífens)."
}

Consulta recusada pelo SERPRO — HTTP 451

Segundo o guia de migração do SERPRO, a v3 não retorna mais 451 por menoridade. A Sintegrapi mantém o tratamento abaixo por compatibilidade, caso esse código seja recebido. Uma consulta que retorne dados cadastrais segue o custo normal da modalidade.

Se a fonte retornar 451, a API preserva HTTP 451 nos dois layouts, sem cobrança. No layout SINTEGRAPI, o retorno contém success=false e error=true. O código e a mensagem ficam em serpro_result e error_message; esse retorno não disponibiliza dados cadastrais. Créditos reservados são devolvidos na finalização, inclusive quando a restrição é identificada em uma resposta armazenada.

{
  "serpro_result": {
    "code": "451",
    "message": "Consulta não permitida pelo SERPRO para este CPF (menor de idade)."
  },
  "request_id": "11111111-1111-4111-8111-111111111111",
  "success": false,
  "error": true,
  "error_message": {
    "message": "Consulta não permitida pelo SERPRO para este CPF (menor de idade).",
    "code": "451"
  },
  "cache": false
}

{
  "code": "451",
  "message": "Consulta não permitida pelo SERPRO para este CPF (menor de idade)."
}

Falha na consulta online sem fallback

Quando a tentativa online falha e nenhum cadastro utilizável é entregue, nem da fonte nem por fallback, a API retorna HTTP 503 sem cobrança. Isso inclui timeout, resposta vazia ou inválida e indisponibilidade da consulta. No layout SINTEGRAPI:

{
  "request_id": "11111111-1111-4111-8111-111111111111",
  "success": false,
  "error": true,
  "error_message": {
    "message": "Ocorreu um erro ao consultar o CPF. Tente novamente em instantes",
    "code": "503"
  },
  "cache": false
}

O status HTTP é 503, success=false e error=true. serpro_result é omitido porque não há cadastro disponível. O código em error_message.code é a string "503".

Com format=SERPRO, o mesmo cenário retorna HTTP 503, com o código e a mensagem na raiz:

{
  "code": "503",
  "message": "Ocorreu um erro ao consultar o CPF. Tente novamente em instantes"
}

Esse retorno indica que a consulta não pôde ser concluída; ele não comprova que o CPF inexiste na fonte. Aguarde antes de repetir a tentativa.

Se a falha ocorrer antes de iniciar a chamada à fonte, o indicador cache do envelope pode ser true, mesmo sem cadastro retornado; o erro continua sem cobrança. Se houver cadastro utilizável entregue por fallback em ONLINE_PREFERENCIAL, o retorno contém os dados, com error=false, e segue a regra descrita em Custos.

CPF não encontrado na fonte online

Quando a fonte informa que o CPF não foi encontrado, a API retorna HTTP 404 sem cobrança. No layout SINTEGRAPI:

{
  "serpro_result": {
    "code": "404",
    "message": "CPF não encontrado na Receita Federal"
  },
  "request_id": "11111111-1111-4111-8111-111111111111",
  "success": false,
  "error": true,
  "error_message": {
    "message": "CPF não encontrado na Receita Federal",
    "code": "404"
  },
  "cache": false
}

Com format=SERPRO, o retorno também é HTTP 404, com o seguinte corpo:

{
  "code": "404",
  "message": "CPF não encontrado na Receita Federal"
}

Validação, acesso, saldo e limite de uso

Esses retornos não são convertidos para o layout escolhido em format. Uma chamada com format=SERPRO também deve aceitar os formatos descritos abaixo.

Regra de leitura para a integração

No layout SINTEGRAPI, confira error_message, os indicadores e a presença de serpro_result.ni. No layout SERPRO, confira o status HTTP, ni e as mensagens que estiverem presentes. Um objeto vazio deve ser tratado como consulta sem cadastro utilizável, mesmo com HTTP 200.

O campo cache não deve ser usado sozinho para calcular o custo ou comprovar atualização dos dados: uma tentativa online com fallback pode manter a indicação online. Consulte Custos e o consumo registrado no painel.

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 success, error e os campos do cadastro antes de atualizar seu sistema; um objeto serpro_result vazio não é um cadastro válido. 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": "Indicador da consulta; avalie junto com error e com a presença dos dados em serpro_result."
    },
    "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. Pode estar vazio, ausente ou nulo; confira ni e os campos necessários antes de utilizar o cadastro.",
      "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."
        },
        "nome_social": {
          "type": ["string", "null"],
          "description": "Nome social informado pela fonte ou disponível no cache, quando houver. Não substitui nome e é omitido quando ausente."
        },
        "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. Isoladamente, não comprova atualização dos dados nem o custo final, inclusive em fallback."
    }
  },
  "required": ["request_id", "success", "error"],
  "additionalProperties": true
}