API
Status PageSuporte

Refinanciamento


🚧

Produto em desenvolvimento — não disponível para uso.
Esta API está em fase de desenvolvimento e ainda não foi liberada para integração.

Versão: v1
Base URL: /credit-flow-engine/v1
Autenticação: Bearer Token (Authorization: Bearer <token>)
Formato: JSON (Content-Type: application/json)

Visão Geral do Fluxo

┌─────────────────────────────────────────────────────────────────────┐
│  SETUP (interno)                                                    │
│  Produto → Operação → Config → Política → Template CCB             │
└───────────────────────────────┬─────────────────────────────────────┘
                                │ feito uma vez por produto
                                ▼
┌─────────────────────────────────────────────────────────────────────┐
│  1. POST /credit-analysis                                           │
│     Cliente envia CPF do tomador + contratos a refinanciar          │
│     → Resposta imediata com credit_analysis_id (status: PENDING)    │
└───────────────────────────────┬─────────────────────────────────────┘
                                │ análise assíncrona 
                                ▼
┌─────────────────────────────────────────────────────────────────────┐
│  2. GET /credit-analysis/{id}  [polling]                            │
│     Cliente consulta até status APPROVED ou DENIED                  │
│     → Retorna condições aprovadas (prazo, taxa, valores)            │
└───────────────────────────────┬─────────────────────────────────────┘
                                │ apenas se APPROVED
                                ▼
┌─────────────────────────────────────────────────────────────────────┐
│  3. POST /credit-simulation                                         │
│     Cliente simula com os parâmetros dentro das condições           │
│     → Resposta síncrona com cronograma, IOF, CET (múltiplas datas)  │
└───────────────────────────────┬─────────────────────────────────────┘
                                │ cliente escolhe 1 proposta
                                ▼
┌─────────────────────────────────────────────────────────────────────┐
│  4. POST /credit-simulation/{sim_id}/proposal/{prop_id}/approval    │
│     Cliente envia dados do tomador + método de assinatura           │
│     → Dispara workflow de aprovação (Temporal)                      │
└───────────────────────────────┬─────────────────────────────────────┘
                                │ processamento assíncrono
                                ▼
┌─────────────────────────────────────────────────────────────────────┐
│  5. GET /credit_operation/{id}  [polling]                           │
│     Cliente aguarda status PENDING_SIGNATURE                        │
│     → Retorna detalhes da credit_operation                          │
└───────────────────────────────┬─────────────────────────────────────┘
                                │ status PENDING_SIGNATURE
                                ▼
┌─────────────────────────────────────────────────────────────────────┐
│  6. POST /credit_operation/{id}/signature/{signature_type}          │
│     Parceiro envia o arquivo da CCB assinada pelo tomador           │
│     → Avança para PENDING_QUALIFICATION                             │
└───────────────────────────────┬─────────────────────────────────────┘
                                │ processamento assíncrono
                                ▼
┌─────────────────────────────────────────────────────────────────────┐
│  7. POST /credit_operation/{id}/qualify                             │
│     Parceiro informa resultado da qualificação (APPROVED / DENIED)  │
│     → APPROVED: avança para QUALIFIED · DENIED: CANCELED            │
└─────────────────────────────────────────────────────────────────────┘

0 · Setup — Configuração Interna (backoffice)

⚠️

Interno — executado pela equipe Celcoin antes de qualquer cliente operar.

O setup define os parâmetros do produto de crédito e a política que governa as operações. São três etapas sequenciais, seguidas do cadastro da política.

0.1 Criar Política de Crédito

A política associa tipo de produto, provedor analítico e detalhes específicos como tempo de expiração e os workflows pertinentes ao fluxo de crédito.

0.2 Template CCB — Múltiplas Datas de Desembolso

Pré-requisito: o produto de refinanciamento deve ter um template de CCB configurado para aceitar múltiplas opções de desembolso e os detalhes específicos da operação de refinanciamento.

1 · Criar Análise de Crédito

POST /credit-flow-engine/v1/credit-analysis
Auth: Bearer Token

O cliente inicia a análise enviando o CPF do tomador e os contratos que deseja refinanciar. O processamento é assíncrono — a resposta retorna imediatamente com PENDING e o id da análise.

1.1 Request

