Ir para o conteúdo

Lançamento: Consulta CPF v3

Prezado(a) Cliente,

Informamos que desde 29/05/2026 já está disponível a nova versão do produto Consulta CPF, com mudanças na forma de consulta e no retorno das informações, conforme regulamentado pela Portaria RFB nº 667, de 24 de Março de 2026.

O que muda?

Como migrar?

Importante: Versões anteriores

As versões anteriores continuarão funcionando até 20/09/2026. Após essa data, serão desativadas — por isso, é importante realizar a migração o quanto antes, a partir da data de lançamento em 29/05/2026.

Documentação e testes

Acesse a documentação

Você pode testar gratuitamente pelo menu “Demonstração” na página do produto.

Atenção

Não haverá ambiente separado de testes para a v3. Todas as requisições realizadas no endpoint serão contabilizadas como consumo em produção.

GUIA DE APOIO À MIGRAÇÃO

Perguntas frequentes para uma migração segura

Em suma, a versão 3 exige CPF e data de nascimento na consulta, utiliza novo endpoint e deixa de retornar o campo ano de óbito. A contratação e as credenciais atuais são mantidas, mas a integração precisa ser atualizada dentro do cronograma de migração.

Sobre a Consulta CPF V3

1. O que é a Consulta CPF?

É uma API REST do Serpro que permite consultar informações cadastrais de pessoas físicas diretamente na base da Receita Federal do Brasil. O serviço apoia validações cadastrais automatizadas e retorna a situação do CPF, conforme as regras e os campos previstos na documentação técnica.

2. O que é a Consulta CPF V3?

É a nova versão da API Consulta CPF. Ela está disponível desde 29 de maio de 2026 e altera a forma de realizar a consulta e parte das informações retornadas.

3. Quais são as principais mudanças da versão 3?

As principais mudanças são a inclusão da data de nascimento na chave de consulta, a adoção de um novo endpoint e a retirada do campo ano de óbito do retorno da API.

4. Por que agora é necessário informar a data de nascimento?

Na versão 3, a data de nascimento passou a compor a chave de consulta com o número do CPF. Os dois dados são utilizados para validar a correspondência com o cadastro da Receita Federal antes do retorno das informações. A documentação pública do produto não indica um ato normativo específico da Receita Federal associado a essa alteração.

5. É possível consultar somente com o número do CPF?

Não na versão 3. Para realizar a consulta, é obrigatório informar o número do CPF e a data de nascimento do titular.

6. Qual é o formato da data de nascimento?

A data deve ser enviada no formato DDMMAAAA, sem barras ou outros separadores. Exemplo: 14 de novembro de 1970 deve ser informado como 14111970.

7. O que fazer se a instituição não possuir a data de nascimento?

A API não oferece uma chave alternativa para a versão 3. A instituição deverá avaliar seus processos de cadastro e atualização de dados e obter a informação por meio legítimo, compatível com a finalidade do tratamento e com as regras de proteção de dados aplicáveis. O Serpro não fornece, por meio desta API, um mecanismo para descobrir previamente a data de nascimento a partir apenas do CPF.

8. O que acontece quando a data de nascimento informada não corresponde ao CPF?

A consulta não será validada como uma correspondência bem-sucedida. A aplicação cliente deve tratar o retorno conforme o código e a mensagem apresentados pela API e orientar a conferência dos dados informados.

Informações retornadas e regras de consulta

9. Quais informações podem ser retornadas pela Consulta CPF V3?

Conforme a documentação do produto e a disponibilidade do cadastro consultado, o retorno pode incluir número do CPF, nome, situação cadastral, data de nascimento, data de inscrição e nome social. O campo ano de óbito foi removido da versão 3.

10. Quais situações cadastrais podem ser apresentadas?

A API prevê os seguintes status: Regular; Suspensa; Titular Falecido; Pendente de Regularização; Cancelada por Multiplicidade; Nula; e Cancelada de Ofício.

11. Situação cadastral regular significa ausência de débitos?

Não. A situação cadastral do CPF é diferente da situação fiscal do contribuinte. O status Regular indica que não há pendência cadastral no CPF, mas não comprova a inexistência de débitos ou outras pendências fiscais.

12. A API retorna dados de menores de idade?

