Abrir datos sin arquitectura es abrir riesgo

Open Finance promete que clientes puedan compartir sus datos financieros con terceros autorizados para obtener mejores productos. La promesa es buena. La implementación es delicada.

Una API financiera mal diseñada no solo falla técnicamente. Puede exponer datos sensibles, romper confianza y crear responsabilidad regulatoria.

Principio 1: consentimiento como entidad de primera clase

El consentimiento no debe vivir como texto en una tabla de usuarios. Debe ser una entidad propia:

type Consent = {
  id: string
  subjectId: string
  providerId: string
  scopes: string[]
  status: 'active' | 'revoked' | 'expired'
  grantedAt: string
  expiresAt: string
  revokedAt?: string
  purpose: string
}

Cada acceso a datos debe poder apuntar a un consentimiento activo. Si el consentimiento vence o se revoca, los tokens derivados deben quedar inválidos.

Principio 2: scopes que significan algo

Scopes como read_all son cómodos y peligrosos. Mejor separar:

• accounts:read
• balances:read
• transactions:read:90days
• identity:read
• payments:initiate
• payments:status

Esto permite construir experiencias más honestas. Una app de presupuesto no necesita permiso para iniciar pagos. Un proveedor de crédito quizá necesita transacciones de 12 meses, no acceso indefinido.

Principio 3: auditoría inmutable

Debe registrarse:

• Quién pidió acceso.
• Qué consentimiento lo autorizó.
• Qué endpoint consultó.
• Qué campos fueron entregados.
• Cuándo ocurrió.
• Desde qué cliente o integración.
• Resultado de la llamada.

Los logs de auditoría no son logs de debugging. Tienen requisitos más estrictos: integridad, retención, búsqueda y control de acceso.

Principio 4: normalización separada de datos crudos

Guarda el evento original. Luego crea una versión normalizada.

El dato crudo permite auditoría. El dato normalizado permite producto.

Ejemplo:

{
  "raw_description": "PAGO POS 000482 SUPERM NACIONAL",
  "merchant_name": "Supermercado Nacional",
  "category": "groceries",
  "amount": 2450.75,
  "currency": "DOP",
  "confidence": 0.94
}

Si el modelo cambia, puedes reprocesar. Si un cliente disputa una clasificación, puedes volver al origen.

Principio 5: tokens de corta vida y rotación

En APIs financieras, los tokens largos son deuda de seguridad. Una base razonable:

• Access tokens de corta duración.
• Refresh tokens rotables.
• Revocación por consentimiento.
• Llaves firmantes con rotación planificada.
• mTLS o mecanismos equivalentes para clientes de alto riesgo.
• Rate limiting por cliente, usuario y endpoint.

El objetivo es limitar daño cuando algo se filtra.

Principio 6: idempotencia en operaciones de dinero

Para iniciar pagos o movimientos, cada request debe llevar una llave idempotente. Si el cliente reintenta por timeout, el sistema no puede duplicar la transacción.

Idempotency-Key: pay_01J0R7W5F9ZK8N

El backend debe devolver el mismo resultado para la misma operación lógica.

Principio 7: revocación real

Muchas plataformas permiten “desconectar” una app, pero los procesos internos siguen usando snapshots o tokens secundarios. Eso no es revocación real.

Revocar debe:

• Invalidar tokens.
• Detener sincronizaciones programadas.
• Registrar el evento.
• Notificar al tercero si aplica.
• Evitar uso futuro de datos salvo obligaciones legales o contractuales.

Cómo lo aplicamos en SSD

Cuando diseñamos integraciones financieras, usamos una separación clara:

• Capa de conectores.
• Capa de consentimiento.
• Bóveda de secretos.
• Lago de eventos crudos.
• Modelo normalizado.
• APIs de producto.
• Auditoría y monitoreo.

Esto parece más trabajo al inicio. Lo es. Pero evita reconstruir todo cuando llega el primer banco nuevo, el primer requerimiento de auditoría o el primer incidente.

Open Finance no se gana publicando endpoints. Se gana demostrando que cada dato tiene permiso, propósito y trazabilidad.

Fuentes de contexto

• BID: finanzas abiertas
• Superintendencia de Bancos: banca abierta en RD