{
  "credit_policy_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "idempotency_key": "7b4e1234-dc90-11ed-afa1-0242ac120002",
  "borrower": {
    "taxpayer_id": "12345678900",
    "type": "PERSON"
  },
  "credit_terms_conditions": [
    {
      "num_payments": { "min": 12, "max": 96 },
      "financed_amount": { "min": 500.00, "max": 50000.00 },
      "payment_amount": { "min": 50.00, "max": 2000.00 },
      "interest_rate": { "min": 0.005, "max": 0.03 },
      "interest_type": "pre_fixed",
      "interest_rate_frequency": "MONTHLY"
    }
  ],
  "additional_data": {
    "refinancing_data": [
      { "contract_number": "32423423" },
      { "contract_number": "55512345" }
    ]
  }
}

Campos do Request

CampoTipoObrigatórioDescrição
credit_policy_iduuid✅ID da política de crédito que governa esta análise.
idempotency_keyuuid✅UUID gerado pelo cliente. Re-envios com a mesma chave retornam 409 Conflict — a análise não é duplicada.
borrowerobject✅Dados básicos do tomador para identificação.
borrower.taxpayer_idstring✅CPF (11 dígitos) ou CNPJ (14 dígitos), somente números.
borrower.typestring✅Tipo do tomador. Valores: PERSON · BUSINESS
credit_terms_conditions[]object✅Faixas de condições permitidas para a simulação. Pelo menos um item.
credit_terms_conditions[].num_payments.minint✅Prazo mínimo em parcelas.
credit_terms_conditions[].num_payments.maxint✅Prazo máximo em parcelas.
credit_terms_conditions[].financed_amount.minfloat64✅Valor mínimo financiado.
credit_terms_conditions[].financed_amount.maxfloat64✅Valor máximo financiado.
credit_terms_conditions[].payment_amount.minfloat64✅Valor mínimo de parcela.
credit_terms_conditions[].payment_amount.maxfloat64✅Valor máximo de parcela.
credit_terms_conditions[].interest_rate.minfloat64⬜Taxa mínima em decimal. Ex: 0.01 = 1%.
credit_terms_conditions[].interest_rate.maxfloat64⬜Taxa máxima em decimal. Ex: 0.03 = 3%.
credit_terms_conditions[].interest_typestring✅Modalidade de juros. Ex: pre_fixed.
credit_terms_conditions[].interest_rate_frequencystring✅Frequência da taxa. Valores: MONTHLY · ANNUAL
additional_dataobject⬜Dados adicionais para necessários para executar a análise de crédito. Ex: Para operações de REFIN, contém os contratos a serem refinanciados.
additional_data.refinancing_data[]object✅*Lista de contratos para verificação de elegibilidade.
additional_data.refinancing_data[].contract_numberstring✅*Número do contrato a ser refinanciado.

* Obrigatório para operações de refinanciamento.

1.2 Response 200 OK

{
  "credit_analysis_id": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
  "status": "PENDING"
}
CampoTipoDescrição
credit_analysis_iduuidID da análise criada. Usar para polling no passo 2.
statusstringStatus inicial sempre PENDING.

Máquina de Status da Análise

     ┌─────────┐
     │ PENDING │
     └────┬────┘
          │
     ┌────┴────────┐
     ▼             ▼
┌──────────┐  ┌────────┐
│ APPROVED │  │ DENIED │
└──────────┘  └────────┘
StatusDescrição
PENDINGAnálise criada, aguardando processamento.
APPROVEDAnálise aprovada. Retorna credit_terms_conditions e decision_metadata.
DENIEDAnálise negada. status_reason indica o motivo da negativa.

Erros Comuns

🚧

Em elaboração — esta seção será complementada em versão futura.

2 · Consultar Análise de Crédito (Polling)

GET /credit-flow-engine/v1/credit-analysis/{id}
Auth: Bearer Token

O cliente consulta periodicamente até obter um status final (APPROVED, DENIED).

⚠️

Apenas polling disponível — notificação via webhook será disponibilizada em versão futura.

Response 200 OK — APPROVED

{
  "id": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
  "credit_policy_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "status": "APPROVED",
  "status_reason": null,
  "expire_at": "2025-10-17T14:30:00Z",
  "borrower": {
    "taxpayer_id": "12345678900",
    "type": "PERSON"
  },
  "credit_terms_conditions": [
    {
      "num_payments": { "min": 12, "max": 96 },
      "financed_amount": { "min": 500.00, "max": 50000.00 },
      "payment_amount": { "min": 50.00, "max": 2000.00 },
      "interest_rate": { "min": 0.005, "max": 0.025 },
      "interest_type": "pre_fixed",
      "interest_rate_frequency": "MONTHLY"
    }
  ],
  "additional_data": {
    "refinancing_data": [
      { "contract_number": "32423423" },
      { "contract_number": "55512345" }
    ]
  },
  "decision_metadata": {
    "refinancing_result": [
      { "contract_number": "32423423", "status": "ELIGIBLE" },
      { "contract_number": "55512345", "status": "ELIGIBLE" }
    ]
  },
  "events": [
    {
      "status": "PENDING",
      "reason": null,
      "created_at": "2025-10-10T10:00:00Z"
    },
    {
      "status": "APPROVED",
      "reason": null,
      "triggered_by": "TEMPORAL",
      "created_at": "2025-10-10T10:00:15Z"
    }
  ]
}

