Cuentas de captación

Esta guía recorre la vida de una cuenta de captación (ahorro, corriente, nómina o plazo): desde el alta del titular hasta el cierre. Todos los ejemplos usan datos ficticios.

1. Registrar al titular

Alcance customer:write. Es el primer paso de la ficha del cliente: datos de identidad y contacto.

curl -s -X POST https://api.banco.example/api/v1/ext/customers \
  -H "X-Api-Key: $FINORA_API_KEY" \
  -H "Idempotency-Key: 6f9b1c2e-7a41-4d3e-9b0a-2c5d8e1f3a77" \
  -H "Content-Type: application/json" \
  -d '{
    "customerTypeCode": "NATURAL",
    "documentType": "V",
    "documentNumber": "12345678",
    "firstName": "Ana",
    "lastName": "Ejemplo",
    "email": "ana.ejemplo@correo.example",
    "phone": "+584120000000",
    "nationality": "VE",
    "agencyCode": "AGE-001"
  }'

Campo	Obligatorio	Notas
customerTypeCode	sí	NATURAL o JURIDICA.
documentType, documentNumber	sí	Tipo V, E, J, G, P o C; número sin guiones (4 a 20 caracteres).
firstName, lastName	en NATURAL	Hasta 80 caracteres cada uno.
companyName, taxId	en JURIDICA	taxId con formato J-12345678-9.
email	sí	Correo de contacto.
agencyCode	no	Si se omite, se usa la agencia principal.

La respuesta 201 trae el cliente con su id (UUID), que usarás como customerId. Si el documento ya está registrado, la API responde 409 (type terminado en customer-already-exists).

2. Elegir el producto

Alcance account:read. Lista los productos de captación; solo los que están activos y aprobados admiten aperturas.

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

Usa el productId o el code del producto en el paso siguiente.

3. Abrir la cuenta

Alcance account:write. El core valida el KYC del cliente, lo verifica contra listas de sanciones y personas expuestas, genera el número de cuenta y la deja activa con saldo cero.

curl -s -X POST https://api.banco.example/api/v1/ext/accounts \
  -H "X-Api-Key: $FINORA_API_KEY" \
  -H "Idempotency-Key: 550e8400-e29b-41d4-a716-446655440000" \
  -H "Content-Type: application/json" \
  -d '{
    "customerId": "b4c6c1d8-bedd-4d05-ae70-a3152d4e1417",
    "productCode": "PRD-AHO-VES",
    "currency": "VES",
    "agencyCode": "AGE-001"
  }'

Indica el producto con productId o productCode. currency es opcional; si la envías, debe coincidir con la del producto.

{
  "accountId": "3d0c4f0e-9c7f-4b8e-8c1a-0a5b5f1d2e11",
  "accountCode": "09990001000000000017",
  "customerId": "b4c6c1d8-bedd-4d05-ae70-a3152d4e1417",
  "customerCode": "V12345678",
  "productId": 99,
  "productCode": "PRD-AHO-VES",
  "productName": "Cuenta de Ahorro VES",
  "currency": "VES",
  "status": "CUENTA ACTIVA",
  "closed": false,
  "agencyId": "a0000001-0001-0001-0001-000000000001",
  "ledgerBalance": 0.00,
  "blockedBalance": 0.00,
  "availableBalance": 0.00,
  "openedAt": "2026-10-13T10:15:30-04:00",
  "pendingOutBalance": null
}

El dinero entra después con un depósito.

4. Consultar el saldo

Alcance account:read.

curl -s https://api.banco.example/api/v1/ext/accounts/3d0c4f0e-9c7f-4b8e-8c1a-0a5b5f1d2e11/balance \
  -H "X-Api-Key: $FINORA_API_KEY"

{
  "accountId": "3d0c4f0e-9c7f-4b8e-8c1a-0a5b5f1d2e11",
  "accountCode": "09990001000000000017",
  "currency": "VES",
  "ledgerBalance": 1500.00,
  "blockedBalance": 200.00,
  "availableBalance": 1250.00,
  "status": "CUENTA ACTIVA",
  "asOf": "2026-10-13T10:20:00-04:00",
  "balanceMode": "ON",
  "pendingOutBalance": 50.00,
  "pendingInBalance": 0.00,
  "phaseAvailableBalance": 1250.00,
  "phases": [
    { "address": "DEFAULT", "currency": "VES", "phase": "COMMITTED", "amount": 1500.00 },
    { "address": "DEFAULT", "currency": "VES", "phase": "PENDING_OUT", "amount": 50.00 }
  ]
}

Campo	Significado
ledgerBalance	Saldo contable en firme: apertura + ingresos − egresos.
blockedBalance	Retenciones y bloqueos vigentes.
availableBalance	Lo que se puede retirar. Con balanceMode OFF o SHADOW: contable − bloqueado. Con ON: además descuenta pendingOutBalance. Es el mismo valor que aplica el motor transaccional.
balanceMode	OFF (sin saldos por fase; los campos de fase vienen null), SHADOW (se calculan pero no cambian el disponible) u ON.
phases	Saldos por fase: COMMITTED, PENDING_OUT (autorizaciones de salida no liquidadas) y PENDING_IN.

