Copy page

Guias

Conceitos

Cinco entidades sustentam a carteira de cobrança. Entender como elas se relacionam evita a maior parte dos erros de integração. Metas são um recurso à parte: medem recuperação, não alteram o ciclo da dívida.

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.

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.

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.

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.

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.

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.

Quatro dessas transições você comanda pela API:

Chamada	De	Para
POST /debts/{id}/hold	PENDING	ON_HOLD
POST /debts/{id}/reactivate	ON_HOLD	PENDING
POST /debts/{id}/archive	PENDING ou ON_HOLD	ARCHIVED
POST /debts/{id}/unarchive	ARCHIVED	PENDING

As demais são consequência da operação de cobrança e chegam até você por webhook. Chamar uma transição a partir de um status que não está na coluna "De" devolve 400 e não altera a dívida — uma dívida SETTLED ou UNDER_CONTRACT, por exemplo, não pode ser pausada nem arquivada. Reativar recalcula juros e multa até a data de hoje, então o today_value volta atualizado.

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.* e pode consultá-los a qualquer momento em GET /contracts (toda a conta) ou em GET /customers/{id}/contracts (um cliente). Os dois devolvem cada acordo já com suas parcelas e as dívidas que ele quita.

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 que informa que dinheiro entrou. Quando a última parcela é paga, o acordo vira SETTLED e as dívidas associadas também.

Meta

Alvo de recuperação da equipe ou de um coletor, em valor negociado (VALUE) ou quantidade de acordos (CONTRACTS). Sem user_id a meta vale para toda a equipe; sem debt_group_id, para todos os grupos.

A API cria, lista, consulta, edita e encerra metas. O campo status é derivado — não existe coluna no banco e você não envia esse valor no POST/PUT:

Status	Significado
SCHEDULED	O período ainda não começou.
ACTIVE	O período já começou e a meta não foi encerrada.
CLOSED	Encerrada. Irreversível.

Encerrar é irreversível e acontece de duas formas, registradas em status_reason:

status_reason	Quando
MANUALLY_CLOSED	Alguém chamou POST /goals/{id}/close.
DEADLINE_REACHED	O período da meta acabou.

closed_at é um instante em UTC. No encerramento por prazo ele é o fim do último dia do período — lido em UTC, cai no dia seguinte ao end_date. Uma meta cujo período já acabou ainda pode aparecer como ACTIVE por um intervalo curto, até o encerramento ser registrado. Enquanto a meta está aberta, closed_at e status_reason vêm nulos.

A lista e o detalhe trazem progress — situação frente ao alvo (health), ritmo diário realizado e necessário, e projeção para o fim do período. É nulo enquanto a meta está agendada, porque não há o que apurar. O detalhe traz ainda daily_results, com um ponto por dia de start_date até o fim da apuração (dias sem acordo vêm com amount 0).

Filtre a listagem com ?status=ACTIVE (vários valores separados por vírgula) e, se quiser, user_id e debt_group_id. Campo omitido lista todas.

Edição

O que o PUT /goals/{id} altera depende do status:

Status	O que muda
SCHEDULED	Todos os campos.
ACTIVE	Só o nome. Os demais campos enviados são ignorados.
CLOSED	Nada: retorna 400 com GOL_001.

Meta recorrente

Envie is_recurring: true no POST /goals para a meta se repetir. A duração do período, contada em dias de start_date a end_date (incluindo os dois), vira o intervalo da série: cada nova meta começa no dia seguinte ao fim da anterior, com o mesmo número de dias.

Code
{
  "name": "Recuperação quinzenal",
  "type": "VALUE",
  "target": 50000,
  "start_date": "2026-10-20",
  "end_date": "2026-11-03",
  "is_recurring": true
}

São 15 dias, então a série segue com 04/11 a 18/11, 19/11 a 03/12, e assim por diante.

• Próxima meta: a série sempre tem uma meta agendada (SCHEDULED) à frente. Ela é criada quando a atual começa; numa série que começa no futuro, só a primeira existe até lá.
• O que se repete: as próximas metas copiam nome, tipo, alvo, user_id e debt_group_id da meta-modelo da série. Na criação, a meta-modelo é a primeira.
• Período: o de uma meta da série nunca muda; start_date e end_date são ignorados no PUT.
• Editar as próximas: no PUT de uma meta da série, apply_to_following: true aplica a alteração também à próxima meta agendada e torna a meta editada a nova meta-modelo. Sem ele, só a meta editada muda. Editar a própria meta-modelo sempre vale para as próximas.
• Encerrar uma meta com POST /goals/{id}/close não interrompe a série.
• Interromper: POST /goals/{id}/stop-recurrence, com o id de qualquer meta da série. Nenhuma meta nova é criada, a meta em andamento vai até o fim e a agendada é removida. Meta avulsa retorna GOL_005; série já interrompida, GOL_004.

Toda meta traz o campo recurrence, nulo na meta avulsa:

Campo	Significado
id	Identificador da série, igual em todas as metas dela.
interval_days	Duração de cada meta da série, em dias.
index	Posição da meta na série, a partir de 0.
is_active	false depois que a série é interrompida.
is_template	Indica se esta meta é a meta-modelo da série.

Datas

A API usa dois tipos de data, e a diferença importa na hora de comparar valores:

Tipo	Campos	Formato
Dia	due_date, origin_date, start_date, end_date, negotiated_date, vencimento de parcela	2026-05-15
Instante	created_at, updated_at, closed_at, paid_at, settled_at	ISO 8601 em UTC: 2026-05-15T13:04:22.000000Z

Um dia é o dia do calendário, sem hora nem fuso — compare direto. Um instante vem sempre em UTC; converta para o fuso do seu sistema antes de exibir ou de extrair o dia, porque a conversão pode mudar a data.

Próximo passo

Com o modelo claro, siga para Primeiros passos e faça a primeira integração ponta a ponta.