Response 200 OK — DENIED

{
  "id": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
  "credit_policy_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "status": "DENIED",
  "status_reason": "NO_ACTIVE_CONTRACTS",
  "expire_at": "2025-10-17T14:30:00Z",
  "borrower": {
    "taxpayer_id": "12345678900",
    "type": "PERSON"
  },
  "credit_terms_conditions": [],
  "additional_data": {
    "refinancing_data": [
      { "contract_number": "32423423" },
      { "contract_number": "55512345" }
    ]
  },
  "decision_metadata": {
    "refinancing_result": [
      { "contract_number": "32423423", "status": "INELIGIBLE" }
    ]
  },
  ,
  "events": [
    {
      "status": "PENDING",
      "reason": null,
      "created_at": "2025-10-10T10:00:00Z"
    },
    {
      "status": "DENIED",
      "reason": "NO_ACTIVE_CONTRACTS",
      "created_at": "2025-10-10T10:00:15Z"
    }
  ]

}

Campos da Response

CampoTipoDescrição
iduuidID da análise de crédito.
credit_policy_iduuidID da política usada.
statusstringStatus atual. Ver máquina de status.
status_reasonstring | nullMotivo da negativa, quando status DENIED.
expire_atdatetime | nullData/hora de expiração quando APPROVED. Após este momento a análise não pode mais ser usada para simulação.
borrower.taxpayer_idstringCPF/CNPJ do tomador.
borrower.typestringTipo do tomador.
credit_terms_conditions[]objectCondições aprovadas para simulação. Populado apenas em APPROVED. Campos: num_payments, financed_amount, payment_amount, interest_rate, interest_type, interest_rate_frequency.
decision_metadata[]objectDados coletados na análise de crédito para tomada de decisão.
decision_metadata.refinancing_result[]objectElegibilidade por contrato.
decision_metadata.refinancing_result[].contract_numberstringNúmero do contrato.
decision_metadata.refinancing_result[].statusstringELIGIBLE · INELIGIBLE · PENDING
events[]objectHistórico imutável de transições de status.

Motivos de Negação (status_reason)

ValorDescrição
NO_ACTIVE_CONTRACTSNenhum contrato ativo elegível encontrado para o tomador.

Erros Comuns

🚧

Em elaboração — esta seção será complementada em versão futura.

3 · Criar Simulação

POST /credit-flow-engine/v1/credit-simulation
Auth: Bearer Token

Com a análise APPROVED, o cliente solicita simulações com diferentes combinações de parâmetros. A resposta é síncrona e retorna o cronograma completo para cada opção de desembolso.
Para operações de refinanciamento, é obrigatório informar o saldo devedor de cada contrato para cada opção de desembolso. O contrato refinanciado é liquidado no 8º dia após a averbação, respeitando os 7 dias corridos de prazo de desistência da operação. Portanto, o saldo devedor informado para cada contrato deve corresponder à data de desembolso acrescida de 8 dias.

Exemplo: desembolso em 14/06 → saldo devedor calculado para 22/06.

A simulação pode ser solicitada de duas formas mutuamente exclusivas — exatamente um dos campos abaixo deve ser informado:

  • requested_amount — o cliente informa o valor desejado de desembolso; o sistema calcula o valor da parcela.
  • payment_amount — o cliente informa o valor fixo de parcela desejado; o sistema calcula o valor de desembolso.

O exemplo abaixo utiliza simulação por valor requisitado (requested_amount).

3.1 Request

