Fluxo de Cobrança

Visão Geral

Apos o desembolso do emprestimo (status da aplicacao FUNDED), o sistema de cobranca gerencia:

• Acompanhamento de emprestimos e faturas -- listar emprestimos, planos de pagamento e faturas mensais
• Geracao de pagamentos -- QR Codes PIX e Boletos para pagamento de faturas ou parcelas
• Pagamentos em lote -- pagar multiplas faturas de uma vez com desconto automatico
• Saldo devedor e liquidacao -- saldo devedor e calculo de liquidacao antecipada
• Renegociacao -- simular e criar renegociacao para parcelas em atraso
• Webhooks -- receber notificacoes quando o status de parcelas ou faturas muda

Fatura vs Plano de Pagamento

Esta e uma das duvidas mais comuns dos parceiros de integracao. Entender a diferenca e essencial.

Um Plano de Pagamento e uma Fatura servem a propositos diferentes:

Exemplo visual:

Cliente comprou 2 itens no BNPL:

  Emprestimo A: Tenis (4x R$100)
    └── Plano de Pagamento A
          ├── Parcela A1 (Fev) ✅ PAID
          ├── Parcela A2 (Mar) ◄──────────┐
          ├── Parcela A3 (Abr)             │ agrupados em
          └── Parcela A4 (Mai)             │
                                           │
  Emprestimo B: Fone de ouvido (3x R$150) │
    └── Plano de Pagamento B              │
          ├── Parcela B1 (Mar) ◄──────────┤
          ├── Parcela B2 (Abr)             │
          └── Parcela B3 (Mai)             │
                                           ▼
                                ┌─────────────────────┐
                                │  Fatura de Marco      │
                                │  R$ 100 + R$ 150     │
                                │  = R$ 250 total      │
                                │  Vencimento: 15 Mar  │
                                │  (PIX/Boleto unico)  │
                                └─────────────────────┘

O cliente paga uma fatura por mes (R$ 250) em vez de pagar cada emprestimo separadamente.

Endpoints de Cobranca

Emprestimos

Faturas

Planos de Pagamento e Parcelas

Cobrancas e Saldo

Renegociacao

Webhooks

Todos os endpoints de webhook estao na secao Webhook da Referencia da API.

Modos de Cobranca

O sistema suporta dois modos de cobranca:

Modo Fatura (Recomendado)

Os emprestimos sao agrupados em faturas mensais, semelhante a uma fatura de cartao de credito. O cliente recebe uma unica fatura por mes contendo todas as parcelas com vencimento naquele periodo.

Cliente tem 3 emprestimos ativos:
  Emprestimo A: 4x R$ 100  (parcelas com vencimento no dia 15)
  Emprestimo B: 3x R$ 150  (parcelas com vencimento no dia 15)
  Emprestimo C: 6x R$ 50   (parcelas com vencimento no dia 15)

Fatura de Marco:
  ├── Emprestimo A — Parcela 2/4: R$ 100,00
  ├── Emprestimo B — Parcela 1/3: R$ 150,00
  └── Emprestimo C — Parcela 3/6: R$ 50,00
  ────────────────────────────────────────
  Total: R$ 300,00  |  Vencimento: 15 de Marco

Fluxo:

1. GET /invoices?person_id={id}&status=OPEN -- listar faturas em aberto
2. GET /invoices/{invoice_id} -- exibir detalhes da fatura com detalhamento por emprestimo
3. POST /invoices/{invoice_id}/payment-method com {"payment_method": "PIX"} -- gerar QR Code PIX
4. Cliente paga → webhook notifica → status da fatura e atualizado

Modo Avulso

Cada emprestimo e cobrado individualmente. As parcelas sao cobradas separadamente por emprestimo usando o endpoint /charging.

Fluxo:

1. GET /payment-plans?person_id={id} -- listar planos de pagamento ativos
2. GET /installments?payment_plan_id={id} -- listar parcelas
3. POST /charging -- gerar PIX ou Boleto para parcelas especificas
4. Cliente paga → POST /webhooks/payment → status da parcela e atualizado

Fluxo Principal: Pagamento de Fatura

┌──────────────────┐
│    Cliente        │
│    abre o app     │
└────────┬─────────┘
         │
         │ 1. Listar emprestimos ativos
         ▼
┌──────────────────────────────┐
│ GET /person/{id}/loans       │
│ Retorna emprestimos + planos │
│ de pagamento + parcelas      │
└────────┬─────────────────────┘
         │
         │ 2. Listar faturas em aberto
         ▼
┌──────────────────────────────┐
│ GET /invoices                │
│ ?person_id={id}&status=OPEN  │
│ Retorna faturas mensais      │
└────────┬─────────────────────┘
         │
         │ 3. Cliente seleciona a fatura
         ▼
┌──────────────────────────────┐
│ GET /invoices/{id}           │
│ Detalhe com detalhamento     │
│ dos itens por emprestimo     │
└────────┬─────────────────────┘
         │
         │ 4. Gerar pagamento
         ▼
