Skip to main content
Este é o primeiro produto disponível na API pública Proteo Data: consulta de dados básicos de pessoa física a partir do CPF. A plataforma trata autenticação, precificação e chamada à origem de dados; o seu cliente fala apenas com a Proteo Data.

​
Fluxo de onboarding (primeira consulta rápida)

Se você está no tour inicial do portal, siga nesta ordem:
  1. Gere sua API key em Portal > API Keys.
  2. Volte para esta página e clique em Try it na referência do endpoint.
  3. Cole sua chave no campo de autenticação como Bearer SUA_API_KEY.
  4. Execute a primeira consulta com um CPF válido (apenas dígitos).
Após executar com sucesso, volte ao Dashboard e marque o passo final do onboarding.

​
O que esperar do produto (escopo em alto nível)

Em termos de negócio, este tipo de consulta costuma devolver informações de cadastro básico associadas ao CPF informado — por exemplo identificação, datas relevantes, filiação e indícios de situação cadastral ou óbito, quando existirem na origem e forem retornados naquele contrato. Os campos concretos vêm no objeto data da resposta. A forma exata depende da origem e pode evoluir com o tempo: modele a integração como JSON dinâmico, valide só o que consome e trate a ausência de campos com elegância. Mais detalhes em Resultados.

​
Contrato único da Proteo Data

  • Autenticação: uma única API Key no header Authorization: Bearer (sem expor credenciais ou parâmetros internos da origem).
  • Corpo mínimo: apenas o campo document com o CPF — não há parâmetros opcionais para conferir nome, data de nascimento ou filiação na mesma requisição. Se a sua integração vinha de outra API que permitia esse tipo de cruzamento, adapte o fluxo: a conferência fica do lado do cliente, comparando o retorno em data com os dados que já possui.
  • Uma entidade por chamada: a consulta é sempre para um documento informado; não é um endpoint de busca textual aberta.
O endpoint genérico continua sendo POST /v1/query/{slug}; para este produto, slug = cpf-basic. Veja também Produtos e consultas.

​
Endpoint

POST /v1/query/cpf-basic Mesmo contrato genérico de consultas por produto: o que muda é o slug na URL e o significado do campo document no corpo.

​
Autenticação

É obrigatório o header: Authorization: Bearer <sua_api_key> Detalhes em Autenticação.

​
Corpo da requisição

{
  "document": "00000000000"
}
CampoTipoObrigatórioDescrição
documentstringsimPara este produto: CPF com 11 dígitos, apenas números (sem pontos ou traço). O contrato HTTP aceita strings de 1 a 100 caracteres; valores fora do padrão de CPF podem ser rejeitados na origem. A API não valida dígito verificador — apenas o formato do JSON e os limites do campo.

​
Concorrência e desempenho

Pedidos simultâneos com o mesmo produto e o mesmo document podem ser consolidados numa única chamada à origem; cada cliente recebe a sua própria resposta 200 e a cobrança segue o valor em meta.chargedCredits daquela chamada.

​
Resposta de sucesso (200)

{
  "data": {
    "MatchKeys": "00000000000",
    "BasicData": { }
  },
  "meta": {
    "chargedCredits": "0.067200",
    "product": "cpf-basic",
    "queryId": "3fa85f64-5717-4562-b3fc-2c963f66afa6"
  }
}
  • data: neste produto, objeto equivalente ao primeiro item de Result na origem (MatchKeys, BasicData, etc.), ou envelope mínimo quando Result vier vazio com sucesso — veja Resultados. Caso contrário pode ser null.
  • meta.chargedCredits: valor em R$ debitado nesta requisição (string decimal).
  • meta.product: sempre cpf-basic neste endpoint fixo.
  • meta.queryId: ID interno Proteo — use em suporte; não é o QueryId da origem.

​
Erros comuns

Os códigos e formatos seguem o guia Erros e limites. Para este produto, destacam-se:
HTTPSituação
400Corpo inválido ou fora do schema JSON esperado (error: VALIDATION_ERROR)
401API Key ausente, inválida ou revogada
402Saldo de créditos insuficiente para a consulta
404Produto inativo, slug incorreto ou sem preço para o plano do tenant
502Indisponibilidade ou falha ao obter o resultado da consulta na origem

​
Privacidade e LGPD (uso responsável)

Dados de pessoa física exigem base legal e finalidade claras no seu tratamento (contrato, obrigação legal, legítimo interesse com teste de proporcionalidade, consentimento quando aplicável, etc.). Pratique minimização: só consulte o CPF quando necessário, armazene só o que precisar, defina prazo de retenção e controles de acesso. A Proteo Data processa a consulta em nome da operação; a responsabilidade pelo uso do retorno na sua aplicação e perante os titulares continua sendo sua. Em dúvidas jurídicas, envolva o time de compliance ou assessoria.

​
Exemplos prontos

Os mesmos exemplos em cURL, JavaScript, Python e PHP — usando cpf-basic e um CPF de exemplo — estão em Primeira consulta. Substitua SLUG_DO_PRODUTO por cpf-basic e VALOR_DOCUMENTO por um CPF válido (apenas dígitos).

​
Referência da API

Na aba Referência da API:
  • POST /v1/query/cpf-basic — endpoint de consulta de dados básicos PF, com contrato e exemplos de uso documentados.