{
  "credit_analysis_id": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
  "request_simulations": [
    {
      "interest_rate": 0.018,
      "number_of_installments": 24,
      "requested_amount": 5000.00,
      "tac_amount": 0,
      "tac_rate": 0,
      "finance_fee": 0,
      "insurance_amount": 0,
      "multiple_disbursements_details": [
        {
          "disbursement_date": "2025-10-10",
          "settlement_data": {
            "32423423": {
              "settlement_date": "2025-10-18",
              "outstanding_balance": 1400.00
            },
            "55512345": {
              "settlement_date": "2025-10-18",
              "outstanding_balance": 850.00
            }
          }
        },
        {
          "disbursement_date": "2025-10-11",
          "settlement_data": {
            "32423423": {
              "settlement_date": "2025-10-19",
              "outstanding_balance": 1395.00
            },
            "55512345": {
              "settlement_date": "2025-10-19",
              "outstanding_balance": 847.50
            }
          }
        },
        {
          "disbursement_date": "2025-10-12",
          "settlement_data": {
            "32423423": {
              "settlement_date": "2025-10-20",
              "outstanding_balance": 1390.00
            },
            "55512345": {
              "settlement_date": "2025-10-20",
              "outstanding_balance": 845.00
            }
          }
        }
      ]
    }
  ]
}

Campos do Request

CampoTipoObrigatórioDescrição
credit_analysis_iduuid✅ID da análise de crédito com status APPROVED.
request_simulations[]object✅Lista de simulações a calcular. Mínimo: 1 item.
request_simulations[].interest_ratefloat64✅Taxa de juros mensal (decimal). Deve estar dentro do intervalo aprovado na análise.
request_simulations[].number_of_installmentsint✅Número de parcelas. Deve estar dentro do intervalo aprovado.
request_simulations[].requested_amountfloat64✅*Valor solicitado pelo cliente para o financiamento.
request_simulations[].payment_amountfloat64✅*Valor fixo de parcela desejado.
request_simulations[].tac_amountfloat64⬜Valor fixo da Tarifa de Abertura de Crédito.
request_simulations[].tac_ratefloat64⬜Taxa percentual da TAC (alternativa a tac_amount).
request_simulations[].finance_feefloat64⬜Taxa financeira adicional sobre o principal.
request_simulations[].insurance_amountfloat64⬜Valor do prêmio de seguro a incluir nas parcelas.
request_simulations[].insurance_ratefloat64⬜Taxa de seguro sobre saldo devedor (alternativa a insurance_amount).
request_simulations[].multiple_disbursements_details[]object✅Opções de data de desembolso. Mínimo conforme disbursement_options_min_quantity da config do produto.
multiple_disbursements_details[].disbursement_datestring✅Data de desembolso desta opção. Formato: YYYY-MM-DD. Datas devem estar em ordem cronológica crescente.
multiple_disbursements_details[].settlement_datamap[string]object✅*Dados de liquidação por contrato. Chave = número do contrato.
settlement_data["<contrato>"].settlement_datestring✅*Data em que o contrato será liquidado. Formato: YYYY-MM-DD.
settlement_data["<contrato>"].outstanding_balancefloat64✅*Saldo devedor do contrato na data de liquidação. Deve ser positivo.

requested_amount ou payment_amount deve ser informado (não ambos, não nenhum).
 settlement_data é obrigatório para operações de refinanciamento.

3.2 Response 201 Created

{
  "simulation_id": "c3d4e5f6-a7b8-9012-cdef-34567890abcd",
  "created_at": "2025-10-10T10:05:00Z",
  "expire_at": "2025-10-10T10:35:00Z",
  "simulations": [
    {
      "proposal_simulation_id": "d4e5f6a7-b8c9-0123-def0-456789abcde0",
      "proposal_details": [
        {
          "disbursement_date": "2025-10-10",
          "disbursement_amount": 5000.00,
          "financed_amount": 5089.26,
          "total_amount_owed": 7418.40,
          "payment_amount": 309.10,
          "interest_rate": 0.018,
          "annual_interest_rate": 0.23869,
          "monthly_effective_interest_rate": 0.019624,
          "annual_effective_interest_rate": 26.4821,
          "total_processing_cost": 89.26,
          "iof_amount": 89.26,
          "iof_base_rate": 0.0038,
          "iof_daily_rate": 0.000082,
          "net_change": 2750.00,
          "issue_date": "2025-10-10",
          "first_payment_date": "2025-11-10",
          "last_payment_date": "2027-10-10",
          "interest_pre_type": "BASE_360",
          "interest_rate_frequency": "MONTHLY",
          "requested_amount": 5000.00,
          "schedule": [
            {
              "period": 1,
              "payment_date": "2025-11-10",
              "payment": 309.10,
              "principal": 218.30,
              "interest": 90.80,
              "iof": 0.00,
              "balance": 4870.96,
              "additional_value": 0.00,
              "running_day": 31
            }
          ],
          "settlement_data": {
            "32423423": {
              "settlement_date": "2025-10-10",
              "outstanding_balance": 1400.00
            },
            "55512345": {
              "settlement_date": "2025-10-10",
              "outstanding_balance": 850.00
            }
          }
        },
        {
          "disbursement_date": "2025-10-15",
          "net_change": 2755.00
        }
      ]
    }
  ]
}

