01 Qué resuelve

Terminada la jornada de consentimiento usted tiene un grantId. Ahí empieza el trabajo caro: hablar el perfil de seguridad del SFA con cada institución, cada una con su propia URL, su propio registro de cliente y su propio token.

Esta API existe para que no lo haga. Su aplicación envía JSON y recibe JSON; la plataforma se encarga del protocolo en su nombre.

02 Dónde encaja

03 La forma de la llamada

Una sola operación cubre los endpoints sin identificador de camino:

Tres parámetros dicen qué se pide, y son obligatorios:

04 Ejemplos

Panel de saldos — el tablero del PFM

Primero el inventario de lo que el titular tiene, después el saldo de cada cuenta.

1. Qué productos hay
   GET /v1/api-requests?apiFamilyType=resources&endpoint=/resources&version=1.0
2. Las cuentas
   GET /v1/api-requests?apiFamilyType=accounts&endpoint=/accounts&version=1.0
3. El saldo de una cuenta
   GET /v1/api-requests/params/ACC-001?apiFamilyType=accounts&endpoint=/accounts/{accountID}/balance&version=1.0

El identificador va en el camino y se expande posicionalmente en el marcador {accountID} que la institución declaró. No lo concatene usted a la URL.

Categorización de gastos — el motor del PFM

Los movimientos de un período, paginados.

GET /v1/api-requests/params/ACC-001
      ?apiFamilyType=accounts
      &endpoint=/accounts/{accountID}/transactions
      &version=1.0
      &fromDate=2026-01-01
      &toDate=2026-03-31
      &page=1
      &pageSize=200

grant-id: 7f3c9e2a-...
Authorization: Bearer <token del Gateway>

Para la tarjeta de crédito, la misma llamada cambiando la familia y el marcador:

GET /v1/api-requests/params/CARD-77
      ?apiFamilyType=credit-card-accounts
      &endpoint=/accounts/{creditCardAccountID}/transactions
      &version=1.0
      &fromDate=2026-01-01&toDate=2026-03-31

Capacidad de pago — antes de ofrecer crédito

Deuda vigente y cupo comprometido, que es lo que cambia la decisión.

Conciliación de un comercio

Para el PSBI que opera sobre un comercio adquirido.

GET /v1/api-requests?apiFamilyType=payment-reports&endpoint=/payment-reports&version=1.0&fromDate=2026-03-01&toDate=2026-03-31

05 Paginación y filtros

Son cinco, y son los que los contratos del SFA definen. No hay más.

06 Lo que la plataforma no hace

Cuatro límites que conviene conocer antes de diseñar encima.

1. No interpreta el cuerpo
   La respuesta de la institución atraviesa sin deserializar. La envoltura data/links/meta y el significado de cada campo los define la norma, no esta API.
2. El estado de la institución se propaga
   Un 401, 404 o 429 emitido por la contraparte llega a usted con su cuerpo y su formato de error, que es el de la API regulada y no el de ésta.
3. No guarda los datos del titular
   Lo que se custodia es el token del grant, no la respuesta. Cada llamada va a la institución.
4. No consulta el Directorio durante la llamada
   La dirección sale de la réplica local. La NCG 569 prohíbe usar los servicios de verificación de estado del Directorio en el flujo transaccional, así que no hay búsqueda remota de respaldo: si la réplica no tiene esa institución, la llamada falla y lo dice.

07 Cuando algo sale mal

Ver el contrato OpenAPI → · ← Volver a Swaggers