Open finance: guía técnica de implementación

La arquitectura de una capa de open finance

Una implementación conforme tiene seis componentes. Se pueden desplegar como un monolito o como servicios separados, pero ninguno se puede omitir.

El error de diseño más común es tratar el Consent Engine como una tabla dentro del Authorization Server. El consentimiento tiene su propio ciclo de vida, su propia interfaz para el titular y su propia retención legal; cuando vive dentro del emisor de tokens, revocar deja de ser confiable y demostrar el estado histórico se vuelve imposible.

FAPI 2.0: qué exige exactamente

Financial-grade API Security Profile 2.0 es un perfil sobre OAuth 2.0 publicado por la OpenID Foundation. No agrega un protocolo nuevo: recorta OAuth a su subconjunto seguro y obliga a mecanismos que en OAuth genérico son opcionales.

Pushed Authorization Requests (PAR, RFC 9126)

En OAuth clásico los parámetros de autorización viajan en la URL del navegador, donde quedan en historial, logs de proxy y encabezados Referer, y donde un atacante puede manipularlos. Con PAR el cliente los envía primero por un canal servidor-a-servidor autenticado, recibe un request_uri opaco de un solo uso, y solo eso viaja por el navegador.

POST /oauth/par HTTP/1.1
Host: api.opensurix.com
Content-Type: application/x-www-form-urlencoded

response_type=code
&client_id=cli_9f2a...
&redirect_uri=https://tercero.example/callback
&scope=accounts:read balances:read
&code_challenge=E9Melhoa2Ow...
&code_challenge_method=S256
&state=af0ifjsldkj

HTTP/1.1 201 Created
{
  "request_uri": "urn:ietf:params:oauth:request_uri:6esc_11ACC5b",
  "expires_in": 90
}

PKCE obligatorio (RFC 7636)

Proof Key for Code Exchange ata el código de autorización al cliente que lo inició: quien intercepte el código no puede canjearlo sin el code_verifier original. En FAPI 2.0 es obligatorio con S256; el método plain está prohibido.

Tokens sender-constrained: mTLS o DPoP

Un bearer token robado sirve a cualquiera. FAPI 2.0 exige atar el token a quien lo pidió, por una de dos vías:

• mTLS (RFC 8705). El token se ata a la huella del certificado de cliente usado en el handshake TLS. Si el token viaja sin ese certificado, el servidor lo rechaza. Es la vía preferida entre entidades vigiladas, porque el certificado ya existe por otras razones regulatorias.
• DPoP (RFC 9449). El cliente firma cada solicitud con una clave propia y adjunta la prueba en un encabezado. Útil para clientes que no pueden presentar certificados de cliente.

Autenticación de cliente sin secretos compartidos

client_secret_post y client_secret_basic quedan fuera. FAPI 2.0 admite private_key_jwt o tls_client_auth: en ambos casos la entidad prueba su identidad con criptografía asimétrica y nunca hay un secreto compartido que rotar por correo.

Lo que queda prohibido

• El flujo implícito y el híbrido con response_type que devuelve tokens por el navegador.
• resource owner password credentials — el tercero nunca toca la clave del titular.
• Redirect URIs con comodines o coincidencia parcial: registro exacto y preregistrado.
• Algoritmos de firma débiles; RS256 como mínimo, PS256 o ES256 preferidos.

Diseñar el motor de consentimientos

El consentimiento es el objeto central del modelo y el que más exigencias acumula: técnicas del estándar, legales de las Leyes 1266 y 1581, y de experiencia de usuario, porque una pantalla mal diseñada mata la conversión del ecosistema.

Qué campos tiene que llevar

• Identificación del receptor — quién pide, con su identificador del registro de la SFC, no un nombre comercial escrito a mano.
• Categorías de datos — el alcance granular, por producto y por tipo de dato, no un permiso global.
• Tipo de tratamiento — leer, agregar, analizar, iniciar pago.
• Propósito específico — para qué. Un propósito genérico como "mejorar la experiencia" no cumple.
• Vigencia — fecha de expiración explícita, no perpetua.
• Estado y su historia — creado, pendiente, activo, rechazado, revocado, expirado, con marca de tiempo de cada transición.

El ciclo de vida

Un consentimiento no es un booleano. Estos son los estados y las transiciones que hay que soportar, cada una registrada:

created ──▶ pending ──▶ active ──┬──▶ revoked    (el titular retira)
                  │              ├──▶ expired    (vence la vigencia)
                  │              └──▶ superseded (nueva versión del alcance)
                  └──▶ rejected  (el titular no autoriza)

Dos reglas que suelen omitirse. Primero: la revocación se propaga. Marcar el registro no basta; los tokens vivos emitidos bajo ese consentimiento tienen que dejar de funcionar. Segundo: el alcance no se amplía en silencio. Si el receptor necesita más datos, es un consentimiento nuevo, no un UPDATE.

El portal del titular