┌──────────────────────────────┐
│ POST /invoices/{id}/          │
│      payment-method           │
│ {"payment_method": "PIX"}     │
│                               │
│ Retorna:                      │
│  • pix_qr_code               │
│  • pix_qr_code_base64        │
│  • pix_copy_paste             │
│  • expires_at                 │
└────────┬─────────────────────┘
         │
         │ 5. Cliente paga via PIX
         ▼
┌──────────────────────────────┐
│ Provedor de pagamento        │
│ confirma                     │
│                              │
│ POST /webhooks/payment       │
│ POST /webhooks/              │
│      installment-status      │
│ POST /webhooks/              │
│      invoice-status          │
└────────┬─────────────────────┘
         │
         ▼
┌──────────────────────────────┐
│  Status da fatura → PAID     │
│  Parcelas → PAID             │
│  Plano de pagamento          │
│  atualizado                  │
└──────────────────────────────┘

Fluxo de Pagamento em Lote

Clientes podem pagar multiplas faturas de uma vez com desconto automatico por antecipacao.

┌──────────────────────────────┐
│ GET /invoices                │
│ ?person_id={id}              │
│ Retorna: 3 faturas em aberto │
│  • Marco:  R$ 300,00         │
│  • Abril:  R$ 300,00         │
│  • Maio:   R$ 250,00         │
└────────┬─────────────────────┘
         │
         │ Cliente seleciona as 3
         ▼
┌──────────────────────────────┐
│ POST /invoices/batch-payment │
│                              │
│ Requisicao:                  │
│  invoice_ids: [mar, abr, mai]│
│  payment_method: PIX         │
│                              │
│ Resposta:                    │
│  original_amount:  R$ 850,00 │
│  discount_amount:  R$ 25,50  │
│  final_amount:     R$ 824,50 │
│  pix_qr_code: "..."         │
└──────────────────────────────┘

Fluxo de Pagamento em Atraso

Quando parcelas ficam em atraso, o sistema aplica duas fases: um periodo de carencia (OVERDUE_GRACE) onde o limite BNPL e zerado mas nenhuma multa e aplicada, seguido por um periodo de penalidade (OVERDUE_PENALTY) onde multa (max 2%) e juros de mora diarios (max 1%/mes) sao aplicados.

┌──────────────────────────────┐
│ Parcela apos a data de       │
│ vencimento                   │
│                              │
│ Webhook recebido:            │
│ POST /webhooks/              │
│      installment-status      │
│ new_status: OVERDUE_GRACE    │
│ (Limite BNPL zerado,         │
│  sem multa)                  │
└────────┬─────────────────────┘
         │
         │ Periodo de carencia expira
         ▼
┌──────────────────────────────┐
│ POST /webhooks/              │
│      installment-status      │
│ new_status: OVERDUE_PENALTY  │
│                              │
│ Fatura tambem e atualizada:  │
│ POST /webhooks/invoice-status│
│ new_status: OVERDUE_PENALTY  │
│                              │
│ fine_amount: 2% do atraso    │
│ interest: 0,033%/dia         │
└────────┬─────────────────────┘
         │
         │ Consultar saldo devedor
         ▼
┌──────────────────────────────┐
│ GET /application/{id}/       │
│     outstanding-balance      │
│                              │
│ Retorna:                     │
│  outstanding_balance: 285,48 │
│  remaining_principal: 278,48 │
│  fine_amount:           2,00 │
│  late_interest:         5,00 │
│  early_settlement:    270,00 │
│  pending_installments:     2 │
└────────┬─────────────────────┘
         │
         │ Opcao A: Pagar fatura em atraso diretamente
         │ Opcao B: Renegociar
         ▼
┌──────────────────────────────┐
│ POST /renegotiation/simulate │
│                              │
│ Retorna opcoes:              │
│  Opc 1: Pagar agora, 15% off│
│    → R$ 242,66               │
│  Opc 2: Parcelar 2x, 5% off │
│    → 2x R$ 135,60            │
└────────┬─────────────────────┘
         │
         │ Cliente seleciona a opcao
         ▼
┌──────────────────────────────┐
│ POST /renegotiation          │
│                              │
│ Retorna:                     │
│  renegotiation_id            │
│  final_amount                │
│  pix_qr_code (p/ pagamento) │
│  status: PENDING_PAYMENT     │
└────────┬─────────────────────┘
         │
         │ Cliente paga → status: PAID
         ▼
┌──────────────────────────────┐
│ GET /renegotiation/{id}      │
│ status: PAID                 │
│                              │
│ Parcelas originais sao       │
│ liquidadas automaticamente   │
└──────────────────────────────┘

Saldo Devedor e Liquidacao Antecipada

Para clientes que desejam quitar o emprestimo antecipadamente (liquidacao antecipada):

GET /application/{id}/outstanding-balance?calculation_date=2026-03-15

Resposta:

