# API de CPF: como consultar data de nascimento pelo número do documento > Saiba como obter a data de nascimento associada a um CPF usando uma API REST. Veja exemplos em Python, JavaScript e cURL. **Publicado:** 06/08/2024 **Autor:** Redação CPFHub.io **URL:** https://cpfhub.io/blog/api-de-cpf-como-consultar-data-de-nascimento-pelo-numero-do-documento --- A API da CPFHub.io permite consultar a data de nascimento associada a um CPF com uma única chamada GET autenticada. A resposta retorna a data completa no campo `birthDate` (formato DD/MM/YYYY) e também os campos numéricos `day`, `month` e `year`, prontos para cálculos de idade sem parsing manual — com latência de aproximadamente 900ms. ## Introdução Consultar a data de nascimento associada a um CPF é uma necessidade comum em processos de verificação de identidade, validação de idade mínima e prevenção de fraudes. Plataformas de e-commerce, fintechs, casas de apostas e sistemas de saúde frequentemente precisam confirmar a idade do titular do documento antes de autorizar operações. --- ## Quando a data de nascimento do CPF é necessária? A consulta à data de nascimento vinculada a um CPF atende a diversas necessidades de negócio: * **Verificação de idade mínima** -- Plataformas de apostas e serviços financeiros precisam confirmar que o usuário tem 18 anos ou mais antes de liberar o acesso. * **Processos de KYC** -- O cruzamento da data de nascimento informada pelo usuário com a data oficial ajuda a detectar tentativas de fraude no cadastro. * **Segmentação de clientes** -- A faixa etária do titular pode ser usada para personalizar ofertas e comunicações. * **Conformidade regulatória** -- Setores regulados exigem a verificação de dados cadastrais como parte dos processos de compliance. --- ## Como a API retorna a data de nascimento A API da [**CPFHub.io**](https://www.cpfhub.io/) retorna os dados de nascimento em três campos distintos, facilitando tanto a exibição formatada quanto cálculos programáticos de idade. ### Campos relacionados à data de nascimento | Campo | Tipo | Exemplo | Descrição | | --- | --- | --- | --- | | birthDate | string | "15/06/1990" | Data completa no formato DD/MM/YYYY | | day | number | 15 | Dia de nascimento | | month | number | 6 | Mês de nascimento | | year | number | 1990 | Ano de nascimento | Essa estrutura facilita tanto a exibição formatada quanto cálculos programáticos de idade, sem necessidade de parsing manual da string. --- ## Exemplo de consulta com cURL ```bash curl -X GET https://api.cpfhub.io/cpf/12345678900 \ -H "x-api-key: SUA_CHAVE_DE_API" \ -H "Accept: application/json" \ --max-time 10 ``` **Resposta:** ```json { "success": true, "data": { "cpf": "12345678900", "name": "Maria Oliveira", "nameUpper": "MARIA OLIVEIRA", "gender": "F", "birthDate": "22/03/1985", "day": 22, "month": 3, "year": 1985 } } ``` --- ## Implementação em JavaScript com cálculo de idade O exemplo abaixo consulta o CPF via API e calcula a idade do titular a partir dos campos numéricos retornados: ```javascript async function consultarIdadePorCPF(cpf) { const controller = new AbortController(); const timeoutId = setTimeout(() => controller.abort(), 10000); try { const response = await fetch( `https://api.cpfhub.io/cpf/${cpf}`, { headers: { 'x-api-key': 'SUA_CHAVE_DE_API', 'Accept': 'application/json' }, signal: controller.signal } ); clearTimeout(timeoutId); const resultado = await response.json(); if (!resultado.success) { return { erro: 'CPF não encontrado' }; } const { day, month, year } = resultado.data; const hoje = new Date(); let idade = hoje.getFullYear() - year; if ( hoje.getMonth() + 1 < month || (hoje.getMonth() + 1 === month && hoje.getDate() < day) ) { idade--; } return { nome: resultado.data.name, dataNascimento: resultado.data.birthDate, idade }; } catch (error) { if (error.name === 'AbortError') { return { erro: 'Timeout na requisição' }; } return { erro: error.message }; } } // Uso consultarIdadePorCPF('12345678900').then(console.log); ``` --- ## Implementação em Python com verificação de idade mínima ```python import requests from datetime import date def verificar_idade_minima(cpf, idade_minima=18): url = f"https://api.cpfhub.io/cpf/{cpf}" headers = { "x-api-key": "SUA_CHAVE_DE_API", "Accept": "application/json" } response = requests.get(url, headers=headers, timeout=10) dados = response.json() if not dados.get("success"): return {"aprovado": False, "motivo": "CPF não encontrado"} ano = dados["data"]["year"] mes = dados["data"]["month"] dia = dados["data"]["day"] nascimento = date(ano, mes, dia) hoje = date.today() idade = hoje.year - nascimento.year if (hoje.month, hoje.day) < (nascimento.month, nascimento.day): idade -= 1 if idade < idade_minima: return { "aprovado": False, "motivo": f"Idade {idade} abaixo do mínimo de {idade_minima}" } return { "aprovado": True, "nome": dados["data"]["name"], "idade": idade } # Uso resultado = verificar_idade_minima("12345678900") print(resultado) ``` --- ## Casos de uso por setor ### Plataformas de apostas e iGaming A regulamentação de apostas online no Brasil exige que todos os apostadores tenham pelo menos 18 anos. A consulta à data de nascimento via API permite automatizar essa verificação no momento do cadastro, sem depender de upload de documentos. ### Fintechs e bancos digitais Na abertura de contas digitais, a data de nascimento é um dos campos obrigatórios para processos de KYC. A comparação entre a data informada pelo usuário e a data oficial retornada pela API é uma camada adicional de segurança contra fraudes. ### E-commerce Em compras de produtos com restrição de idade (bebidas alcoólicas, por exemplo), a consulta pode ser feita no checkout para confirmar que o comprador atende aos requisitos legais. ### Sistemas de saúde Hospitais e clínicas podem usar a data de nascimento para confirmar a identidade do paciente e calcular a faixa etária para fins de triagem ou dosagem de medicamentos. --- ## Boas práticas ao consultar data de nascimento via API * **Valide o CPF sintaticamente antes da consulta** -- Verifique os dígitos verificadores localmente para evitar requisições desnecessárias à API. * **Use os campos numéricos para cálculos** -- Os campos `day`, `month` e `year` são mais confiáveis para cálculos de idade do que o parsing da string `birthDate`. * **Armazene apenas o necessário** -- Em conformidade com a LGPD, armazene somente os dados que sua aplicação realmente precisa. Se apenas a verificação de idade é necessária, não é preciso guardar a data completa. * **Configure timeout nas requisições** -- Sempre defina um timeout (recomendado: 10 segundos) para evitar travamentos na aplicação. * **Trate o cenário de CPF não encontrado** -- Nem todo CPF retornará dados. Implemente fallbacks adequados para esse cenário. --- ## Perguntas frequentes ### O que é necessário para implementar validação de CPF neste contexto? A validação de CPF exige uma chamada à API com o número do documento e a chave de autenticação. A CPFHub.io retorna o status do CPF, nome do titular e data de nascimento em menos de 200ms, permitindo a verificação em tempo real durante o cadastro ou transação. ### A API CPFHub.io funciona para todos os volumes de consulta? Sim. O plano gratuito oferece 50 consultas por mês sem cartão de crédito — ideal para testes e projetos pequenos. Para volumes maiores, o plano Pro inclui 1.000 consultas mensais por R$149. Se o limite for ultrapassado, a API não bloqueia: cobra R$0,15 por consulta adicional. ### Como garantir conformidade com a LGPD ao usar uma API de CPF? Use o CPF apenas para a finalidade declarada ao titular, armazene apenas o necessário (não guarde o CPF cru se um token bastar), implemente controle de acesso aos logs de consulta e documente a base legal para o tratamento. A [ANPD](https://www.gov.br/anpd) orienta que dados de identificação devem ser tratados com o princípio da necessidade. ### Quanto tempo leva para integrar a API CPFHub.io? A integração básica leva menos de 30 minutos: crie uma conta em cpfhub.io, gere a API key no painel e faça uma chamada GET para `https://api.cpfhub.io/cpf/{CPF}` com o header `x-api-key`. A documentação inclui exemplos em Python, Node.js, PHP, Java e outras linguagens. ### Leia também - [Diferença entre validação de CPF e consulta de CPF: quando usar cada uma](https://cpfhub.io/blog/diferenca-entre-validacao-de-cpf-e-consulta-de-cpf-quando-usar-cada-uma) - [API de CPF grátis para desenvolvedores: como começar em 5 minutos](https://cpfhub.io/blog/api-cpf-gratis-desenvolvedores-comecar-5-minutos) - [Onboarding digital em fintechs: como validar CPF em menos de 30 segundos](https://cpfhub.io/blog/onboarding-digital-em-fintechs-como-validar-cpf-em-menos-de-30-segundos) - [KYC no Brasil: quais setores são obrigados a validar CPF por lei](https://cpfhub.io/blog/kyc-no-brasil-quais-setores-sao-obrigados-a-validar-cpf-por-lei) --- ## Conclusão A consulta à data de nascimento pelo número do CPF é um recurso valioso para verificação de idade, prevenção de fraudes e processos de KYC. A API da [**CPFHub.io**](https://www.cpfhub.io/) retorna os campos `birthDate`, `day`, `month` e `year` em uma única chamada, tornando o cálculo de idade direto e seguro para qualquer linguagem ou plataforma. Com tempo de resposta de aproximadamente 900ms e plano gratuito com 50 consultas por mês sem cartão de crédito, a integração pode ser testada imediatamente. Cadastre-se em [cpfhub.io](https://www.cpfhub.io/) — 50 consultas mensais gratuitas, sem cartão de crédito — e comece a verificar idades e validar identidades em tempo real nos seus fluxos de cadastro.