Ciclo de vida de un crédito

El core origina créditos de consumo y personales con su propio motor de amortización, el cálculo del costo anual total (CAT), la capacidad de pago, el scoring y las reglas regulatorias del producto. Cada paso que compromete dinero exige una identidad distinta.

Las rutas de esta guía cuelgan de https://api.banco.example/api/v1/ext. Los montos son ilustrativos.

1. Listar productos de crédito

Alcance credit:read.

curl -s https://api.banco.example/api/v1/ext/credit-products -H "X-Api-Key: $FINORA_API_KEY"

Cada producto trae sus topes; usa su productId o su código en los pasos siguientes.

2. Simular el plan de pagos

Alcance credit:read. No crea ni reserva nada. Es el mismo cálculo que hará la solicitud real (producto, comisiones y método), sin scoring ni reglas regulatorias.

curl -s -X POST https://api.banco.example/api/v1/ext/credits/simulations \
  -H "X-Api-Key: $FINORA_API_KEY" -H "Content-Type: application/json" \
  -d '{
    "productCode": "CRE-PERS",
    "amount": 12000.00,
    "annualRatePct": 24.00,
    "installments": 12,
    "method": "FRENCH",
    "capitalFrequency": "MONTHLY",
    "firstPaymentDate": "2026-11-13"
  }'

Campo	Notas
annualRatePct	Tasa nominal anual en porcentaje (24.00 = 24 %).
installments	De 1 a 360.
method	FRENCH (por defecto), GERMAN, AMERICAN, BULLET, GRADIENT o BALLOON.
capitalFrequency	MONTHLY (por defecto), BIMONTHLY, QUARTERLY, SEMIANNUAL, ANNUAL, BIWEEKLY o WEEKLY.
firstPaymentDate	Por defecto, un mes desde hoy.

{
  "currency": "VES",
  "amount": 12000.00,
  "annualRatePct": 24.00,
  "installments": 12,
  "method": "FRENCH",
  "totalPrincipal": 12000.00,
  "totalInterest": 1616.59,
  "totalCharges": 0.00,
  "totalPayments": 13616.59,
  "catNominal": 0.2400,
  "catEffective": 0.2682,
  "schedule": [
    { "number": 1, "dueDate": "2026-11-13", "openingBalance": 12000.00, "principal": 894.72,
      "interest": 240.00, "charges": 0.00, "total": 1134.72, "closingBalance": 11105.28 }
  ]
}

catNominal y catEffective son fracciones (0.24 = 24 %). charges agrupa comisión, seguro y otros cargos de la cuota.

3. Crear la solicitud

Alcance credit:write. Ejecuta la originación completa. Si pasa, el crédito queda en PENDING_APPROVAL; si una regla bloquea o el scoring rechaza, responde 422 y no crea nada.

curl -s -X POST https://api.banco.example/api/v1/ext/credits \
  -H "X-Api-Key: $CLAVE_ORIGINACION" \
  -H "Idempotency-Key: 2f4a8c1e-9d3b-4e7f-a6c2-5b8d0e1f7a93" \
  -H "Content-Type: application/json" \
  -d '{
    "customerId": "b4c6c1d8-bedd-4d05-ae70-a3152d4e1417",
    "productCode": "CRE-PERS",
    "amount": 12000.00,
    "annualRatePct": 24.00,
    "installments": 12,
    "declaredMonthlyIncome": 25000.00,
    "method": "FRENCH",
    "capitalFrequency": "MONTHLY",
    "firstPaymentDate": "2026-11-13",
    "destination": "CONSUMO"
  }'

declaredMonthlyIncome es obligatorio: es la base de la capacidad de pago. Respuesta 201:

{
  "creditId": 215,
  "status": "PENDING_APPROVAL",
  "customerId": "b4c6c1d8-bedd-4d05-ae70-a3152d4e1417",
  "productCode": "CRE-PERS",
  "productName": "Préstamo Personal",
  "currency": "VES",
  "amount": 12000.00,
  "annualRatePct": 24.00,
  "installments": 12,
  "outstandingBalance": 0.00,
  "creditAccountId": "5a2f0a52-1d63-4c8e-9a53-0d3a2f0a9a10",
  "creditAccountCode": "09990001000000000025",
  "requestedBy": "apikey:7",
  "approver": null,
  "approvalDate": null,
  "disbursedBy": null,
  "disbursementDate": null,
  "riskClass": null,
  "firstPaymentDate": "2026-11-13",
  "maturityDate": "2027-11-13"
}

creditAccountId es la cuenta del crédito: recibe el desembolso y es la cuenta de cobro por defecto.

4. Aprobar o rechazar

Alcance credit:approve, con una credencial distinta de la que creó la solicitud.

curl -s -X POST https://api.banco.example/api/v1/ext/credits/215/approval \
  -H "X-Api-Key: $CLAVE_COMITE" \
  -H "Idempotency-Key: 7c2e9a41-3f6d-4b8a-91e5-0d4c6b2a8f17" \
  -H "Content-Type: application/json" \
  -d '{ "decision": "APPROVE", "comment": "Cumple política" }'

