# Conceitos

Cinco entidades sustentam toda a API. Entender como elas se relacionam evita a maior
parte dos erros de integração.

<Mermaid chart={`
flowchart TD
  BU["Conta<br/><i>escopo do seu token</i>"]
  BU --> CU["Cliente<br/><i>o devedor</i>"]
  BU --> DG["Grupo de dívidas<br/><i>a carteira / régua</i>"]
  CU --> DE["Dívida<br/><i>o título vencido</i>"]
  DG --> DE
  DE --> CT["Acordo<br/><i>a negociação</i>"]
  CT --> IN["Parcela<br/><i>o que é pago</i>"]
`} />

## Conta

É o escopo de tudo: a sua organização dentro da Quyta. Cada token de API pertence a
**uma** conta, e toda requisição enxerga apenas os dados dela — você nunca precisa (nem
consegue) filtrar por conta manualmente.

:::note
No JSON, a conta aparece como **`business_unit_id`**, e nos webhooks como o objeto
`business_unit`. O nome do campo é histórico; leia como "a sua conta".
:::

Se a sua empresa opera várias carteiras separadas — marcas distintas, CNPJs distintos —
cada uma é uma conta com o seu próprio token.

## Cliente

O devedor: pessoa física (`person_type: "F"`, CPF) ou jurídica (`person_type: "J"`, CNPJ),
identificado pelo campo `document`.

Um cliente carrega **listas** de telefones e e-mails, não um único contato. Isso é
deliberado: quanto mais canais válidos, maior a chance de a régua de cobrança alcançar a
pessoa. Cada telefone e cada e-mail tem o seu próprio `id`, usado para removê-lo depois.

O endereço é obrigatório na criação. Ele não é decorativo — alimenta o cadastro usado em
confissões de dívida e documentos de acordo.

### Telefones: E.164

Telefones são **normalizados para E.164** antes de serem validados, e é sempre nesse
formato que a API os devolve. Você não precisa enviar já formatado — a Quyta resolve —,
mas precisa entender como ela resolve:

| Você envia | A Quyta grava | Por quê |
| --- | --- | --- |
| `+5511999999999` | `+5511999999999` | Já em E.164: o DDI é respeitado como veio. |
| `(11) 99999-9999` | `+5511999999999` | Sem `+`, assume Brasil e prefixa `+55`. |
| `11999999999` | `+5511999999999` | Idem — pontuação é descartada. |
| `+13115552368` | `+13115552368` | Número internacional preservado. |

A regra do `+`: **com** ele, a Quyta confia no DDI que você mandou. **Sem** ele, ela
prefixa `+55` — a menos que os dígitos já comecem em `55` e tenham 12 ou mais dígitos,
caso em que entende que o DDI do Brasil já está lá.

Depois de normalizado, o número precisa ser válido de verdade — brasileiro ou
internacional. Não basta ter a quantidade certa de dígitos: um DDD inexistente ou um
celular sem o nono dígito é recusado com **422**.

:::tip
Envie sempre em E.164, com `+` e DDI. É a única forma sem ambiguidade — e é o que a API
devolve, então o seu lado já fica espelhado com o dela.
:::

Telefones também são **únicos dentro da conta**: tentar adicionar um número que já
pertence a outro cliente da mesma conta devolve 422.

### Documento

O `document` é validado de verdade: CPF (11 dígitos) ou CNPJ (14), com **conferência dos
dígitos verificadores**. Documentos com todos os dígitos iguais são recusados. Envie só os
números — pontuação é descartada antes da validação.

O `document` também é único dentro da conta.

:::tip
O cliente precisa existir **antes** da dívida. `POST /debts` recebe `customer_id`, não os
dados do devedor.
:::

## Grupo de dívidas

A carteira. Agrupa dívidas que compartilham a mesma régua de cobrança — mesma cadência de
mensagens, mesma política de desconto, mesmo tom.

Grupos são criados e configurados **no painel da Quyta**. Pela API você apenas os lista
(`GET /debtgroups`) para descobrir o `id` que vai informar ao criar uma dívida.

Na prática: peça ao time da Quyta a configuração dos grupos que a sua operação precisa,
liste-os uma vez e guarde o mapeamento no seu lado.

## Dívida

O título vencido — o recurso central da API. Além do valor e do vencimento, dois campos
merecem atenção:

| Campo | Para que serve |
| --- | --- |
| `external_id` | O identificador da dívida **no seu sistema**. É por ele que você reencontra a dívida sem guardar o `id` da Quyta. |
| `origin_contract_id` | O contrato ou acordo original que deu origem ao título, quando existir. |