5. Listar movimientos

Alcance account:read. Del más reciente al más antiguo, paginados por cursor (size de 1 a 100, 20 por defecto) y filtrables por día con from y to (ambos inclusive).

curl -s "https://api.banco.example/api/v1/ext/accounts/3d0c4f0e-9c7f-4b8e-8c1a-0a5b5f1d2e11/transactions?from=2026-10-01&to=2026-10-31&size=20" \
  -H "X-Api-Key: $FINORA_API_KEY"

{
  "accountId": "3d0c4f0e-9c7f-4b8e-8c1a-0a5b5f1d2e11",
  "pageSize": 20,
  "totalInPage": 1,
  "nextCursor": null,
  "hasMore": false,
  "items": [
    {
      "transactionId": "0d9d4f2e-1b0a-4f6e-8a7c-6a1c2f3b4d5e",
      "transactionDate": "2026-10-13T14:51:20-04:00",
      "direction": "CREDIT",
      "amount": 300.00,
      "currency": "VES",
      "reference": "DEP-1",
      "description": "Depósito",
      "channel": "API",
      "status": "COMPLETED",
      "commissions": 0.00,
      "ledgerRef": "pending:01a1369d-c726-7725-95c6-dc3f0ddfb649",
      "voucher": "V-001-20261013-000512"
    }
  ]
}

Mientras hasMore sea true, pide la página siguiente con ?cursor=<nextCursor>. ledgerRef es la referencia contable estable del movimiento; voucher es el comprobante y llega null hasta que el asiento se contabiliza.

6. Bloquear una cuenta (cuatro ojos)

Un bloqueo se registra con una credencial y se aprueba con otra distinta. Mientras está pendiente no afecta el saldo.

Registrar (alcance account:status). Sin amount el bloqueo es total: la cuenta no admite débitos. Con amount se reserva ese importe.

curl -s -X POST https://api.banco.example/api/v1/ext/accounts/3d0c4f0e-9c7f-4b8e-8c1a-0a5b5f1d2e11/blocks \
  -H "X-Api-Key: $CLAVE_REGISTRO" \
  -H "Idempotency-Key: 0b6d1f53-2c8e-4b7a-9e41-7d2a5c9f8e10" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "BLOQUEO_INTERNO",
    "authority": "Oficial de cumplimiento",
    "caseNumber": "CASO-2026-0042",
    "amount": 200.00,
    "notes": "Actividad inusual en revisión"
  }'

type admite EMBARGO, RETENCION_SUDEBAN, BLOQUEO_INTERNO, ORDEN_JUDICIAL y PIGNORACION_GARANTIA. endDate (opcional) libera el bloqueo al vencer. La respuesta es 202 con el bloqueo en PENDIENTE_APROBACION.

Aprobar o rechazar (alcance account:authorize, con otra credencial):

curl -s -X POST https://api.banco.example/api/v1/ext/accounts/3d0c4f0e-9c7f-4b8e-8c1a-0a5b5f1d2e11/blocks/6f1c2a7e-3a45-4c58-9d2b-1f6e0b9f7a10/approval \
  -H "X-Api-Key: $CLAVE_APROBACION" \
  -H "Idempotency-Key: 9a3e7c1d-55b2-4f0e-8d6a-1b2c3d4e5f60" \
  -H "Content-Type: application/json" \
  -d '{ "decision": "APPROVE", "comment": "Procede según el expediente" }'

REJECT exige comment. Si la misma identidad que registró intenta aprobar, la respuesta es 422 (four-eyes-violation).

Liberar (alcance account:status): POST /api/v1/ext/accounts/{accountId}/blocks/{blockId}/release con { "reason": "Revisión concluida sin hallazgos" } (obligatorio). Consultar: GET /api/v1/ext/accounts/{accountId}/blocks devuelve los bloqueos en cualquier estado.

7. Cerrar la cuenta

Alcance account:status. Exige saldo contable y bloqueado en cero, ningún bloqueo vigente ni pendiente, ninguna operación en curso, ningún crédito vigente y un código de motivo (reasonCode, texto corto como SOLICITUD_CLIENTE). Después de cerrada, el core rechaza todo movimiento.

curl -s -X POST https://api.banco.example/api/v1/ext/accounts/3d0c4f0e-9c7f-4b8e-8c1a-0a5b5f1d2e11/close \
  -H "X-Api-Key: $FINORA_API_KEY" \
  -H "Idempotency-Key: c41f0a9e-6b7d-4e2a-8f13-5d9c0b7a2e44" \
  -H "Content-Type: application/json" \
  -d '{ "reasonCode": "SOLICITUD_CLIENTE", "notes": "El titular cierra la relación" }'

La respuesta trae la cuenta con closed: true.

Otras consultas

Operación	Ruta
Cuentas de un cliente (abiertas y cerradas)	GET /api/v1/ext/accounts?customerId={uuid}
Una cuenta	GET /api/v1/ext/accounts/{accountId}
Cuenta por número	GET /api/v1/ext/accounts/by-code/{accountCode}