Campos da Response

CampoTipoDescrição
simulation_iduuidID do lote de simulação. Usado no passo de aprovação.
created_atdatetimeTimestamp de criação.
expire_atdatetimeAs propostas expiram neste momento.
simulations[]objectUma entrada por request_simulation enviado.
simulations[].proposal_simulation_iduuidID desta proposta específica. Usado no passo 4.
simulations[].proposal_details[]objectUma entrada por data de desembolso simulada.
proposal_details[].disbursement_datestringData de desembolso desta opção.
proposal_details[].disbursement_amountfloat64Valor líquido da operação. Para operações de refinanciamento, é a soma do valor de quitação do contrato e troco ao tomador.
proposal_details[].financed_amountfloat64Principal + encargos financiados.
proposal_details[].total_amount_owedfloat64Soma de todos as parcelas a valor futuro.
proposal_details[].payment_amountfloat64Valor fixo de cada parcela.
proposal_details[].interest_ratefloat64Taxa nominal mensal (decimal).
proposal_details[].annual_interest_ratefloat64Taxa nominal anual (decimal).
proposal_details[].monthly_effective_interest_ratefloat64CET mensal (decimal).
proposal_details[].annual_effective_interest_ratefloat64CET anual (decimal).
proposal_details[].total_processing_costfloat64Custo total: tarifas + IOF.
proposal_details[].iof_amountfloat64Valor total do IOF.
proposal_details[].iof_base_ratefloat64Alíquota base IOF (fixo). Ex: 0.0038.
proposal_details[].iof_daily_ratefloat64Alíquota diária IOF. Ex: 0.000082.
proposal_details[].net_changefloat64Valor do troco ao tomador. Valor que o tomador efetivamente recebe no bolso.
proposal_details[].issue_datestringData de emissão da CCB.
proposal_details[].first_payment_datestringData do primeiro vencimento.
proposal_details[].last_payment_datestringData do último vencimento (maturidade).
proposal_details[].interest_pre_typestringBase de cálculo dos juros: BASE_360 · BASE_365 · BASE_252
proposal_details[].interest_rate_frequencystringFrequência da taxa: MONTHLY · ANNUAL
proposal_details[].schedule[]objectCronograma completo de amortização.
schedule[].periodintNúmero da parcela (começa em 1).
schedule[].payment_datestringData de vencimento.
schedule[].paymentfloat64Total da parcela.
schedule[].principalfloat64Amortização do principal.
schedule[].interestfloat64Juros do período.
schedule[].ioffloat64IOF diário acumulado até este vencimento.
schedule[].balancefloat64Saldo devedor após pagamento. Zero na última.
schedule[].additional_valuefloat64Encargos adicionais (seguro, tarifas).
schedule[].running_dayintDias corridos desde issue_date até este vencimento.
proposal_details[].settlement_datamap[string]objectDados de liquidação por contrato nesta data de desembolso.

Erros Comuns

🚧

Em elaboração — esta seção será complementada em versão futura.

4 · Aprovar Proposta — Criar CCB

POST /credit-flow-engine/v1/credit-simulation/{simulation_id}/proposal/{proposal_simulation_id}/approval
Auth: Bearer Token

O cliente escolhe uma proposta específica (combinação simulation_id + proposal_simulation_id) e envia os dados completos do tomador, método de assinatura e custom_variables (se aplicável).

Path Parameters

ParâmetroTipoDescrição
simulation_iduuidID do lote de simulação (campo simulation_id da response do passo 3).
proposal_simulation_iduuidID da proposta específica escolhida (campo proposal_simulation_id da response do passo 3).

4.1 Request

{
  "funding_id": "e746ba58-8cfe-48e0-872a-a4109baba935",
  "signature_collect_method": "LINK",
  "signature_provider": "UNICO",
  "signature_authentication_options": {
    "mode": "DOC_SIGN"
  },
  "borrower": {
    "taxpayer_id": "12345678900",
    "full_name": "João Silva Santos",
    "nationality": "Brasileira",
    "birth_date": "1985-03-15",
    "pep": false,
    "sex": "MALE",
    "marital_status": "MARRIED",
    "marital_property_system": "PARTIAL_COMMUNION",
    "mothers_name": "Maria Santos",
    "email_address": "[email protected]",
    "occupation": "Analista de Sistemas",
    "monthly_income": 8500.00,
    "education_level": "HIGHER_EDUCATION",
    "phone": {
      "country_code": "55",
      "area_code": "11",
      "number": "912345678"
    },
    "id_document": {
      "number": "12345678",
      "issuer": "SSP/SP",
      "issue_date": "2010-05-20",
      "type": "NATIONAL_ID"
    },
    "address": {
      "street_name": "Rua das Flores",
      "street_number": 123,
      "postal_code": "01310100",
      "district": "Jardins",
      "city": "São Paulo",
      "state_code": "SP",
      "country_code": "BRA",
      "extra_info": "Apto 42"
    },
    "pix": {
      "key": "[email protected]",
      "key_type": "EMAIL"
    }
  }
}

