Documentación de Desarrollo

Cumplimiento Ley Fintech Chile

Introducción a SFA-Sandbox

SFA-Sandbox proporciona a los equipos de desarrollo una plataforma completa y desacoplada para probar e integrar interfaces de acuerdo con el estándar **FAPI 2.0 (Financial-grade API)** y el Sistema de Finanzas Abiertas (SFA) chileno dictado por la CMF bajo las normativas **NCG 502 y NCG 514**.

FAPI 2.0 Estricto

Validación rigurosa de tokens Bearer firmados, cabeceras forenses (x-fapi-interaction-id), y flujos asíncronos y síncronos reglamentarios.

Ingeniería de Resiliencia

Simula en caliente anomalías bancarias (latencias de red, errores 500, colapsos por rate limit 429) para entrenar y robustecer tu software antes del paso a producción.

Guía de Inicio Rápido

Para iniciar el consumo del sandbox, ingresa a la plataforma utilizando tu cuenta y obtén tu **Sandbox Key** exclusiva. Todas las solicitudes deben incluir esta llave en las cabeceras técnicas para asegurar el aislamiento.

// 1. Obtener la llave Sandbox de desarrollo desde la Consola
const SANDBOX_KEY = "sfa_desarrollo_87f2ab";
// 2. Configurar las cabeceras del cliente HTTP
headers = {
"x-sandbox-key": SANDBOX_KEY,
"x-fapi-interaction-id": "18f3a2c5-d72b-426c-85a1-77e8a9d1c25f",
"Content-Type": "application/json"
}

Flujo de Redirección (Decoupled Redirect)

Es el flujo tradicional por defecto donde la aplicación Fintech crea una intención de consentimiento y luego redirecciona al usuario al portal del Banco para la firma:

Negociar Intención: Envía un POST a api.php?action=consents con los alcances del consentimiento.
Redirección Soberana: El Sandbox responde con un enlace interactivo para autorizar en el Banco Simulador.
Canje de Token: Tras la firma, canjea el código temporal mediante un POST a api.php?action=token para obtener el access token definitivo.

Nuevo: FAPI-CIBA Backchannel

Flujo CIBA Backchannel (Asíncrono)

Diseñado para integraciones móviles y server-to-server sin redirección directa. Permite iniciar la autenticación de forma silenciosa y realizar consultas periódicas (polling) de estado:

1. Registrar Sesión CIBA (POST)

POST https://sfasandbox.cl/api.php?action=ciba_auth
// Request Body:
{ "login_hint": "12.345.678-9", "scope": "accounts", "binding_message": "SFA-8891" }

2. Polling e Intercambio de Token (POST)

POST https://sfasandbox.cl/api.php?action=ciba_token
// Request Body:
{ "auth_req_id": "bcauth_7f2a8c3d9e01" }
// Respuestas del Servidor:
{"error": "authorization_pending"} // Si está en espera
{"access_token": "eyJhbG...", "token_type": "Bearer", "expires_in": 3600} // Al autorizar

Estándar de Iniciación de Pagos

Iniciación de Pagos (PISP / TEF Simulado)

SFA-Sandbox implementa el modelo de **Payment Initiation Service Provider (PISP)** para simular transferencias electrónicas inmediatas con redirección y firma interactiva de PIN de coordenadas.

1. Iniciar Intención de Pago (POST)

Registra los datos de origen, destino y monto en el servidor con tus cabeceras multitenant:

POST https://sfasandbox.cl/api.php?action=payments
// Request Headers:
"x-sandbox-key": "sfa_tu_llave_aquí"
// Request Body (JSON):
{
"amount": 15000,
"debtor_account": "12345678",
"creditor_account": "987654321",
"creditor_name": "Portal Fintech SpA",
"creditor_rut": "76.452.880-K",
"creditor_bank": "Banco Santander Chile"
}

2. Redirección y Firma interactiva (Consentimiento Web)

La API responderá con un estado 201 Created y una URL interactiva de consentimiento consent_url:

{
"payment_req_id": "urn:sfa:payment:pay_req_a89bc...",
"status": "AWAITING_AUTHORISATION",
"consent_url": "https://sfasandbox.cl/auth.php?action=payment_auth&payment_req=...",
"expires_in": 600
}

Redirecciona al pagador a consent_url. Se levantará el **Portal de Firma Externa del Banco Central** donde el usuario ingresará su PIN de 4 dígitos para autorizar o rechazar la transacción de forma inmediata.

3. Consultar Estado de Transferencia (Polling GET)

Consulta en cualquier momento el estado final del pago. Al autorizarse, el sistema generará el código único de transferencia transaction_code:

GET https://sfasandbox.cl/api.php?action=payment_status&id=urn:sfa:payment:pay_req_...
// Response (JSON al autorizarse):
{
"payment_req_id": "urn:sfa:payment:pay_req_...",
"status": "AUTHORIZED",
"transaction_code": "TEF-D8A9F1B2",
"amount": 15000,
"updated_at": "2026-05-22T03:26:00Z"
}

Cumplimiento CMF NCG 514

Información de Canales e Infraestructura (NCG 514)

La normativa **NCG 514** dictada por la CMF exige a las instituciones financieras exponer información detallada de la disponibilidad operativa de sus servicios y la ubicación geográfica de sus puntos de atención físicos.

1. Obtener Disponibilidad Operativa Dinámica (GET)