Para rechazar, envía "decision": "REJECT" con el motivo en comment (obligatorio). El crédito pasa a APPROVED o REJECTED.

5. Desembolsar

Alcance credit:disburse, con una credencial distinta de la que aprobó. Se desembolsa el monto aprobado completo en la cuenta del crédito; con destinationAccountId los fondos se trasladan además a una cuenta de captación del mismo cliente, abierta y en la misma moneda.

curl -s -X POST https://api.banco.example/api/v1/ext/credits/215/disbursement \
  -H "X-Api-Key: $CLAVE_DESEMBOLSO" \
  -H "Idempotency-Key: e5b1d7c3-8a2f-4c69-b0e4-3f7a9d1c5e28" \
  -H "Content-Type: application/json" \
  -d '{ "destinationAccountId": "3d0c4f0e-9c7f-4b8e-8c1a-0a5b5f1d2e11" }'

{
  "creditId": 215,
  "status": "ACTIVE",
  "amount": 12000.00,
  "currency": "VES",
  "creditAccountId": "5a2f0a52-1d63-4c8e-9a53-0d3a2f0a9a10",
  "creditAccountCode": "09990001000000000025",
  "destinationAccountId": "3d0c4f0e-9c7f-4b8e-8c1a-0a5b5f1d2e11",
  "reference": "credit:DISBURSE:215",
  "movementTransactionId": "0d9d4f2e-1b0a-4f6e-8a7c-6a1c2f3b4d5e",
  "transferDebitTransactionId": "7c1e2f3a-4b5c-6d7e-8f90-a1b2c3d4e5f6",
  "outstandingBalance": 12000.00
}

reference aparece en el movimiento y en el asiento contable.

6. Cobrar cuotas

Alcance credit:payment. El cobro se imputa en el orden legal: cargos, mora, interés y capital, empezando por la cuota más antigua. Sin amount, cobra lo que falta de la próxima cuota.

curl -s -X POST https://api.banco.example/api/v1/ext/credits/215/payments \
  -H "X-Api-Key: $CLAVE_COBRANZA" \
  -H "Idempotency-Key: 1d8f3b6a-2e4c-4a7d-9b15-6c0e8f2a4d71" \
  -H "Content-Type: application/json" \
  -d '{ "amount": 1134.72, "originAccountId": "3d0c4f0e-9c7f-4b8e-8c1a-0a5b5f1d2e11" }'

originAccountId es la cuenta del cliente que se debita (por defecto, la cuenta del crédito). Respuesta 201:

{
  "creditId": 215,
  "paymentId": 31,
  "reference": "CRDPAY-215-31",
  "paymentDate": "2026-11-13",
  "currency": "VES",
  "totalApplied": 1134.72,
  "charges": 0.00,
  "penalty": 0.00,
  "interest": 240.00,
  "capital": 894.72,
  "balanceBefore": 12000.00,
  "balanceAfter": 11105.28,
  "payoff": false,
  "originAccountCode": "09990001000000000017",
  "creditStatus": "ACTIVE",
  "allocations": [
    { "installmentNumber": 1, "capital": 894.72, "interest": 240.00, "charges": 0.00, "penalty": 0.00, "fullyPaid": true }
  ]
}

allocations solo viene en la respuesta original; una repetición idempotente (200) lo omite.

Adelantos

Un monto mayor que la cuota cubre las cuotas siguientes en orden. No reduce el plazo ni recalcula el plan: el abono a capital con reamortización no está disponible.

7. Cotizar y cancelar el crédito

Cotizar (alcance credit:read): cuánto cuesta liquidar el crédito en una fecha. Se cobra el capital insoluto, el interés y los cargos devengados y la mora; el interés futuro no se cobra.

curl -s "https://api.banco.example/api/v1/ext/credits/215/payoff-quote?asOf=2026-12-01" \
  -H "X-Api-Key: $FINORA_API_KEY"

{ "creditId": 215, "asOf": "2026-12-01", "currency": "VES", "capital": 11105.28, "accruedInterest": 133.26,
  "accruedCharges": 0.00, "penalty": 0.00, "total": 11238.54, "installmentsToSettle": 11 }

Cancelar (alcance credit:payment): cobra la cotización del día, salda todas las cuotas y pasa el crédito a CLOSED.

curl -s -X POST https://api.banco.example/api/v1/ext/credits/215/payoff \
  -H "X-Api-Key: $CLAVE_COBRANZA" \
  -H "Idempotency-Key: 4a7e2c9b-6d1f-4e83-b5a0-9c3d7f1e2b64" \
  -H "Content-Type: application/json" \
  -d '{ "originAccountId": "3d0c4f0e-9c7f-4b8e-8c1a-0a5b5f1d2e11" }'

Consultas

Operación	Ruta
Créditos de un cliente	GET /api/v1/ext/credits?customerId={uuid}&status=ACTIVE (estados PENDING_APPROVAL, APPROVED, REJECTED, ACTIVE, CLOSED)
Un crédito	GET /api/v1/ext/credits/{creditId}
Plan de pagos con lo pagado y lo pendiente	GET /api/v1/ext/credits/{creditId}/schedule
Historial de cobros	GET /api/v1/ext/credits/{creditId}/payments