API de Refinanciamento — credit-flow-engine

Versão: v1
Base URL (Sandbox): https://platform.sbx.credit.celcoin.com.br/credit-flow-engine/v1
Base URL (Produção): https://platform.prod.credit.celcoin.com.br/credit-flow-engine/v1
Autenticação: Bearer Token (Authorization: Bearer <token>), seguindo o padrão de autenticação cel-credit — ver Autenticação
Formato: JSON (Content-Type: application/json)

Visão Geral do Fluxo

┌─────────────────────────────────────────────────────────────────────┐
│  SETUP (interno)                                                    │
│  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 registra a qualificação (QUALIFIED / DENIED)           │
│     → QUALIFIED: AWAITING_DISBURSEMENT · DENIED: CANCELED           │
└─────────────────────────────────────────────────────────────────────┘

Formato de Erro

Todos os erros seguem o mesmo envelope:

{
  "path": "/credit-flow-engine/v1/credit-analysis",
  "status": 422,
  "code": "CF0002",
  "message": "credit analysis not eligible",
  "meta": {
    "details": ["analysis not approved"]
  }
}

Categorias de erro:

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

O setup define os parâmetros do produto de crédito e a política que governa as operações, em duas etapas: cadastro da política de crédito e configuração do template de CCB.

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.

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": {
      "contracts": [
        { "contract_number": "32423423" }
      ]
    }
  }
}

Campos do Request

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

Response 200 OK

{
  "credit_analysis_id": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
  "status": "PENDING"
}

Máquina de Status da Análise

     ┌─────────┐
     │ PENDING │
     └────┬────┘
          │
     ┌────┴────────┐
     ▼             ▼
┌──────────┐  ┌────────┐
│ APPROVED │  │ DENIED │
└──────────┘  └────────┘

Erros Comuns

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).

Estratégia de polling recomendada: intervalo inicial de 3s, back-off exponencial até 30s, timeout máximo de 10 minutos.

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": {
      "contracts": [
        { "contract_number": "32423423" }
      ]
    }
  },
  "decision_metadata": {
    "refinancing_result": {
      "contracts": [
        { "contract_number": "32423423", "status": "ELIGIBLE" }
      ]
    }
  },
  "events": [
    {
      "status": "PENDING",
      "reason": null,
      "created_at": "2025-10-10T10:00:00Z"
    },
    {
      "status": "APPROVED",
      "reason": null,
      "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": {
      "contracts": [
        { "contract_number": "32423423" }
      ]
    }
  },
  "decision_metadata": {
    "refinancing_result": {
      "contracts": [
        { "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

Motivos de Negação (status_reason)

Erros Comuns

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).

Request

{
  "credit_analysis_id": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
  "request_simulations": [
    {
      "num_payments": 24,
      "interest_rate": 0.018,
      "requested_amount": 5000.00,
      "tac_amount": 0,
      "tac_rate": 0,
      "finance_fee": 0,
      "insurance_amount": 0,
      "insurance_rate": 0,
      "disbursement_options": [
        {
          "disbursement_date": "2025-10-10",
          "settlement_contract": [
            {
              "contract_number": "32423423",
              "outstanding_balance": 1400.00,
              "settlement_date": "2025-10-18"
            }
          ]
        },
        {
          "disbursement_date": "2025-10-11",
          "settlement_contract": [
            {
              "contract_number": "32423423",
              "outstanding_balance": 1395.00,
              "settlement_date": "2025-10-19"
            }
          ]
        }
      ]
    }
  ]
}

Campos do Request

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

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",
          "num_payments": 24,
          "disbursement_amount": 5000.00,
          "financed_amount": 5089.26,
          "requested_amount": 5000.00,
          "total_amount_owed": 7418.40,
          "payment_amount": 309.10,
          "net_change": 2750.00,
          "interest_rate": 0.018,
          "annual_interest_rate": 0.23869,
          "monthly_effective_interest_rate": 0.019624,
          "annual_effective_interest_rate": 0.264821,
          "iof_amount": 89.26,
          "iof_base_rate": 0.0038,
          "iof_daily_rate": 0.000082,
          "schedule_type": "MONTHLY",
          "first_payment_date": "2025-11-10",
          "last_payment_date": "2027-10-10",
          "schedule": [
            {
              "period": 1,
              "payment_date": "2025-11-10",
              "payment": 309.10,
              "principal": 218.30,
              "interest": 90.80,
              "iof": 0.00,
              "balance": 4870.96,
              "running_day": 31
            }
          ],
          "settlement_contracts_data": [
            {
              "contract_number": "32423423",
              "outstanding_balance": 1400.00,
              "settlement_date": "2025-10-10"
            }
          ]
        }
      ]
    }
  ]
}

Campos da Response

Erros Comuns

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

Request

{
  "funding_id": "e746ba58-8cfe-48e0-872a-a4109baba935",
  "signature": {
    "authentication_options": {
      "mode": "DOC_SIGN"
    },
    "collect_method": "LINK",
    "provider": "UNICO"
  },
  "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:

Borrower — Identificação:

Borrower — Contato (phone):

Borrower — Documento (id_document):

Borrower — Endereço (address):

Borrower — Desembolso via Pix:

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

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

Response 201 Created

{
  "credit_operation_id": "b1c2d3e4-f5a6-7890-bcde-f01234567890",
  "status": "PENDING"
}

Erros Comuns

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

Response 200 OK

{
  "id": "b1c2d3e4-f5a6-7890-bcde-f01234567890",
  "proposal_simulation_id": "d4e5f6a7-b8c9-0123-def0-456789abcde0",
  "status": "ISSUED",
  "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": 0.264821,
      "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": "",
        "requested_at": "2025-10-10T10:11:00Z",
        "processed_at": "2025-10-10T10:11:30Z",
        "payment_orders": [
          {
            "id": "",
            "amount": 2750.00,
            "type": "PIX",
            "status": "PAID",
            "description": "Desembolso ao tomador"
          },
          {
            "id": "",
            "amount": 1400.00,
            "type": "PIX",
            "status": "PAID",
            "description": ""
          }
        ]
      }
    ],
    "disbursement": {
      "requested_at": "2025-10-10T10:11:00Z",
      "processed_at": "2025-10-10T10:11:30Z",
      "receipt": "E00038166202510101211AbCdEf123456"
    }
  }
}

Campos da Response

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

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

  Em qualquer etapa: ──► CANCELED

Erros Comuns

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

6.1 Request

Path Parameters

Form Data

6.2 Response — 200 OK

{
  "status": "SUCCESS"
}

Erros Comuns

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

7.1 Request

Path Parameters

Body

{
  "status": "QUALIFIED"
}

Campos do Body

7.2 Response — 200 OK

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

Campos da Response

Erros Comuns

Catálogo Completo de Erros