{
  "application_id": "6ffd813a-1e88-4a4a-a892-758ca310e607",
  "calculation_date": "2026-03-15",
  "remaining_principal": 278.48,
  "remaining_interest": 5.00,
  "fine_amount": 0,
  "late_interest": 0,
  "outstanding_balance": 283.48,
  "pending_installments": 3,
  "early_settlement_amount": 270.00,
  "early_settlement_discount": 13.48
}

O early_settlement_amount reflete o valor com desconto para quitar o emprestimo inteiro antes do prazo original.

Status das Parcelas

Os status das parcelas estao alinhados com a infraestrutura de pagamentos da QI Tech:

Transicoes comuns:

• PENDING → PAID (pagamento normal em dia)
• PENDING → OVERDUE_GRACE (nao pagou no vencimento, sem multa ainda, limite BNPL zerado)
• OVERDUE_GRACE → OVERDUE_PENALTY (periodo de carencia expirado, multa e juros de mora incidem)
• OVERDUE_GRACE → PAID (pagamento recebido durante o periodo de carencia, sem multa)
• PENDING → PAID_EARLY (pago antes do vencimento)
• OVERDUE_PENALTY → PAID_OVERDUE (pagamento em atraso com multa/juros de mora)

Status das Faturas

Eventos de Webhook

O sistema envia/recebe cinco tipos de notificacoes via webhook:

Webhook de Pagamento (POST /webhooks/payment)

Chamado pelo provedor de pagamento (QI Tech) quando um pagamento via PIX ou Boleto e confirmado.

{
  "person_id": "ff0024e6-d11e-4700-b7f3-b3d201624e62",
  "installment_id": "inst-002",
  "amount": 139.24,
  "payment_method": "PIX",
  "external_payment_id": "pay-ext-12345",
  "payment_date": "2026-03-13"
}

Webhook de Status da Parcela (POST /webhooks/installment-status)

Chamado pela QI Tech quando o status de uma parcela muda (ex.: PENDING → OVERDUE_GRACE).

{
  "person_id": "ff0024e6-d11e-4700-b7f3-b3d201624e62",
  "webhook_type": "installment.status_change",
  "installment_id": "inst-002",
  "previous_status": "PENDING",
  "new_status": "OVERDUE_GRACE",
  "event_datetime": "2026-03-14T00:00:01Z",
  "data": {
    "amount": 139.24,
    "paid_amount": 0,
    "due_date": "2026-03-13",
    "fine_amount": 0,
    "interest_amount": 0
  }
}

Webhook de Status da Fatura (POST /webhooks/invoice-status)

Disparado quando uma fatura transita entre estados.

{
  "person_id": "ff0024e6-d11e-4700-b7f3-b3d201624e62",
  "webhook_type": "invoice.status_change",
  "invoice_id": "inv-2026-03-001",
  "previous_status": "OPEN",
  "new_status": "PAID",
  "event_datetime": "2026-03-13T14:30:00Z",
  "data": {
    "total_amount": 278.48,
    "paid_amount": 278.48,
    "due_date": "2026-03-15",
    "payment_method": "PIX"
  }
}

Webhook de Status da Aplicacao (POST /webhooks/application-status)

Disparado quando uma aplicacao transita entre estados (ex.: SUBMITTED_TO_FI → FUNDED). Util para acompanhar o progresso da aplicacao quando uma requisicao de criacao ou cobranca expira por timeout.

{
  "person_id": "ff0024e6-d11e-4700-b7f3-b3d201624e62",
  "webhook_type": "application.status_change",
  "application_id": "6ffd813a-1e88-4a4a-a892-758ca310e607",
  "previous_status": "SUBMITTED_TO_FI",
  "new_status": "FUNDED",
  "event_datetime": "2026-01-20T12:00:00Z"
}

Webhook de Status do Reembolso (POST /webhooks/refund-status)

Disparado quando um reembolso transita entre estados. Inclui um campo reason quando o status e ACTION_REQUIRED, indicando que o parceiro precisa coletar dados corrigidos do cliente.

{
  "person_id": "ff0024e6-d11e-4700-b7f3-b3d201624e62",
  "webhook_type": "refund.status_change",
  "application_id": "6ffd813a-1e88-4a4a-a892-758ca310e607",
  "refund_id": "9abc1234-def5-6789-abcd-ef0123456789",
  "previous_status": "PENDING",
  "new_status": "ACTION_REQUIRED",
  "event_datetime": "2026-01-22T11:00:00Z",
  "data": {
    "refund_amount": 0,
    "refund_type": "FULL",
    "offset_amount": 500,
    "reason": "INVALID_PIX_KEY"
  }
}

Integracao com a QI Tech

O sistema de cobranca integra-se com a infraestrutura bancaria da QI Tech:

Referencias:

• QI Tech Simulacao de Divida
• QI Tech Processamento de Pagamentos

Tratamento de Erros

Exemplo de resposta de erro:

{
  "error": "INVALID_INSTALLMENT_STATE",
  "message": "One or more installments are already paid",
  "timestamp": "2026-01-21T10:00:00Z"
}