A API Consulta CPF V3, diferentemente das versões anteriores, retorna integralmente os dados de menor. Não existe mais os códigos de retorno HTTP 451 para dados de menores de 16 anos e HTTP 422 para dados de menores de 18 anos. Cabe à sua aplicação calcular a idade com base na data de nascimento.

13. O que significa o retorno 206 - Conteúdo Parcial?

Significa que a consulta foi processada, mas nem todos os campos esperados estavam disponíveis. A documentação informa que isso pode ocorrer, por exemplo, quando o cadastro não possui data de inscrição ou outro campo considerado obrigatório para o retorno.

Migração e integração

14. É necessário assinar um novo contrato?

Não. Os clientes atuais podem migrar para a versão 3 sem a assinatura de um novo contrato.

15. As credenciais de acesso serão alteradas?

Não. A Consumer Key e a Consumer Secret atuais continuam válidas. Essas credenciais identificam o contrato e devem permanecer protegidas.

16. Qual é o novo endpoint?

O endpoint informado para a versão 3 é https://gateway.apiserpro.serpro.gov.br/consulta-cpf-df/v3. Consulte a referência técnica para compor corretamente o caminho completo da requisição. O gateway diferencia letras maiúsculas de minúsculas, por isso o endereço deve ser utilizado exatamente como documentado.

17. Como funciona a autenticação?

A API utiliza OAuth 2.0. O cliente usa a Consumer Key e a Consumer Secret para solicitar um Bearer Token temporário. A documentação informa validade de uma hora para o token, que deve ser renovado após a expiração.

18. Quais passos são recomendados para a migração?

Recomenda-se mapear os sistemas que utilizam a API, verificar a disponibilidade e a qualidade das datas de nascimento, adequar a requisição ao novo formato, atualizar o endpoint, revisar o tratamento dos códigos de retorno, executar testes e acompanhar a entrada em produção.

19. Existe ambiente de testes?

A documentação oferece uma API de demonstração com CPFs fictícios e respostas simuladas para conhecer o funcionamento da solução. Entretanto, não há um ambiente separado de homologação com dados reais para a versão 3. As consultas realizadas no endpoint de produção são contabilizadas como consumo.

20. Qual é o prazo para concluir a migração?

As versões anteriores serão desativadas em 20 de setembro de 2026. A partir dessa data, as consultas deverão ser realizadas pela versão 3, com CPF e data de nascimento. Recomenda-se concluir o desenvolvimento e os testes com antecedência.

21. O uso simultâneo das versões anteriores e da V3 exige outra contratação?

Não. Durante o período de transição, o cliente pode adequar gradualmente sua integração dentro do contrato existente. As chamadas realizadas em produção continuam sujeitas às regras de consumo e faturamento do produto.

Retornos, faturamento e suporte

22. Quais códigos de retorno não são contabilizados no faturamento?

Segundo a documentação técnica, não são bilhetados os retornos 400 (requisição inválida), 401 (não autorizado), 403 (proibido), 500 (erro no servidor) e 504 (tempo esgotado do gateway). Para os demais códigos, consulte as regras vigentes do produto e do contrato.

23. O que significam os principais códigos HTTP?

De forma resumida: 200 indica consulta validada com sucesso; 206, conteúdo parcial; 400, CPF inválido ou requisição inválida; 401, problema de autenticação; 403, acesso ou caminho não autorizado; 404, CPF não encontrado; 500, erro interno; e 504, tempo de resposta esgotado no gateway. Na versão 3 não existe mais os códigos de retorno 451 para dados de menores de 16 anos e 422 para dados de menores de 18 anos.

24. Que cuidados devem ser adotados com a data de nascimento?

A data de nascimento é um dado pessoal. A instituição deve definir finalidade e base legal para o tratamento, limitar o acesso, proteger a informação durante armazenamento e transmissão, revisar prazos de retenção e evitar o uso do dado para finalidades incompatíveis. A adequação à API não substitui a avaliação de privacidade da própria organização.

25. Onde consultar a documentação e solicitar suporte?

A documentação técnica está disponível no API Center do Serpro. Clientes que encontrem dificuldades na migração devem registrar uma solicitação de suporte pelos canais da Central de Ajuda ou pela Área do Cliente, informando o código de retorno, o horário da ocorrência e o contexto técnico, sem encaminhar credenciais ou dados pessoais desnecessários.

Gravação de apoio a Migração

Atenciosamente,

Equipe Serpro

Última atualização: 1 de setembro de 2026
Criada: 2 de junho de 2026