Nota: Para desembolso via conta bancária em vez de Pix, substituir pix por external_account. Não é possível informar ambos.

Campos do Request

Raiz:

CampoTipoObrigatórioDescrição
funding_iduuid✅ID do fundo que financiará a operação.
signature_collect_methodstring✅Canal de entrega da assinatura ao tomador. Valores: LINK · EMAIL · WHATSAPP · NONE
signature_providerstring✅Provedor de assinatura eletrônica. Valores: UNICO · (outros por contrato)
signature_authentication_optionsobject✅Configuração de autenticação.
signature_authentication_options.modestring✅Modo de autenticação. Valores: DOC_SIGN · FACIAL
borrowerobject✅Dados completos do tomador.

Borrower — Identificação:

CampoTipoObrigatórioDescrição
borrower.taxpayer_idstring✅CPF (11 dígitos) ou CNPJ (14 dígitos).
borrower.full_namestring✅Nome completo conforme documento.
borrower.nationalitystring✅Nacionalidade.
borrower.birth_datestring✅Data de nascimento. Formato: YYYY-MM-DD.
borrower.email_addressstring✅E-mail para comunicações e link de assinatura.
borrower.occupationstring✅Profissão atual.
borrower.pepbool⬜Pessoa Exposta Politicamente.
borrower.sexstring⬜Valores: MALE · FEMALE · OTHER
borrower.marital_statusstring⬜Valores: SINGLE · MARRIED · DIVORCED · WIDOWED · SEPARATED
borrower.marital_property_systemstring⬜Obrigatório se marital_status = MARRIED. Valores: PARTIAL_COMMUNION · UNIVERSAL_COMMUNION · TOTAL_SEPARATION · FINAL_PARTICIPATION
borrower.mothers_namestring⬜Nome completo da mãe.
borrower.monthly_incomefloat64⬜Renda mensal bruta.
borrower.education_levelstring⬜Nível de escolaridade.

Borrower — Contato (phone):

CampoTipoObrigatórioDescrição
borrower.phoneobject✅Dados de contato telefônico.
borrower.phone.country_codestring✅DDI. Ex: "55".
borrower.phone.area_codestring✅DDD sem zero. Ex: "11".
borrower.phone.numberstring✅Número sem DDD.

Borrower — Documento (id_document):

CampoTipoObrigatórioDescrição
borrower.id_documentobject⬜Documento de identificação.
borrower.id_document.numberstring✅*Número do documento.
borrower.id_document.issuerstring✅*Órgão emissor. Ex: "SSP/SP".
borrower.id_document.issue_datestring✅*Data de emissão. Formato: YYYY-MM-DD.
borrower.id_document.typestring✅*Tipo. Valores: NATIONAL_ID · PROOF_OF_INCOME · SRC_AUTHORIZATION · OTHER

Borrower — Endereço (address):

CampoTipoObrigatórioDescrição
borrower.addressobject⬜Endereço residencial.
borrower.address.street_namestring✅*Logradouro.
borrower.address.street_numberint✅*Número.
borrower.address.postal_codestring✅*CEP, somente dígitos.
borrower.address.districtstring✅*Bairro.
borrower.address.citystring✅*Cidade.
borrower.address.state_codestring✅*UF com 2 letras. Ex: "SP".
borrower.address.country_codestring✅*País (ISO 3166-1 alpha-3). Ex: "BRA".
borrower.address.extra_infostring⬜Complemento.

Borrower — Desembolso via Pix:

CampoTipoObrigatórioDescrição
borrower.pixobject✅†Chave Pix para receber o desembolso.
borrower.pix.keystring✅*Chave Pix.
borrower.pix.key_typestring✅*Tipo. Valores: TAXPAYER_ID · EMAIL · PHONE_NUMBER · ALEATORY_KEY

Borrower — Desembolso via Conta Bancária (alternativa ao Pix):

