Documentación de la API de BankConv

Autenticación

Cada solicitud requiere una clave de API del equipo, enviada como token Bearer:

Authorization: Bearer sk_live_your_api_key

Las claves de API pertenecen a un equipo. Créelas en la aplicación de BankConv, en la configuración de su equipo. La clave completa se muestra una sola vez, al crearla: guárdela en un lugar seguro. Las conversiones por la API usan las páginas del plan de su equipo; vea la facturación.

Inicio rápido

1. Subir un estado de cuenta

curl -X POST https://bankconv.com/api/v1/conversions \
  -H "Authorization: Bearer sk_live_your_api_key" \
  -F "[email protected]"

La API responde 201 Created con la nueva conversión:

{
  "data": {
    "id": "9a8b7c6d-…",
    "status": "processing",
    "pages_count": 3,
    "created_at": "2026-10-11T12:00:00Z",
    "input": {
      "filename": "statement.pdf",
      "pages_count": 3
    }
  }
}

2. Consultar el estatus

curl https://bankconv.com/api/v1/conversions/9a8b7c6d-… \
  -H "Authorization: Bearer sk_live_your_api_key"

Repita cada pocos segundos hasta que status sea completed o failed.

3. Descargar los resultados

# JSON (default)
curl https://bankconv.com/api/v1/conversions/9a8b7c6d-…/download \
  -H "Authorization: Bearer sk_live_your_api_key"

# CSV, with matching tables merged into one transaction list
curl "https://bankconv.com/api/v1/conversions/9a8b7c6d-…/download?format=csv&view=merged" \
  -H "Authorization: Bearer sk_live_your_api_key" \
  -o statement.csv

# QBO for QuickBooks Desktop (also ofx, qfx or xero)
curl "https://bankconv.com/api/v1/conversions/9a8b7c6d-…/download?format=qbo" \
  -H "Authorization: Bearer sk_live_your_api_key" \
  -o statement.qbo

Endpoints

Todas las rutas son relativas a https://bankconv.com/api/v1.

Crear una conversión

POST /conversions recibe un cuerpo multipart/form-data.

Para un estado de cuenta protegido con contraseña, envíe la contraseña junto con el archivo:

curl -X POST https://bankconv.com/api/v1/conversions \
  -H "Authorization: Bearer sk_live_your_api_key" \
  -F "[email protected]" \
  -F "password=the_pdf_password"

Si no conoce la contraseña, las páginas de los bancos indican el formato que usa cada banco cuando lo hemos podido confirmar.

Listar conversiones

GET /conversions devuelve las conversiones de su equipo, de la más reciente a la más antigua.

Obtener los movimientos

GET /conversions/{id}/transactions devuelve los movimientos del estado de cuenta listos para usar: fechas reales, un solo importe con signo (abonos en positivo, cargos en negativo), el saldo acumulado, y sin el saldo inicial ni las filas de totales. Los importes son cadenas decimales en la moneda del estado de cuenta.

curl https://bankconv.com/api/v1/conversions/9a8b7c6d-…/transactions \
  -H "Authorization: Bearer sk_live_your_api_key"

{
  "data": {
    "tables": "0:1,1:0",
    "institution": "JPMorgan Chase Bank, N.A.",
    "country": "US",
    "account_type": "checking",
    "account_number": "XXXX4821",
    "currency": "USD",
    "period": { "start": "2026-01-03", "end": "2026-01-31" },
    "transaction_count": 42,
    "transactions": [
      { "date": "2026-01-03", "description": "Payroll deposit", "reference": null, "amount": "3200.00", "balance": "4450.00" },
      { "date": "2026-01-04", "description": "Coffee shop", "reference": null, "amount": "-4.80", "balance": "4445.20" }
    ],
    "warnings": []
  }
}

BankConv elige el grupo de tablas que da más movimientos y le dice cuál en tables (índices de página y de tabla, desde 0). Para leer otras tablas, páselas, por ejemplo ?tables=2:0,3:0. Si no se pueden leer como movimientos, como un resumen de cuenta, la respuesta es 422 unreadable_statement con el motivo.

Descargar los resultados

GET /conversions/{id}/download funciona cuando la conversión está en completed.

La respuesta JSON contiene cada página extraída con sus bloques (tablas y texto), para que usted haga el mapeo de columnas. Para filas listas para usar, use mejor Obtener los movimientos.

Las descargas OFX, QFX, QBO y Xero incluyen las advertencias que haya, como un banco que no está en la lista de QuickBooks, como un arreglo JSON en el encabezado X-BankConv-Warnings.

Créditos y consumo

GET /credits devuelve sus páginas disponibles en el periodo de facturación actual:

{
  "data": {
    "total": 1000,
    "remaining": 842,
    "bonus": 50,
    "bonusRemaining": 50
  }
}

GET /credits/usage devuelve las páginas usadas desde el inicio del periodo:

{
  "data": {
    "period_start": "2026-09-11",
    "period_end": "2026-10-11",
    "pages_used": 158
  }
}

Respuestas y errores

Las respuestas correctas ponen el resultado bajo una clave data. Las listas agregan la información de paginación:

{
  "data": [ … ],
  "links": { … },
  "meta": {
    "current_page": 1,
    "last_page": 5,
    "per_page": 15,
    "total": 72
  }
}

Todos los errores tienen la misma forma:

{
  "error": {
    "code": "insufficient_credits",
    "message": "Not enough credits. You have 2 remaining but need 5.",
    "status": 422
  }
}

Límites de solicitudes

Cada clave de API puede hacer 60 solicitudes por minuto. Las respuestas incluyen los encabezados X-RateLimit-Limit y X-RateLimit-Remaining, y una respuesta 429 incluye Retry-After con los segundos que debe esperar.

Facturación

Cada página de un PDF convertido usa una página de las páginas mensuales de su plan. Una conversión necesita páginas suficientes para todo el documento; no se hacen conversiones parciales, y la solicitud devuelve insufficient_credits en su lugar. Si el pago de su suscripción falló, la solicitud devuelve payment_failed hasta que actualice la tarjeta.

Compare los planes en la página de precios. Precios en pesos mexicanos (MXN).

Conservación de datos

Las conversiones se eliminan automáticamente según el periodo de conservación de su equipo: 24, 48 o 72 horas, 24 de forma predeterminada. Después, las solicitudes de descarga devuelven 410 Gone. Descargue lo que necesite antes, o elimine usted mismo una conversión con DELETE /conversions/{id}. Vea seguridad y tratamiento de datos.