Referencia de la API de finO$

finO$ convierte estados de cuenta bancarios en PDF en datos estructurados. El API te da acceso programático a esos datos ya procesados y normalizados: un solo formato sin importar de qué banco venga el estado de cuenta.

• Transacciones normalizadas de cualquier banco, con especialidad en México y Latinoamérica
• Saldos y patrimonio por cuenta, con arrastre entre periodos
• Resumen mensual y serie histórica de ingreso, gasto y patrimonio
• Conversión de divisas a la tasa de cada fecha
• Subida de PDFs para procesar, de forma asíncrona
• Conector MCP: tu agente de IA (Claude, ChatGPT) consulta estos mismos datos con tu llave
• SDKs oficiales y webhooks de notificación Próximamente

1. 1 Crea una API key en la app: Configuración → API. Se muestra una sola vez, guárdala como secreto.
2. 2 Mándala en el header Authorization de cada petición.
3. 3 Pide el resumen del mes. Si tu workspace ya tiene estados de cuenta procesados, ahí están tus cifras.

Con la llave lista, esta es la petición más corta que devuelve algo útil: el resumen del mes en curso.

curl -H "Authorization: Bearer $FINOS_API_KEY" \
  "https://api.getfinos.com/api/v1/summary?month=2026-07"

Crear una API key en la app

Todas las peticiones llevan la API key en el header Authorization, con el esquema Bearer.

Authorization: Bearer fin_sk_...

La llave se crea en la app (Configuración → API) y se muestra UNA sola vez. Cada llave está atada al workspace donde se creó: no mandes ningún encabezado de workspace; no hace falta y no cambia nada.

La misma llave conecta un cliente MCP: das de alta el conector en Claude, ChatGPT o el agente que uses, y consulta estos mismos endpoints con el scope que le diste. Más sobre esto en la comparativa con ChatGPT.

Scopes

• read Leer transacciones, cuentas, categorías, estados de cuenta, resumen y periodos.
• statements:write Subir PDFs para procesar. Va aparte porque consume saldo del wallet.

Forma de la respuesta

Todas las respuestas comparten la misma envoltura. Las listas además traen paginación:

{
  "data": [ ... ],
  "pagination": { "limit": 50, "offset": 0, "total": 213, "has_more": true }
}

Usa has_more para saber si falta pedir más; no hace falta hacer cuentas con total y offset.

Ocho operaciones sobre una sola URL base. Todas las de lectura funcionan con el scope read.

Recorrer todas las transacciones

async function allTransactions(from, to) {
  const out = [];
  let offset = 0;

  for (;;) {
    const url = new URL('https://api.getfinos.com/api/v1/transactions');
    url.search = new URLSearchParams({ from, to, limit: '200', offset: String(offset) });

    const res = await fetch(url, {
      headers: { Authorization: `Bearer ${process.env.FINOS_API_KEY}` },
    });
    const { data, pagination } = await res.json();

    out.push(...data);
    if (!pagination.has_more) return out;
    offset += pagination.limit;
  }
}

// Ojo: incluye validadas y pendientes.
const confirmed = (await allTransactions('2026-01-01', '2026-07-31'))
  .filter((tx) => tx.status === 'validated');

Subir un PDF y esperar el resultado

# 1. Subir (responde 202 con el estado de cuenta creado)
curl -X POST "https://api.getfinos.com/api/v1/statements" \
  -H "Authorization: Bearer $FINOS_API_KEY" \
  -F "file=@estado-de-cuenta.pdf"

# 2. Consultar hasta que status sea "completed"
curl -H "Authorization: Bearer $FINOS_API_KEY" \
  "https://api.getfinos.com/api/v1/statements/STATEMENT_ID"

Estos son los objetos que devuelve el API. Los campos marcados como obligatorios siempre vienen en la respuesta, aunque su valor pueda ser null.

El formato es idéntico para todos los bancos soportados: la normalización pasa antes, al procesar el PDF. Detalle por banco en las páginas de banco .

Los errores devuelven { "error": "...", "code": "..." } con el status HTTP correspondiente. Estos aplican a cualquier endpoint:

{
  "error": "Invalid API key",
  "code": "unauthorized"
}

Comportamiento que conviene tener presente al construir contra el API:

• limit tiene un máximo de 200. Un valor mayor se acota en vez de fallar.
• Los PDFs pesan máximo 10 MB por archivo.
• El procesamiento de un PDF es asíncrono: la subida responde 202 y hay que consultar el estado hasta que sea completed.
• Un 402 al subir significa saldo insuficiente. Reintentar NO ayuda: hay que recargar. La respuesta trae required_cents y available_cents.
• Ante un 429, respeta el header Retry-After antes de reintentar.