CampoTipoObrigatórioDescrição
borrower.external_accountobject✅†Conta bancária para receber o desembolso.
borrower.external_account.bank_codestring✅*Código COMPE do banco (3 dígitos).
borrower.external_account.bank_branchstring✅*Agência sem dígito.
borrower.external_account.bank_accountstring✅*Conta sem dígito.
borrower.external_account.bank_account_digitstring✅*Dígito verificador.
borrower.external_account.bank_account_typestring✅*Tipo. Valores: CHECKING · SAVINGS
borrower.external_account.bank_ispb_codestring✅*Código ISPB (8 dígitos).
borrower.external_account.bank_taxpayer_idstring✅*CNPJ do banco.
borrower.external_account.namestring✅*Nome do titular da conta.

† Exatamente um entre pix e external_account deve ser informado.
* Obrigatório quando o objeto pai está presente.

4.2 Response 201 Created

{
  "credit_operation_id": "b1c2d3e4-f5a6-7890-bcde-f01234567890",
  "status": "PENDING"
}
CampoTipoDescrição
credit_operation_iduuidID da operação de crédito criada. Usar para polling no passo 5.
statusstringStatus inicial sempre PENDING.

Erros Comuns

🚧

Em elaboração — esta seção será complementada em versão futura.

5 · Consultar Operação de Crédito (Polling)

GET /credit-flow-engine/v1/credit_operation/{credit_operation_id}
Auth: Bearer Token

Após a aprovação, a operação de crédito é processada de forma assíncrona. O cliente consulta periodicamente até o status final.

Path Parameters

ParâmetroTipoDescrição
credit_operation_iduuidID retornado no passo 4.

Response 200 OK

{
  "id": "b1c2d3e4-f5a6-7890-bcde-f01234567890",
  "proposal_simulation_id": "d4e5f6a7-b8c9-0123-def0-456789abcde0",
  "status": "APPROVED",
  "contract_number": "123456",
  "created_at": "2025-10-10T10:10:00Z",
  "updated_at": "2025-10-10T10:10:45Z",
  "details": {
    "loan_details": {
      "total_processing_cost": 89.26,
      "annual_interest_rate": 0.23869,
      "interest_rate": 0.018,
      "annual_effective_interest_rate": 26.4821,
      "monthly_effective_interest_rate": 0.019624,
      "total_amount_owed": 7418.40,
      "disbursement_amount": 5000.00,
      "financed_amount": 5089.26,
      "iof_daily_rate": 0.000082,
      "iof_amount": 89.26,
      "iof_base_rate": 0.0038,
      "payment_amount": 309.10,
      "issue_date": "2025-10-10",
      "last_payment_date": "2027-10-10",
      "interest_pre_type": "BASE_360",
      "interest_rate_frequency": "MONTHLY",
      "amortization_type": "PRICE",
      "insurance_amount": 0.00
    },
    "funding": {
      "id": "e746ba58-8cfe-48e0-872a-a4109baba935",
      "legal_name": "Fundo de Investimento ABC",
      "alias": "FI-ABC"
    },
    "disbursement_attempts": [
      {
        "id": "a1b2c3d4",
        "status": "SUCCESS",
        "status_description": "Desembolso realizado com sucesso",
        "requested_at": "2025-10-10T10:11:00Z",
        "processed_at": "2025-10-10T10:11:30Z",
        "payment_orders": [
          {
            "id": "po-001",
            "amount": 2750.00,
            "type": "PIX",
            "status": "PAID",
            "description": "Desembolso ao tomador"
          },
          {
            "id": "po-002",
            "amount": 1400.00,
            "type": "PIX",
            "status": "PAID",
            "description": "Liquidação contrato 32423423"
          },
          {
            "id": "po-003",
            "amount": 850.00,
            "type": "PIX",
            "status": "PAID",
            "description": "Liquidação contrato 55512345"
          }
        ]
      }
    ],
    "disbursement": {
      "requested_at": "2025-10-10T10:11:00Z",
      "processed_at": "2025-10-10T10:11:30Z",
      "receipt": "E00038166202510101211AbCdEf123456"
    }
  }
}

Campos da Response