Retorna las métricas del Gateway, el Servidor de Autorización mTLS y el Core de Pagos. **Este endpoint reacciona dinámicamente al Motor de Caos**: si activas latencia o errores 500 en tu panel, las métricas del Sandbox se degradarán en tiempo real para simular un incidente:

GET https://sfasandbox.cl/api.php?action=channels_status
// Response (JSON):
{
"status": "OPERATIONAL",
"standards_compliance": { "cmf_ncg": "514", "standard_version": "v1.1" },
"channels": {
"apis": { "name": "Open Banking API Gateway", "availability_24h": 99.98, "avg_response_time_ms": 142, "status": "OPERATIONAL" },
"oauth": { "name": "FAPI Authorization Server", "availability_24h": 99.99, "avg_response_time_ms": 167, "status": "OPERATIONAL" }
}
}

2. Obtener Sucursales y Cajeros (GET)

Retorna el listado geolocalizado de sucursales físicas y cajeros automáticos del banco ficticio, con horarios de atención y servicios disponibles:

GET https://sfasandbox.cl/api.php?action=branches
// Response (JSON):
{
"count": 3,
"data": [
{
"id": "suc_santiago_01",
"type": "BRANCH",
"name": "Casa Central Santiago Centro",
"address": "Moneda 1155, Santiago Centro",
"geolocation": { "latitude": -33.4442, "longitude": -70.6539 },
"status": "OPEN"
}
]
}

API AISP Transaccional (Cuentas y Saldos)

Lectura de Información de Cuentas (AISP)

Una vez que el flujo **OIDC** o **CIBA** te entrega un **Bearer Token criptográfico (JWT)**, tu aplicación puede consumir endpoints transaccionales seguros. Estos endpoints validan criptográficamente el token y aíslan los datos según tu Sandbox Key.

1. Obtener Saldos de Cuenta (AISP balances)

Consulte el saldo disponible, contable y cupos de la cuenta autorizada:

GET https://sfasandbox.cl/api.php?action=balances
// Headers requeridos:
Authorization: Bearer eyJhbGciOiJQUzI1NiIs...
x-sandbox-key: su_llave_de_desarrollo
// Response (JSON):
{
"accountId": "ACC-992810",
"currency": "CLP",
"availableBalance": 8900340,
"ledgerBalance": 8900340,
"creditLimit": 1500000,
"status": "ACTIVE"
}

2. Obtener Historial de Transacciones (AISP transactions)

Retorna el historial de transacciones. **Cumple con la exigencia regulatoria de almacenar 5 años de datos**:

GET https://sfasandbox.cl/api.php?action=transactions
// Response (JSON):
{
"accountId": "ACC-992810",
"transactions": [
{
"transactionId": "TX-9991",
"bookingDate": "2026-05-22",
"amount": -45000,
"merchantName": "Supermercados Lider Chile"
}
]
}

API de Datos Abiertos (Open Data)

Productos Financieros Públicos

Las APIs de **Datos Abiertos** no requieren autenticación Bearer Token del usuario (MFA), lo que las hace perfectas para demos públicas, comparadores de tarifas y simuladores rápidos.

1. Obtener Catálogo de Tarifas y Productos (GET)

Retorna los productos comerciales del banco, sus cobros asociados y tasas:

GET https://sfasandbox.cl/api.php?action=products
// Response (JSON público sin login):
{
"brand": "Banco Sandbox de Chile",
"products": [
{
"name": "Cuenta Corriente Open Prime",
"category": "PERSONAL_ACCOUNTS",
"fees": [ { "name": "MANTENCION_MENSUAL", "amount": 4500 } ]
}
]
}

Motor de Caos e Inyección de Anomalías

A través de tu panel web, puedes programar al Gateway para inyectar fallas selectivas en vuelo, simulando problemas reales de los cores bancarios para validar el comportamiento offline de tu software:

⏱️ Latencia Selectiva

Agrega +3500ms a todas las llamadas del proxy.

❌ Colapso de Servidor (500)

Fuerza respuestas HTTP 500 simulando caída de APIs.

📡 Timeouts CIBA

El polling retorna pending de forma infinita.

El Túnel Proxy de Caos

Para equipos avanzados, puedes canalizar tráfico real a través de nuestro reverse-proxy proxy.php para interceptar peticiones destinadas a servidores del banco de producción real y sabotearlas según tus configuraciones de caos.

# Header requerido para enrutar el proxy
x-proxy-target: https://api.bancoreal.cl/v1/accounts
x-sandbox-key: sfa_mi_llave_99827

Ejemplos de Consumo Prácticos

Node.js (Axios)

const axios = require('axios');

axios.post('https://sfasandbox.cl/api.php?action=ciba_auth', {
    login_hint: '12.345.678-9',
    scope: 'accounts',
    binding_message: 'SFA-1002'
}, {
    headers: {
        'x-sandbox-key': 'sfa_desarrollo_87f2ab',
        'x-fapi-interaction-id': 'b1c67d3e-9081-42cb-a311-2df8a2f1c8e9'
    }
}).then(res => console.log('AuthReqID:', res.data.auth_req_id));

Python (Requests)

import requests

headers = {
    'x-sandbox-key': 'sfa_desarrollo_87f2ab',
    'x-fapi-interaction-id': 'b1c67d3e-9081-42cb-a311-2df8a2f1c8e9'
}

data = {
    'login_hint': '12.345.678-9',
    'scope': 'accounts',
    'binding_message': 'SFA-1002'
}

r = requests.post('https://sfasandbox.cl/api.php?action=ciba_auth', json=data, headers=headers)
print(r.json())