Referência

JSON da consulta CPF: campos nome, mãe e nascimento

Entenda a estrutura JSON da consulta CPF, os tipos dos campos e como evitar erros ao ler dados cadastrais.

Imagem editorial sobre Entendendo os campos JSON
Entendendo os campos JSON.

Como ler o JSON da consulta de CPF

Uma API de consulta CPF geralmente responde com um objeto JSON, mas o contrato de campos deve ser conferido em cada fornecedor. Na API CPF, o formato de sucesso documentado apresenta code e data, que inclui os campos cpf, nome, mae, genero e data_nascimento.

{
  "code": 200,
  "data": {
    "cpf": "52998224725",
    "nome": "Maria Aparecida da Silva",
    "mae": "Ana da Silva",
    "genero": "F",
    "data_nascimento": "1988-03-12"
  }
}

Dados demonstrativos publicados na documentação, sem confirmação de identidade. O formato pode mudar conforme o versionamento do serviço; sempre consulte o contrato atualizado.

Entenda cada campo

Campo Papel na estrutura Cuidado ao usar
code Código lógico da resposta Não substitui HTTP status
data.cpf Identificador consultado Tratar como dado pessoal
data.nome Nome cadastral retornado Não supor prova de identidade
data.mae Nome da mãe retornado Não expor sem necessidade
data.genero Valor cadastral documentado Evitar inferências indevidas
data.data_nascimento Data textual no exemplo ISO Validar formato antes do uso

Como consumir os dados em JavaScript

function resumirConsulta(payload) {
  if (!payload || payload.code !== 200 || !payload.data) {
    throw new Error("Resposta inesperada");
  }
  return {
    nome: typeof payload.data.nome === "string"
      ? payload.data.nome : null,
  };
}

Devolver somente nome aqui é uma demonstração de minimização; sua aplicação deve avaliar se até esse campo é necessário. Não encaminhe a resposta completa para ferramentas de métricas, logs ou browser sem justificativa.

Como tratar campos ausentes

Uma integração resiliente não acessa data.nome antes de verificar a existência de data. Distinga ausência de campo, string vazia, HTTP de erro e falha na decodificação JSON. A mensagem de erro pública deve ser compreensível, mas não precisa conter todos os detalhes do provedor.

Perguntas frequentes

A resposta JSON garante que os dados estejam corretos?

Não. É uma resposta cadastral de um serviço; precisão, atualidade e adequação devem ser avaliadas conforme a finalidade.

data_nascimento pode ser tratada como Date automaticamente?

É recomendável validar a string e padronizar fuso e representação antes de convertê-la; datas de nascimento não incluem horário.

Continue aprendendo