Originação com Boleto de Entrada

Visão Geral

Este documento descreve o ciclo completo de originação de uma CCB quando o produto possui a flag requireEntryPayment ativa. Nesse fluxo, um boleto (ou PIX) de entrada é gerado após a coleta de assinaturas e o desembolso fica bloqueado até a confirmação do pagamento.

Sequência resumida:

Proposta aprovada
  → Geração do contrato
  → KYC (se ativo)
  → Assinatura das partes
  → Geração do boleto de entrada
  → Pagamento confirmado
  → Desembolso
  → ISSUED

Referência de Endpoints

1. Simulação

POST /banking/originator/products/{productId}/preview

Payload:

{
  "requested_amount": 1500,
  "interest_rate": 0.1,
  "tac_amount": 0,
  "finance_fee": 0,
  "insurance_amount": 0,
  "num_payments": 12,
  "first_payment_date": "2026-05-06",
  "disbursement_date": "2026-04-06",
  "schedule_type": "MONTHLY",
  "iof_type": "PERSON"
}

Campos:

O retorno do /preview inclui um simulation_id que deve ser usado na criação da application.

2. Criação da Application

POST /banking/originator/applications

Payload:

{
  "product": {
    "id": "f02a68c4-15cb-4401-bdb2-bd3a246ceb5c"
  },
  "borrower": {
    "id": "a45da11d-ba44-4df1-929a-f1863a5d65f0"
  },
  "funding": {
    "id": "6b400e55-99ca-4563-9980-a0e3d9af68f6"
  },
  "simulation_id": "b6ab2f6b-a766-45ac-9d84-ed7d2544c44c",
  "signature_collect_method": "LINK",
  "signature_provider": "ZAPSIGN",
  "entry_payment_info": {
    "amount": 500,
    "due_date": "2026-04-06"
  }
}

Campos:

Estados do Fluxo

1. AGREEMENT_RENDERING

O sistema inicia a geração do documento contratual (CCB) utilizando o template configurado no produto.

• Saída normal: documento gerado com sucesso → verifica status do KYC e avança.
• Erro: falha no template ou armazenamento → CANCELED.

2. KYC_PROCESSING

Se o motor de KYC estiver ativo no produto, a operação aguarda a análise do perfil do cliente de forma assíncrona.

• Aprovado: avança para PENDING_SIGNATURE.
• Reprovado: status muda para CANCELED com descrição do motivo retornado pelo KYC.

3. PENDING_SIGNATURE

O contrato está pronto para ser assinado pelas partes obrigatórias (tomador, avalistas etc.) através do provedor configurado — ZapSign ou Celcoin, ClickSign, Unico.

• Saída normal: todas as assinaturas coletadas → avança para CREATING_ENTRY_PAYMENT.
• Erro: falha na comunicação com o provedor ou dados de signatários inválidos → SIGNATURE_ERROR.

4. CREATING_ENTRY_PAYMENT

O sistema realiza a geração do boleto (ou PIX) de entrada com base nos dados de entry_payment_info.

• Saída normal: boleto gerado → PENDING_ENTRY_PAYMENT.
• Erro: falha na criação → CANCELED com descrição ENTRY_PAYMENT_CANCELED.

5. PENDING_ENTRY_PAYMENT

O boleto foi criado com sucesso.

• Saída normal: pagamento confirmado (PAID) → avança para desembolso.
• Expirado / cancelado: boleto não pago no prazo → CANCELED com descrição ENTRY_PAYMENT_CANCELED.

6a. PENDING_DISBURSEMENT

Pagamento confirmado. Liberado para processamento imediato pela tesouraria/fundo.

• Quando: sem data futura configurada e sem janelas de horário.
• Saída: desembolso processado → ISSUED.

6b. SCHEDULED_DISBURSEMENT

Desembolso agendado para data futura ou sujeito a janela de horário configurada no produto.

• Saída: janela atingida → desembolso processado → ISSUED.

7. ISSUED

Estado terminal do ciclo de originação. O recurso foi transferido.

Mapeamento de Erros