# Primeiros passos

# Primeiros passos

## 1. A chave

Toda chamada leva a sua chave no header `X-API-Key`:

```bash
-H "X-API-Key: SUA_CHAVE"
```

A chave também determina o **ambiente**. Uma chave de teste responde em modo de teste; uma chave de
produção executa e cobra de verdade. Não há parâmetro para escolher — se você quer testar, use a
chave de teste.

## 2. Descubra o que consultar

```bash
curl -X GET "https://api.consultas.us/catalog" \
  -H "X-API-Key: SUA_CHAVE"
```

Cada item traz:

- **`slug`** — é o que você envia em `consultation_type`;
- **`input_schema`** — o contrato de `input_data`: o que é obrigatório e em que formato;
- **`preco_efetivo_brl`** — o preço para a **sua** conta;
- **`assincrono`** — se `true`, o resultado não vem na resposta do `POST` (veja
  [Consultas que demoram](/consultas-que-demoram)).

O catálogo não cobra. Chame-o à vontade.

## 3. Orce, se quiser

```bash
curl -X POST "https://api.consultas.us/estimate" \
  -H "X-API-Key: SUA_CHAVE" \
  -H "Content-Type: application/json" \
  -d '{ "consultation_type": "antecedentes-cpf", "input_data": { "cpf": "11144477735" } }'
```

Responde o preço, de onde o pagamento sairia, se a entrada está completa (`validacao`) e se aquele
documento **já está no seu histórico** (`ja_no_historico`). Não cobra e não executa nada.

## 4. Consulte

```bash
curl -X POST "https://api.consultas.us" \
  -H "X-API-Key: SUA_CHAVE" \
  -H "Content-Type: application/json" \
  -d '{ "consultation_type": "antecedentes-cpf", "input_data": { "cpf": "11144477735" } }'
```

**Este é o endpoint que cobra.** A resposta traz `consultation_id`, o `result` e o `balance`
atualizado.

## Reenviar sem cobrar duas vezes

Se você precisa reenviar uma chamada com segurança — timeout de rede, retentativa automática, fila
que reprocessa —, mande um `Idempotency-Key`:

```bash
-H "Idempotency-Key: um-valor-seu-por-consulta"
```

Repetir o mesmo valor faz as duas chamadas valerem por uma: a segunda devolve o resultado da
primeira, **sem cobrar de novo**, e a resposta vem marcada com `idempotent: true`.

## Uma nota sobre `POST /` e `POST /consultations`

As duas formas existem, chegam ao mesmo motor e têm o mesmo efeito e o mesmo custo. Use a que
preferir.