> ## Documentation Index
> Fetch the complete documentation index at: https://docs.proteodata.com.br/llms.txt
> Use this file to discover all available pages before exploring further.

# Dados básicos PF

> Primeira API de consulta: slug cpf-basic, autenticação, corpo, escopo, resposta e privacidade

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](/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](/produtos-e-consultas).

## Endpoint

`POST /v1/query/cpf-basic`

Mesmo contrato genérico de [consultas por produto](/produtos-e-consultas): 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](/dev/autenticacao).

## Corpo da requisição

```json theme={null}
{
  "document": "00000000000"
}
```

| Campo      | Tipo   | Obrigatório | Descrição                                                                                                                                                                                                                                                                                              |
| ---------- | ------ | ----------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `document` | string | sim         | Para 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`)

```json theme={null}
{
  "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](/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](/dev/erros-e-limites). Para este produto, destacam-se:

| HTTP    | Situação                                                                     |
| ------- | ---------------------------------------------------------------------------- |
| **400** | Corpo inválido ou fora do schema JSON esperado (`error`: `VALIDATION_ERROR`) |
| **401** | API Key ausente, inválida ou revogada                                        |
| **402** | Saldo de créditos insuficiente para a consulta                               |
| **404** | Produto inativo, slug incorreto ou sem preço para o plano do tenant          |
| **502** | Indisponibilidade 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](/dev/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.