Depósitos y préstamos

El gateway reenvía el cuerpo de cada operación al core y devuelve su respuesta tal cual: los campos y las reglas son los de la API externa del core. Esta guía muestra la ruta del gateway y remite a la guía del core para el detalle de cada campo.

Todas las escrituras llevan Authorization: Bearer $TOKEN e Idempotency-Key con un UUID nuevo por operación.

Registrar un cliente

Alcance clients:write. El cuerpo es el del alta de titular del core.

curl -s -X POST https://gateway.banco.example/v1/clients \
  -H "Authorization: Bearer $TOKEN" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
    "customerTypeCode": "NATURAL", "documentType": "V", "documentNumber": "12345678",
    "firstName": "Ana", "lastName": "Ejemplo", "email": "ana.ejemplo@correo.example"
  }'

201 con el cliente creado. Si el documento ya existe: 409 con codigo CORE_CUSTOMER_ALREADY_EXISTS y existingCustomerId.

Consulta	Ruta
Buscar clientes	GET /v1/clients?search=…&offset=0&limit=50
Un cliente (con el estado de su ficha en FULL)	GET /v1/clients/{clientId}?detailsLevel=FULL
Cuentas y préstamos del cliente	GET /v1/clients/{clientId}/deposits, GET /v1/clients/{clientId}/loans

Abrir una cuenta de depósito

Alcance deposits:write. El cuerpo es el de la apertura en el core.

curl -s https://gateway.banco.example/v1/deposit-products -H "Authorization: Bearer $TOKEN"

curl -s -X POST https://gateway.banco.example/v1/deposits \
  -H "Authorization: Bearer $TOKEN" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{ "customerId": "b4c6c1d8-bedd-4d05-ae70-a3152d4e1417", "productCode": "PRD-AHO-VES", "currency": "VES" }'

La cuenta queda activa con saldo cero.

Operación	Ruta	Alcance
Consultar (con saldo por fases en FULL)	GET /v1/deposits/{depositId}?detailsLevel=FULL	deposits:read
Saldo	GET /v1/deposits/{depositId}/balance	deposits:read
Movimientos (por cursor)	GET /v1/deposits/{depositId}/transactions?from=2026-10-01&to=2026-10-31&limit=50	deposits:read
Bloqueos	GET y POST /v1/deposits/{depositId}/blocks, POST …/blocks/{blockId}/approval, POST …/blocks/{blockId}/release	deposits:write en escritura
Cerrar	POST /v1/deposits/{depositId}:close	deposits:write

Los bloqueos siguen el flujo de cuatro ojos del core: quien aprueba debe usar otro cliente del gateway.

Mover dinero

Beta: requiere habilitación

Depósitos, retiros y transferencias por el gateway exigen que el banco habilite el permiso de pagos para tu inquilino. Si no está habilitado, la operación responde 403. Confírmalo durante la incorporación.

La cuenta de la ruta fija el lado correspondiente: no repitas sourceAccountId ni destinationAccountId (si lo envías y no coincide con la ruta, 400 CUENTA_INCONSISTENTE).

# Depósito
curl -s -X POST https://gateway.banco.example/v1/deposits/3d0c4f0e-9c7f-4b8e-8c1a-0a5b5f1d2e11/deposit-transactions \
  -H "Authorization: Bearer $TOKEN" -H "Idempotency-Key: $(uuidgen)" -H "Content-Type: application/json" \
  -d '{ "amount": "1500.00", "currency": "VES", "externalReference": "CAJA-20261013-0042" }'

# Transferencia a otra cuenta del banco
curl -s -X POST https://gateway.banco.example/v1/deposits/3d0c4f0e-9c7f-4b8e-8c1a-0a5b5f1d2e11/transfer-transactions \
  -H "Authorization: Bearer $TOKEN" -H "Idempotency-Key: $(uuidgen)" -H "Content-Type: application/json" \
  -d '{ "destinationAccountId": "8b7e6d5c-4a3f-4e2d-9c1b-0a9f8e7d6c5b", "amount": "500.00", "currency": "VES", "reference": "FACT-2026-001" }'

# Retiro
curl -s -X POST https://gateway.banco.example/v1/deposits/3d0c4f0e-9c7f-4b8e-8c1a-0a5b5f1d2e11/withdrawal-transactions \
  -H "Authorization: Bearer $TOKEN" -H "Idempotency-Key: $(uuidgen)" -H "Content-Type: application/json" \
  -d '{ "amount": "300.00", "currency": "VES", "reference": "RET-20261013-001", "channel": "API" }'

La respuesta y los errores son los de pagos del core.

Llevar un préstamo de punta a punta

Cada paso que compromete dinero exige una identidad distinta en el core. En el gateway eso significa un cliente OAuth por rol: el banco asocia a cada cliente su propia credencial del core.

Paso	Ruta del gateway	Alcance	Cuerpo
Productos	GET /v1/loan-products	loans:read	—
Simular	POST /v1/loans:simulate (sin Idempotency-Key)	loans:read	Simulación
Solicitar	POST /v1/loans	loans:write	Solicitud
Aprobar o rechazar	POST /v1/loans/{loanId}/approval	loans:write	{"decision":"APPROVE","comment":"Cumple política"}
Desembolsar	POST /v1/loans/{loanId}:disburse o …/disbursement-transactions	loans:write	{"destinationAccountId":"…"}
Pagar	POST /v1/loans/{loanId}:repay o …/repayment-transactions	loans:write	{"amount":1134.72}
Cotizar cancelación	GET /v1/loans/{loanId}/payoff-quote?asOf=2026-12-01	loans:read	—
Cancelar	POST /v1/loans/{loanId}:payOff	loans:write	{"originAccountId":"…"}

Consultas: GET /v1/loans?clientId={uuid}&accountState=ACTIVE, GET /v1/loans/{loanId}?detailsLevel=FULL (incluye el plan), GET /v1/loans/{loanId}/schedule y GET /v1/loans/{loanId}/repayment-transactions.

clientId es obligatorio al listar: el core no lista préstamos de todo el banco (sin él, 501 CORE_NO_SOPORTA).