# Catálogo de eventos A Quyta emite dez eventos, em três famílias. Você escolhe quais receber ao cadastrar a assinatura no painel. | Evento | Quando dispara | | --- | --- | | [`customer.created`](#customercreated) | Um cliente foi criado. | | [`debt.created`](#debtcreated) | Uma dívida foi criada. | | [`debt.held`](#debtheld) | A cobrança de uma dívida foi pausada. | | [`debt.reactivated`](#debtreactivated) | A cobrança foi reativada. | | [`debt.archived`](#debtarchived) | A dívida foi arquivada. | | [`debt.unarchived`](#debtunarchived) | A dívida foi desarquivada. | | [`contract.created`](#contractcreated) | Um acordo foi fechado. | | [`contract.installment.paid`](#contractinstallmentpaid) | Uma parcela do acordo foi paga. | | [`contract.settled`](#contractsettled) | O acordo foi integralmente pago. | | [`contract.terminated`](#contractterminated) | O acordo foi quebrado. | Se você só puder consumir dois, consuma **`contract.created`** e **`contract.installment.paid`**: são os que movem dinheiro. Todos os exemplos abaixo mostram apenas o campo `data`. Ele vem sempre dentro do [payload padrão](/webhooks/introducao#o-formato-do-evento). --- ## Eventos de cliente ### `customer.created` Um novo devedor entrou na base — seja por `POST /customers`, seja por cadastro feito no painel. ```json { "customer": { "id": 42, "name": "Fulano de Tal", "document": "12345678909", "emails": [{ "id": 1, "email": "fulano@example.com" }], "phones": [{ "id": 1, "phone": "+5511999999999" }] }, "business_unit": { "id": 1, "name": "Empresa Exemplo" } } ``` **Use quando** você precisa espelhar a base de devedores da Quyta no seu CRM. Se todos os clientes nascem do seu próprio sistema via API, esse evento tende a ser redundante — você já sabe da criação pela resposta do `POST`. --- ## Eventos de dívida ### `debt.created` Uma dívida entrou na carteira. É o evento mais completo: traz a dívida, o devedor, o grupo e a conta numa única entrega. ```json { "debt": { "id": 3120, "description": "Parcela 05/2026 — contrato 88213", "status": "PENDING", "original_value": 1000.0, "today_value": 1078.5, "due_date": "2026-05-15T00:00:00.000000Z", "origin_date": "2026-04-15", "external_id": "TIT-88213", "created_at": "2026-08-27T10:31:00Z", "updated_at": "2026-08-27T10:31:00Z" }, "customer": { "id": 42, "name": "Fulano de Tal", "document": "12345678909", "emails": [{ "id": 1, "email": "fulano@example.com" }], "phones": [{ "id": 1, "phone": "+5511999999999" }] }, "debt_group": { "id": 1, "name": "Carteira principal — 30 a 90 dias" }, "business_unit": { "id": 1, "name": "Empresa Exemplo" } } ``` **Use quando** dívidas podem ser criadas fora do seu sistema — importação por planilha ou cadastro manual no painel — e você precisa saber disso. O `external_id` permite casar o evento com o título na sua base. ### `debt.held` A cobrança foi **pausada**. A dívida continua existindo, mas a régua para de disparar. Acontece, por exemplo, quando o devedor contesta o débito ou paga fora da Quyta. ```json { "debt": { "status": "ON_HOLD" } } ``` ### `debt.reactivated` A cobrança pausada voltou a rodar. A dívida retorna para `PENDING` e a régua recomeça. ### `debt.archived` A dívida saiu do fluxo de cobrança de vez, mantida apenas para histórico — prescrição, baixa contábil, acordo judicial. ```json { "debt": { "status": "ARCHIVED" } } ``` **Use para** dar baixa na expectativa de recebimento do seu lado. Uma dívida arquivada não será mais cobrada. ### `debt.unarchived` A dívida foi retirada do arquivo e devolvida ao fluxo de cobrança. ```json { "debt": { "status": "PENDING" } } ``` :::note Os payloads dos eventos `debt.held`, `debt.archived`, `debt.unarchived` e `debt.reactivated` são enxutos: informam a transição, não o registro completo. Se o seu processamento precisa de mais dados, consulte `GET /debts/{id}` ao recebê-los. ::: --- ## Eventos de acordo ### `contract.created` **O evento mais importante da API.** Um acordo foi fechado: o devedor negociou e se comprometeu com um parcelamento. Traz o acordo, todas as parcelas previstas e as dívidas que ele cobre. ```json { "contract": { "id": 501, "description": "Acordo de renegociação", "status": "ACTIVE", "value": 5000.0, "discount": 500.0, "created_at": "2026-09-01T09:12:00Z", "updated_at": "2026-09-01T09:12:00Z" }, "installments": [ { "value": 1000.0, "status": "PENDING", "due_date": "2026-10-01T00:00:00.000000Z" }, { "value": 1000.0, "status": "PENDING", "due_date": "2026-11-01T00:00:00.000000Z" } ], "debts": [ { "id": 3120, "description": "Parcela 05/2026 — contrato 88213", "status": "UNDER_CONTRACT" } ] } ``` **Use para** registrar a expectativa de recebimento no seu financeiro e marcar as dívidas como negociadas. O `discount` é o valor abatido na negociação — informação que costuma interessar ao seu controle de perdas. Um acordo em `DEBT_CONFESSION_PENDING` ainda aguarda a assinatura da confissão de dívida: o compromisso existe, mas não está formalizado. ### `contract.installment.paid` Uma parcela foi paga. **É este o evento que representa dinheiro entrando.** ```json { "installment_paid": { "id": 8801, "value": 1000.0, "status": "PAID", "due_date": "2026-10-01T00:00:00.000000Z", "paid_at": "2026-09-28T16:44:12.000000Z" } } ``` **Use para** conciliação financeira. O campo `paid_at` é a data efetiva do pagamento e costuma diferir do `due_date` — para regime de caixa, use `paid_at`. :::warning Não espere `contract.settled` para dar baixa. Num acordo de doze parcelas, ele só chega no décimo segundo mês. `contract.installment.paid` chega a cada pagamento. ::: ### `contract.settled` Todas as parcelas do acordo foram pagas. O acordo se encerra e as dívidas cobertas por ele passam a `SETTLED`. ```json { "contract": { "status": "SETTLED" }, "installments": [{ "status": "PAID" }], "debts": [{ "status": "SETTLED" }] } ``` **Use para** encerrar o caso: a recuperação daquele título terminou com sucesso. ### `contract.terminated` O acordo foi **quebrado** — em geral por parcelas em atraso além do tolerado. As dívidas saem de `UNDER_CONTRACT`, voltam a `PENDING` e retornam à régua de cobrança. ```json { "contract": { "status": "TERMINATED" } } ``` **Use para** reverter, no seu financeiro, a expectativa de recebimento registrada em `contract.created`. Sem tratar este evento, sua previsão de caixa fica otimista demais. --- ## O ciclo completo >Q: POST /debts Q-->>S: debt.created Note over Q: régua de cobrança Q-->>S: contract.created Q-->>S: contract.installment.paid Q-->>S: contract.installment.paid alt Devedor cumpre o acordo Q-->>S: contract.settled else Devedor abandona o acordo Q-->>S: contract.terminated Note over Q: dívida volta para PENDING end `} /> ## Próximos passos - [Entrega e retentativas](/webhooks/entrega) — o que acontece quando seu endpoint falha. - [Segurança](/webhooks/seguranca) — validando a assinatura das entregas.