A dívida também expõe dois valores distintos: `original_value`, o que você enviou, e
`today_value`, o valor atualizado com juros e multa na data de hoje. Para cobrar ou
conciliar, o número relevante é `today_value`.

:::warning
O `due_date` precisa ser **hoje ou uma data passada** — a API recusa vencimento futuro com
422. É coerente com o produto: a Quyta cobra o que já venceu, não gerencia carnê a vencer.
Se o seu sistema envia títulos antes do vencimento, segure-os até virarem.

O `origin_date`, quando enviado, também não pode ser futuro nem posterior ao `due_date`.
Ambas as datas usam estritamente `AAAA-MM-DD`.
:::

Os campos `external_id`, `origin_contract_id` e `origin_date` são **opcionais**. Os
obrigatórios na criação são `customer_id`, `debt_group_id`, `original_value`, `due_date` e
`description`.

### Estados da dívida

| Status | Significado |
| --- | --- |
| `PENDING` | Pendente — aguardando ou em cobrança ativa. É o estado inicial. |
| `UNDER_CONTRACT` | Em acordo — a dívida foi incluída numa negociação e saiu da régua normal. |
| `SETTLED` | Liquidada — foi paga. |
| `ON_HOLD` | Cobrança pausada — suspensa temporariamente, por decisão da operação. |
| `ARCHIVED` | Arquivada — fora do fluxo de cobrança, mantida para histórico. |

<Mermaid chart={`
stateDiagram-v2
  [*] --> PENDING: POST /debts
  PENDING --> UNDER_CONTRACT: acordo criado
  UNDER_CONTRACT --> SETTLED: acordo liquidado
  UNDER_CONTRACT --> PENDING: acordo quebrado
  PENDING --> ON_HOLD: cobrança pausada
  ON_HOLD --> PENDING: cobrança reativada
  PENDING --> ARCHIVED: arquivada
  ARCHIVED --> PENDING: desarquivada
  SETTLED --> [*]
`} />

Note que `ARCHIVED` e `ON_HOLD` são reversíveis, e que desarquivar sempre devolve a dívida
para `PENDING`. Uma dívida cujo acordo é quebrado também volta para `PENDING` e retorna à
régua de cobrança.

### Os dois sinalizadores

`is_collectable` e `is_contractable` respondem, respectivamente, "esta dívida pode ser
cobrada agora?" e "esta dívida pode entrar num acordo?". São campos calculados pela
Quyta — você não os define. Use-os como filtro em `GET /debts` quando precisar saber o que
de fato está em jogo na carteira, em vez de deduzir isso a partir do status.

## Acordo

A negociação fechada com o devedor: um valor, um desconto e um parcelamento. Um acordo
pode agrupar **várias dívidas** do mesmo cliente.

Acordos nascem da operação da Quyta — pelo painel ou pelo portal de negociação do próprio
devedor. **Não existe endpoint para criá-los.** Você toma conhecimento deles pelos
webhooks `contract.*`.

| Status | Significado |
| --- | --- |
| `ACTIVE` | Ativo — acordo em andamento, parcelas em dia. |
| `DEBT_CONFESSION_PENDING` | Aguardando assinatura da confissão de dívida. |
| `OVERDUE` | Atrasado — há parcelas vencidas e não pagas. |
| `TERMINATED` | Quebrado — cancelado por descumprimento. As dívidas voltam à cobrança. |
| `SETTLED` | Liquidado — todas as parcelas foram pagas. |

## Parcela

Cada pagamento previsto dentro de um acordo, com valor, vencimento e status
(`PENDING`, `PAID`, `OVERDUE`, `SETTLED`, `CANCELLED`).

A parcela é a unidade de conciliação financeira: é o evento
[`contract.installment.paid`](/webhooks/eventos#contractinstallmentpaid) que informa que
dinheiro entrou. Quando a última parcela é paga, o acordo vira `SETTLED` e as dívidas
associadas também.

:::warning
Um acordo `SETTLED` significa que **todas** as parcelas foram pagas. Se você der baixa no
seu ERP apenas em `contract.settled`, vai registrar o valor só no fim do parcelamento.
Para conciliar caixa mês a mês, use `contract.installment.paid`.
:::

## Próximo passo

Com o modelo claro, siga para [Primeiros passos](/primeiros-passos) e faça a
primeira integração ponta a ponta.