CampoTipoDescrição
iduuidID da operação de crédito.
proposal_simulation_iduuidID da proposta aprovada.
statusstringStatus atual. Ver máquina de status.
contract_numberstring | nullNúmero do contrato. Disponível após PENDING_SIGNATURE.
created_atdatetimeData de criação da operação.
updated_atdatetime | nullÚltima atualização.
detailsobject | nullDetalhes financeiros e de desembolso. Disponível após PENDING_SIGNATURE.
details.loan_detailsobjectValores financeiros da CCB gerada.
details.fundingobjectDados do fundo financiador.
details.disbursement_attempts[]objectHistórico de tentativas de desembolso.
disbursement_attempts[].payment_orders[]objectOrdens de pagamento por beneficiário.
payment_orders[].typestringTipo de pagamento: PIX · TED · (outros)
payment_orders[].statusstringStatus da ordem de pagamento.
details.disbursementobjectDados do desembolso efetivado (receipt).

Máquina de Status da Operação de Crédito

            ┌─────────┐
            │ PENDING │
            └────┬────┘
                 ▼
     ┌───────────────────┐
     │ PENDING_SIGNATURE │
     └────────┬──────────┘
              ▼
   ┌───────────────────────┐
   │ PENDING_QUALIFICATION │
   └───────────┬───────────┘
               ▼
         ┌───────────┐
         │ QUALIFIED │
         └─────┬─────┘
               ▼
         ┌────────────┐◄──────────────────────────┐
         │ DISBURSING │                           │
         └──────┬─────┘                           │
           ┌────┴──────────────────────────┐      │
           ▼                               ▼      │
      ┌────────┐  ┌─────────────────────────────┐ │
      │ ISSUED │  │ DISBURSEMENT_ATTEMPT_FAILED ├─┘
      └────────┘  └─────────────────────────────┘

  Em qualquer etapa: ──► CANCELED
StatusDescriçãoÉ final?
PENDINGOperação criada, aguardando início do workflow.Não
PENDING_SIGNATUREAguardando assinatura da CCB pelo tomador.Não
PENDING_QUALIFICATIONCCB assinada, aguardando qualificação.Não
QUALIFIEDQualificação aprovada pelo parceiro, operação pronta para o próximo step.Não
DISBURSINGDesembolso em processamento.Não
DISBURSEMENT_ATTEMPT_FAILEDFalha na tentativa de desembolso. Após correção da causa raiz — por exemplo, dados bancários incorretos do tomador — a operação retorna a DISBURSING para nova tentativa.Não
ISSUEDDesembolso efetuado com sucesso.Sim
CANCELEDOperação cancelada. Pode ocorrer em qualquer etapa do fluxo.Sim

Erros Comuns

🚧

Em elaboração — esta seção será complementada em versão futura.

6 · Registrar Assinatura

Após a CCB ser gerada, a operação entra no status PENDING_SIGNATURE. Este endpoint notifica o sistema de que a assinatura do tomador foi coletada diretamente pelo parceiro, avançando a operação para PENDING_QUALIFICATION.

Método: POST
Path: /credit-flow-engine/v1/credit_operation/{credit_operation_id}/signature/{signature_type}
Content-Type: multipart/form-data

⚠️

Pré-requisito: a operação deve estar no status PENDING_SIGNATURE.

6.1 Request

Path Parameters

CampoTipoObrigatórioDescrição
credit_operation_iduuid✅ID da operação de crédito.
signature_typestring✅Tipo de assinatura. Valores: PHYSICAL

Form Data

CampoTipoObrigatórioDescrição
filefile✅Arquivo da CCB assinada pelo tomador.

6.2 Response — 200 OK

{
  "status": "SUCCESS"
}
CampoTipoDescrição
statusstringConfirmação do registro. Valor fixo: SUCCESS

7 · Qualificar Operação de Crédito

Após a assinatura da CCB, a operação entra no status PENDING_QUALIFICATION. Este endpoint permite que o parceiro registre o resultado da qualificação — aprovando ou negando a operação.

Método: POST
Path: /credit-flow-engine/v1/credit_operation/{credit_operation_id}/qualify

⚠️

Pré-requisito: a operação deve estar no status PENDING_QUALIFICATION.

7.1 Request

Path Parameters

CampoTipoObrigatórioDescrição
credit_operation_iduuid✅ID da operação de crédito.

Body

{
  "status": "APPROVED"
}

Campos do Body

CampoTipoObrigatórioDescrição
statusstring✅Resultado da qualificação. APPROVED avança a operação para o próximo step; DENIED move a operação para CANCELED.

7.2 Response — 200 OK

{
  "status_qualify": "APPROVED",
  "credit_operation_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6"
}

Campos da Response

CampoTipoDescrição
status_qualifystringStatus da qualificação registrado: APPROVED · DENIED
credit_operation_iduuidID da operação de crédito qualificada.

Catálogo Completo de Erros

🚧

Em elaboração — esta seção será complementada em versão futura.

Updated about 2 hours ago

Updated about 2 hours ago