REST API de finO$

Cada petición requiere tu API key vía header HTTP. Las keys se obtienen al solicitar acceso (24-48 horas).

Authorization: Bearer YOUR_API_KEY

Sandbox vs producción

Al solicitar acceso recibes dos keys: sk_sandbox_* para testing (sin cargo, procesa documentos de muestra) y sk_live_* para producción (cobra $5 MXN por hoja procesada).

POST /v1/upload

Sube un PDF de estado de cuenta y crea un job de extracción.

curl -X POST https://api.getfinos.com/v1/upload \
  -H "Authorization: Bearer $FINOS_API_KEY" \
  -F "file=@statement.pdf" \
  -F "bank_hint=bbva_mx"

{
  "job_id": "job_abc123",
  "status": "processing",
  "estimated_seconds": 15
}

Cada extracción exitosa devuelve un JSON con metadata de la cuenta, periodo, balances y array de transacciones.

{
  "bank_name": "BBVA Bancomer S.A.",
  "bank_canonical_name": "BBVA",
  "account_number": "012180001234567890",
  "account_type": "debit",

  "opening_balance":   { "amount": 18450.32, "currency": "MXN" },
  "closing_balance":   { "amount": 22107.18, "currency": "MXN" },
  "average_balance":   { "amount": 20278.75, "currency": "MXN" },

  "total_commissions": { "amount": 152.00, "currency": "MXN" },
  "statement_period_start": "2026-04-01",
  "statement_period_end":   "2026-04-30",

  "account_holder_name":    "JUAN PEREZ LOPEZ",
  "account_holder_rfc":     "PELJ810707H94",
  "account_holder_address": "AV. INSURGENTES 100, CDMX",

  "transactions": [
    {
      "day": 3, "month": 4,
      "description": "TRANSFERENCIA SPEI CLIENTE ACME SA",
      "transaction_concept": "Cobro de cliente",
      "counterparty_name": "ACME SA DE CV",
      "counterparty_rfc": "ACM800101AB1",
      "merchant_canonical_name": null,
      "amount": 15000.00,
      "currency": "MXN",
      "transaction_type": "DEBIT",
      "direction": "inflow",
      "channel": "SPEI",
      "category": "income",
      "kind_hint": "income",
      "is_recurring_likely": false
    }
  ],

  "zero_interest_installments": [
    {
      "description": "AMAZON A MESES",
      "purchase_date": "2026-02-15",
      "original_amount":    { "amount": 12000.00, "currency": "MXN" },
      "current_payment_number": 2,
      "total_payments_number": 12,
      "monthly_installment": { "amount": 1000.00, "currency": "MXN" },
      "interest_rate": 0,
      "pending_amount":      { "amount": 10000.00, "currency": "MXN" }
    }
  ]
}

Detalle de cada campo en cualquier página de banco. El JSON es idéntico para todos los bancos soportados — el mismo schema v5 aplica para BBVA, Nu, Mercado Pago, etc.

Regla clave: las líneas tipo "AMAZON A MESES 2/12" que aparecen en estados de tarjeta de crédito NO van a transactions[] — solo la compra original aparece como transaction; el plan se rastrea en zero_interest_installments[].

Los errores siguen una shape consistente: HTTP status + JSON con error.code, error.message y error.request_id.

{
  "error": {
    "code": "invalid_pdf",
    "message": "The uploaded file could not be parsed as a PDF.",
    "request_id": "req_xyz789"
  }
}

Flujo completo: subir PDF, esperar procesamiento, obtener transacciones. En producción usa webhooks en vez de polling.

async function processStatement(pdfPath) {
  // 1. Upload
  const formData = new FormData();
  formData.append('file', await fs.openAsBlob(pdfPath));
  formData.append('bank_hint', 'bbva_mx');

  const upload = await fetch('https://api.getfinos.com/v1/upload', {
    method: 'POST',
    headers: { 'Authorization': `Bearer ${process.env.FINOS_API_KEY}` },
    body: formData,
  }).then(r => r.json());

  // 2. Poll until completed (or use webhook in production)
  let job;
  do {
    await new Promise(r => setTimeout(r, 2000));
    job = await fetch(`https://api.getfinos.com/v1/jobs/${upload.job_id}`, {
      headers: { 'Authorization': `Bearer ${process.env.FINOS_API_KEY}` },
    }).then(r => r.json());
  } while (job.status === 'processing');

  if (job.status === 'failed') throw new Error(job.error.message);

  // 3. Fetch result
  const result = await fetch(`https://api.getfinos.com/v1/extractions/${job.extraction_id}`, {
    headers: { 'Authorization': `Bearer ${process.env.FINOS_API_KEY}` },
  }).then(r => r.json());

  return result.transactions;
}