El titular tiene que poder ver, sin ayuda de nadie, qué autorizó, a quién, para qué y hasta cuándo, y revocarlo en un clic. Es un requisito de transparencia, y en la práctica es lo primero que revisa un supervisor cuando llega una queja.

POST /api/v1/consents
Authorization: Bearer <token>
Content-Type: application/json

{
  "subject_id": "CC-1032456789",
  "recipient_id": "sfc:tpp:00417",
  "scopes": ["accounts:read", "transactions:read", "income:verify"],
  "purpose": "Evaluación de crédito de libre inversión",
  "expires_at": "2026-10-27T00:00:00Z"
}

HTTP/1.1 201 Created
{
  "id": "cns_01J8Z...",
  "status": "pending",
  "authorize_url": "https://auth.opensurix.com/consent/cns_01J8Z..."
}

Las APIs de datos y de pagos

Con la autorización resuelta, los endpoints de recursos son la parte mecánica. Lo que importa es que el contrato coincida con el diccionario de datos de la SFC y que cada respuesta sea rastreable al consentimiento que la habilitó.

Datos financieros

GET /api/v1/accounts                      # productos del titular
GET /api/v1/accounts/:id/balance          # saldo
GET /api/v1/accounts/:id/transactions     # movimientos
GET /api/v1/accounts/:id/income           # verificación de ingresos
GET /api/v1/connectors                    # entidades conectadas

POST /api/v1/payments                     # iniciación de pago
GET  /api/v1/payments/:id                 # estado

POST /api/v1/portability/export           # portabilidad de datos
POST /api/v1/portability/import

Datos de seguros

GET  /api/v1/insurance/policies
GET  /api/v1/insurance/policies/:id/coverages
GET  /api/v1/insurance/policies/:id/coverages/verify
GET  /api/v1/insurance/claims
POST /api/v1/insurance/claims
POST /api/v1/insurance/quotes

El alcance de seguros es obligatorio en Colombia porque las aseguradoras son entidades vigiladas y por tanto proveedores de datos. Ver open insurance.

Requisitos transversales de los endpoints

• Versionado en la ruta (/api/v1/) y política de deprecación publicada, porque el estándar va a cambiar.
• Paginación por cursor en colecciones de movimientos: el desplazamiento por offset se rompe con datos que se insertan mientras se pagina.
• Idempotencia en toda operación de escritura, con clave provista por el cliente. Un pago reintentado no puede ejecutarse dos veces.
• Errores tipificados con código estable, no prosa. El tercero programa contra el código.
• Sandbox con datos sintéticos en paridad de contrato con producción. Sin sandbox, la API existe pero nadie la integra.

Directorio de participantes y certificados

El directorio de la SFC es la raíz de confianza del sistema. Registra quién es proveedor de datos, quién es tercero receptor y quién participa de forma voluntaria, y es lo que permite que dos entidades que nunca negociaron un contrato bilateral intercambien datos con seguridad.

Las obligaciones operativas que se derivan:

• Validar al receptor en cada solicitud, no en un job nocturno. Una habilitación revocada tiene que cortar el acceso de inmediato.
• Verificar vigencia y cadena del certificado presentado en el handshake mTLS.
• Mantener el propio registro al día — endpoints publicados, certificados, datos de contacto técnico.
• Rotar certificados sin ventana de indisponibilidad, lo que implica soportar dos certificados válidos durante la transición.
• Alertar sobre vencimientos con suficiente antelación. Un certificado vencido no degrada el servicio: lo apaga.

Trazabilidad, observabilidad y reportes

La Circular 004 no pide solo que el sistema funcione: pide poder demostrarlo. Eso se traduce en tres capas de registro con propósitos distintos.

1. Audit trail inmutable. Un registro por acceso a datos: identidad del receptor, consentimiento invocado, alcance efectivo, marca de tiempo y resultado. Append-only, con retención acorde a las Leyes 1266 y 1581, y exportable en un formato que un supervisor pueda leer.
2. Telemetría operacional. Latencia por endpoint, tasa de error por código, disponibilidad. Es la base de cualquier SLA y de los indicadores de seguimiento que la SFC va a exigir.
3. Evidencia de consentimiento. El estado histórico de cada autorización, reconstruible a una fecha dada. Cuando un titular reclama que nunca autorizó algo, esto es lo único que sirve.

Conviene separar el audit trail del log de aplicación desde el diseño. Mezclarlos obliga a retener terabytes de ruido bajo la política de retención más estricta, y a explicarle a un auditor por qué la evidencia legal está entremezclada con trazas de depuración.

Construir o integrar: los números

La decisión no es ideológica. Es una comparación entre lo que cuesta construir y mantener conformidad, y lo que cuesta integrar una capa que ya la tiene.

El argumento de fondo: ninguno de los componentes de esta guía diferencia comercialmente a una entidad. Un cliente jamás va a elegir un banco porque su implementación de PAR sea más elegante. Lo que diferencia es qué se construye sobre esa capa — y ese es el tiempo que un proyecto in-house consume.

Preguntas frecuentes