Copy page

Guias

Conceitos

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

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.

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

Próximo passo

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