# Primeiros passos

Este guia leva você do token em mãos até a primeira dívida entrando em cobrança. São
quatro passos e todos usam `curl` — traduza para a sua linguagem à vontade.

Antes de começar, tenha um [token de API](/fundamentos/autenticacao) com as permissões
`debtgroups.list`, `customers.create` e `debts.create`.

```bash
export QUYTA_TOKEN="seu_token_aqui"
export QUYTA_API="https://app.quyta.com.br/api/v1"
```

:::note
Todos os dados de exemplo desta documentação são fictícios — nomes, endereços, e-mails e
telefones não correspondem a pessoas reais. Os e-mails usam o domínio `example.com`,
reservado para documentação pela [RFC 2606](https://www.rfc-editor.org/rfc/rfc2606).
O CPF `123.456.789-09` é o exemplo canônico brasileiro: sequencial, mas com dígitos
verificadores válidos — necessário, porque a API confere.
:::

## 1. Descubra o grupo de dívidas

O grupo define a régua de cobrança que será aplicada. Ele é configurado no painel da
Quyta; pela API você só o consulta para pegar o `id`.

```bash
curl -s "$QUYTA_API/debtgroups" \
  -H "Authorization: Bearer $QUYTA_TOKEN"
```

```json
{
  "data": [
    { "id": 1, "business_unit_id": 1, "name": "Carteira principal — 30 a 90 dias" },
    { "id": 2, "business_unit_id": 1, "name": "Carteira principal — acima de 90 dias" }
  ],
  "meta": { "total": 2, "per_page": 15, "current_page": 1, "total_pages": 1 }
}
```

Essa lista muda raramente. Consulte uma vez e guarde o mapeamento no seu sistema, em vez
de chamá-la a cada dívida.

## 2. Crie o cliente

Todos os campos abaixo são obrigatórios, incluindo o endereço completo e ao menos um
e-mail e um telefone.

```bash
curl -s -X POST "$QUYTA_API/customers" \
  -H "Authorization: Bearer $QUYTA_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Fulano de Tal",
    "document": "12345678909",
    "addr_zipcode": "01001000",
    "addr_street": "Rua Exemplo",
    "addr_number": "100",
    "addr_district": "Centro",
    "addr_city": "São Paulo",
    "addr_state": "SP",
    "addr_extra": "Sala 2",
    "emails": ["fulano@example.com"],
    "phones": ["+5511999999999"]
  }'
```

A resposta traz o cliente criado, com o `id` que você vai usar no próximo passo:

```json
{
  "id": 42,
  "business_unit_id": 1,
  "name": "Fulano de Tal",
  "document": "12345678909",
  "person_type": "F",
  "emails": [{ "id": 1, "email": "fulano@example.com" }],
  "phones": [{ "id": 1, "phone": "+5511999999999" }],
  "created_at": "2026-08-27T10:30:00Z",
  "updated_at": "2026-08-27T10:30:00Z"
}
```

O `person_type` é deduzido do `document`: CPF vira `F`, CNPJ vira `J`.

Repare que o telefone volta em **E.164** (`+5511999999999`). A Quyta normaliza para esse
formato antes de validar, então `(11) 99999-9999` e `11999999999` chegam ao mesmo
resultado — mas enviar já com `+` e DDI é o único jeito sem ambiguidade. Os detalhes estão
em [Conceitos](/conceitos#telefones-e164).

:::tip
Envie todos os canais que você tiver — cada telefone e cada e-mail é uma chance a mais de
a régua de cobrança alcançar o devedor.
:::

## 3. Crie a dívida

Agora amarre o cliente ao grupo de dívidas:

```bash
curl -s -X POST "$QUYTA_API/debts" \
  -H "Authorization: Bearer $QUYTA_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "customer_id": 42,
    "debt_group_id": 1,
    "original_value": 1000.00,
    "due_date": "2026-05-15",
    "description": "Parcela 05/2026 — contrato 88213",
    "external_id": "TIT-88213",
    "origin_contract_id": "767",
    "origin_date": "2026-04-15"
  }'
```

```json
{
  "id": 3120,
  "customer_id": 42,
  "debt_group_id": 1,
  "business_unit_id": 1,
  "status": "PENDING",
  "is_collectable": true,
  "is_contractable": true,
  "original_value": 1000.0,
  "today_value": 1078.5,
  "due_date": "2026-05-15",
  "origin_date": "2026-04-15",
  "external_id": "TIT-88213",
  "origin_contract_id": "767",
  "created_at": "2026-08-27T10:31:00Z",
  "updated_at": "2026-08-27T10:31:00Z"
}
```

A dívida nasce em `PENDING` e a régua de cobrança do grupo assume a partir daí.

:::tip
Preencha sempre o `external_id` com o identificador do título no **seu** sistema. Ele é a
chave que torna a conciliação possível sem você precisar armazenar os `id` da Quyta — e é
filtrável em `GET /debts?external_id=...`.
:::

## 4. Receba os eventos

A cobrança acontece do lado da Quyta. Para o seu sistema saber o que aconteceu — acordo
fechado, parcela paga, dívida liquidada — cadastre um endpoint de webhook no painel.

```json
{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "type": "contract.installment.paid",
  "version": "1",
  "created_at": "2026-09-15T14:02:11Z",
  "data": { "...": "..." }
}
```

Os detalhes estão em [Webhooks](/webhooks/introducao). Vale a pena configurá-los agora:
sem eles, a única forma de saber que uma dívida foi paga é ficar consultando `GET /debts`
em laço.

## Conferindo o resultado

Para ver a dívida que você acabou de criar:

```bash
curl -s "$QUYTA_API/debts?external_id=TIT-88213" \
  -H "Authorization: Bearer $QUYTA_TOKEN"
```

Ou toda a carteira ainda cobrável de um cliente:

```bash
curl -s "$QUYTA_API/debts?customer_id=42&is_collectable=true" \
  -H "Authorization: Bearer $QUYTA_TOKEN"
```

## Daqui para frente

- [Sincronizando a carteira](/guias/sincronizacao) — carga inicial, atualizações diárias e volume.
- [Tratamento de erros](/fundamentos/erros) — o que fazer com cada código de resposta.
- [Referência de API](/api) — todos os campos e validações de cada endpoint.