Documentación API - Bank-Statement-Conversion

API Bank Statement Conversion

Añade conversión de extractos bancarios a tu software con un flujo claro de carga, estado y descarga.

Resumen

La API Bank Statement Conversion es para desarrolladores que quieren añadir conversión a su propia aplicación. Documenta el flujo público: opcionalmente comprobar capacidad, subir archivos, consultar estado y descargar resultados con el token devuelto.

Esta referencia se limita intencionalmente al flujo público de conversión.

Inicio rápido

Paso 1

Crear un token API

Genera un token en el panel y envíalo como Authorization: Bearer YOUR_API_TOKEN.

Paso 2

Subir un archivo

POST a /api/upload con statement[], format y opciones.

Paso 3

Consultar el estado

Usa el jobId con /api/conversion-status/{jobId} hasta recibir download_token.

Paso 4

Descargar resultado

GET /api/download/{downloadToken} y guarda la respuesta binaria.

Autenticación

Autenticación con token API

Todas las solicitudes API deben incluir un token API. Puedes generarlo en el panel, sección API Tokens.

Cómo generar un token API

  1. Inicia sesión
  2. Ve a API Tokens en el panel
  3. Haz clic en "Create New Token" y asigna un nombre
  4. Copia y guarda el token. Solo se muestra una vez.

Usar el token API

Incluye el token en la cabecera Authorization:

Authorization: Bearer YOUR_API_TOKEN

Agentes de IA

Usar la API con agentes de IA

Las herramientas de IA pueden integrarse con el mismo flujo público de conversión que los desarrolladores. Usa el esquema OpenAPI, los archivos de descubrimiento para LLM o el endpoint MCP para que los agentes sepan qué endpoints de conversión llamar y qué acciones requieren confirmación.

Descubrimiento para agentes

/api/openapi.json/llms.txt/llms-full.txt/mcp/bank-statement-conversion
  • Usa /api/openapi.json para herramientas compatibles con esquemas, como ChatGPT Actions o constructores de agentes personalizados.
  • Usa /llms.txt y /llms-full.txt para dar a los agentes el contexto canónico del producto y de la API.
  • Usa /mcp/bank-statement-conversion para clientes de agentes compatibles con MCP que admitan servidores MCP remotos.

Configuración única del token

  1. Inicia sesión una vez y crea un token de API en el panel.
  2. Mantén habilitadas todas las capacidades de conversión salvo que quieras un token restringido.
  3. Define el token como BSC_API_TOKEN en el entorno del cliente MCP.
  4. Revoca el token desde el panel cuando deba finalizar el acceso del agente.

Conectar Codex, Claude, Cursor y otros clientes de IA

Todos los clientes de IA compatibles con MCP usan el mismo endpoint remoto y token bearer. Guarda el token en una variable de entorno, no en prompts ni en el código fuente.

Endpoint MCP remoto
https://bank-statement-conversion.com/mcp/bank-statement-conversion
Encabezado de autenticación
Authorization: Bearer YOUR_API_TOKEN
Configuración de Codex

Añade esta entrada de servidor a tu configuración de Codex.

Codex MCP configtoml
[mcp_servers.bank_statement_conversion]
url = "https://bank-statement-conversion.com/mcp/bank-statement-conversion"
bearer_token_env_var = "BSC_API_TOKEN"

Define el token en tu shell o entorno del sistema y reinicia el cliente de IA.

Token environment variablebash
export BSC_API_TOKEN="YOUR_API_TOKEN_HERE"
Otros clientes de IA
  • Claude, Cursor y otros clientes MCP deben usar el mismo endpoint y token bearer Authorization.
  • ChatGPT Actions y los constructores de agentes personalizados deben usar /api/openapi.json en lugar de MCP cuando necesiten un esquema OpenAPI.
  • Usa /llms.txt y /llms-full.txt como contexto de producto para agentes que admitan archivos de conocimiento.

Capacidades de token con alcance

account:statusconversion:uploadconversion:readconversion:download

Endpoints del flujo

Estos son los únicos endpoints necesarios para añadir conversión a tu aplicación.

EndpointMétodoDescripción
/api/user-statusGETComprobación opcional de créditos, páginas y plan
/api/uploadPOSTSubir extractos para conversión
/api/conversion-status/{jobId}GETComprobar el estado de un trabajo
/api/download/{downloadToken}GETDescargar una conversión finalizada con el token devuelto

Endpoint de estado de cuenta

GET /api/user-status

Usa este endpoint opcional antes de subir para confirmar créditos, páginas disponibles o acceso de pago.

Campos útiles de respuesta

CampoTipoDescripción
remaining_creditsintegerCréditos disponibles para conversiones basadas en créditos.
remaining_daily_pagesintegerLímite diario de páginas restante para el usuario autenticado.
remaining_premium_pagesintegerLímite mensual premium de páginas restante para el plan efectivo.
plan_typestringPlan de suscripción efectivo del token API.

Ejemplo de respuesta

Respuesta JSONjson
Copia esta estructura para el análisis del cliente y la gestión de errores.
{
  "success": true,
  "remaining_credits": 42,
  "remaining_daily_pages": 100,
  "remaining_premium_pages": 950,
  "plan_type": "premium"
}

Endpoint de carga

POST /api/upload

Este endpoint permite subir extractos bancarios para conversión. El proceso es asíncrono y recibirás un ID de trabajo para comprobar el estado más tarde.

Formatos de entrada compatibles

UsoFormatosExtensionesNotas
Conversiones estándarPDF, JPG/JPEG, PNG, TIFF/TIF, CSV, XLS/XLSX, OFX, QBO, QFX, 940, STA, MT940, MT940X, XML, CAMT.053.pdf, .jpg, .jpeg, .png, .tiff, .tif, .csv, .xls, .xlsx, .ofx, .qbo, .qfx, .940, .sta, .mt940, .mt940x, .xml, .camt053Úsalo para conversiones de extractos bancarios, facturas y recibos.
Limpiador CSVCSV, XLS, XLSX.csv, .xls, .xlsxÚsalo solo cuando format sea csv_clean.
Generación de archivos de pagoCSV, XLS, XLSX.csv, .xls, .xlsxUse para filas de pago CSV o Excel que generan archivos ACH/NACHA, CPA005, SEPA XML, BACS, ABA o NZ listos para banco.

Formatos de salida compatibles

document_typeDocumentoValores format permitidos
bank_statementExtracto bancario
csvexceljsonqb_onlineqb_desktopxeroofxofx_legacyqfxmt940mt940_moneybirdcamt053camt053_legacycamt053_moneybirdcamt053_netsuitecamt053_sap_v2camt053_sap_v8camt053_business_centralcamt053_datevcamt053_afascamt053_twinfieldtally_xmlbai2bai2_netsuitebai2_sapbai2_bank_xsagesage_cloudsage_intacctmyobdatevdatev_accountingcsv_clean
invoiceFactura
csvexceljsonqb_onlineqb_desktopubl_xmlubl_peppolxrechnung_ublzugferd_pdffactur_x_pdf
receiptRecibo
csvexceljson
payment_fileArchivo de pago bancario
payment_nachapayment_cpa005payment_sepa_pain001payment_bacspayment_abapayment_nz

Parámetros de solicitud

ParámetroTipoObligatorioDescripción
formatstringFormato de salida. Usa uno de los valores format permitidos arriba para el document_type seleccionado.
document_typestringNoCategoría de documento: bank_statement, invoice, receipt o payment_file. Predeterminado: bank_statement.
statementfile arrayArchivos a convertir. Envía uno o más archivos como statement[].
conversion_modestringNoModo de conversión: precision o fast. Por defecto es precision.
separate_debit_creditbooleanNoSi deben separarse columnas de débito y crédito. Por defecto: false.
combine_filesbooleanNoSi deben combinarse varios archivos en una sola salida. Por defecto: false.

Ejemplo de respuesta

Respuesta JSONjson
Copia esta estructura para el análisis del cliente y la gestión de errores.
{
  "stage": "pending",
  "jobId": "5f3a7d8c-8a91-4a2e-9d3b-4c84f0636c12"
}

Endpoint de estado

GET /api/conversion-status/{jobId}

Este endpoint permite comprobar el estado de un trabajo de conversión. Debes consultarlo hasta que el trabajo finalice.

Parámetros de ruta

ParámetroTipoDescripción
jobIdstringEl ID de trabajo devuelto por el endpoint de carga

Ejemplo de respuesta pendiente

Respuesta JSONjson
Copia esta estructura para el análisis del cliente y la gestión de errores.
{
  "stage": "processing",
  "success": false,
  "previews": []
}

Ejemplo de respuesta completada

Respuesta JSONjson
Copia esta estructura para el análisis del cliente y la gestión de errores.
{
  "success": true,
  "previews": [
    {
      "file_name": "bank_statement.pdf",
      "format": "CSV",
      "download_token": "Y8Jm7qVf9sR2kP6nL4xA0bT3cD5eF1gH",
      "partial_conversion": false,
      "credits_used": 1
    }
  ],
  "failed_files": [],
  "remaining_credits": 41,
  "remaining_premium_pages": 949,
  "remaining_daily_pages": 99
}

Ejemplo de respuesta fallida

Respuesta JSONjson
Copia esta estructura para el análisis del cliente y la gestión de errores.
{
  "stage": "complete",
  "success": false,
  "error": "An error occurred during the conversion process.",
  "message": "The uploaded file could not be processed.",
  "previews": []
}

Endpoint de descarga

GET /api/download/{downloadToken}

Usa el download_token devuelto dentro de una respuesta de estado completada. No construyas tokens de descarga manualmente.

Parámetros de ruta

ParámetroTipoDescripción
downloadTokenstringEl download_token devuelto para un archivo convertido en la respuesta de estado.

Ejemplo de solicitud

Descargar con cURLbash
Ejecuta desde una terminal después de reemplazar el token y el token de descarga.
curl -L \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -o converted_statement.csv \
  "https://bank-statement-conversion.com/api/download/Y8Jm7qVf9sR2kP6nL4xA0bT3cD5eF1gH"

Ejemplo de respuesta

200 OK
Devuelve el archivo convertido como descarga binaria con Content-Disposition: attachment. La extensión depende del formato solicitado, como .csv, .xlsx, .qbo, .ofx, .xml, .json, .ach, .txt o .aba.

Ejemplo de cabeceras

Cabeceras de respuestahttp
El endpoint de descarga devuelve un flujo de archivo en vez de un cuerpo JSON.
HTTP/1.1 200 OK
Content-Type: text/csv
Content-Disposition: attachment; filename="bank-statement.csv"
X-Content-Type-Options: nosniff
X-Frame-Options: DENY
}

Gestión de errores

La API usa códigos de estado HTTP estándar para indicar el éxito o fallo de las solicitudes.

Código de estadoDescripción
200 OKLa solicitud fue correcta
400 Bad RequestLa solicitud no es válida o faltan parámetros obligatorios
401 UnauthorizedLa autenticación falló o el token no es válido
403 ForbiddenEl usuario autenticado no tiene permiso para acceder al recurso
422 Unprocessable EntitySe produjeron errores de validación
500 Internal Server ErrorSe produjo un error en el servidor

Ejemplos de errores

401 No autenticadojson
Copia esta estructura para el análisis del cliente y la gestión de errores.
{
  "message": "Unauthenticated."
}
422 Error de validaciónjson
Copia esta estructura para el análisis del cliente y la gestión de errores.
{
  "message": "The given data was invalid.",
  "errors": {
    "statement": [
      "The statement field is required."
    ],
    "format": [
      "The selected format is invalid."
    ]
  }
}
403 Capacidad insuficientejson
Copia esta estructura para el análisis del cliente y la gestión de errores.
{
  "success": false,
  "error": "Insufficient credits or page allowance for this conversion."
}

Límites de uso

Para un uso justo, los límites dependen del plan:

  • Usuarios premium: 100 solicitudes por minuto
  • Tamaño máximo: 100 MB por archivo
  • Máximo: 5 archivos por solicitud

Ejemplos de código

Ejemplos completos: subir, consultar y descargar.

1. Subir2. Consultar3. Descargar
JavaScript ejemplojavascript
Usa axios y form-data para subir, consultar y descargar el archivo convertido.
1// Upload a bank statement file
2const axios = require('axios');
3const FormData = require('form-data');
4const fs = require('fs');
5
6// Your API token from the dashboard
7const API_TOKEN = 'your_api_token_here';
8
9// Create a form data object
10const formData = new FormData();
11formData.append('document_type', 'bank_statement');
12formData.append('format', 'csv');
13formData.append('statement[]', fs.createReadStream('bank_statement.pdf'));
14formData.append('separate_debit_credit', 'true');
15formData.append('combine_files', 'false');
16
17// Make the API request
18const BASE_URL = 'https://bank-statement-conversion.com/api';
19
20axios.post(`${BASE_URL}/upload`, formData, {
21  headers: {
22    'Authorization': `Bearer ${API_TOKEN}`,
23    ...formData.getHeaders()
24  }
25})
26.then(response => {
27  const jobId = response.data.jobId;
28  console.log(`Conversion job started with ID: ${jobId}`);
29
30  // Poll for job status
31  checkJobStatus(jobId);
32})
33.catch(error => {
34  console.error('Error uploading file:', error.response ? error.response.data : error.message);
35});
36
37// Function to check job status
38function checkJobStatus(jobId) {
39  axios.get(`${BASE_URL}/conversion-status/${jobId}`, {
40    headers: {
41      'Authorization': `Bearer ${API_TOKEN}`
42    }
43  })
44  .then(response => {
45    const data = response.data;
46    console.log('Job stage:', data.stage);
47
48    if (data.success && data.previews && data.previews.length > 0) {
49      const downloadToken = data.previews[0].download_token;
50      downloadFile(`${BASE_URL}/download/${downloadToken}`);
51    } else if (data.stage === 'pending' || data.stage === 'processing') {
52      // Check again after 5 seconds
53      setTimeout(() => checkJobStatus(jobId), 5000);
54    } else {
55      console.error('Conversion failed:', data.error || data.message || data);
56    }
57  })
58  .catch(error => {
59    console.error('Error checking job status:', error.response ? error.response.data : error.message);
60  });
61}
62
63// Function to download the converted file
64function downloadFile(url) {
65  const outputPath = 'converted_statement.csv';
66
67  axios({
68    method: 'get',
69    url: url,
70    responseType: 'stream',
71    headers: {
72      'Authorization': `Bearer ${API_TOKEN}`
73    }
74  })
75  .then(response => {
76    response.data.pipe(fs.createWriteStream(outputPath));
77    console.log(`File downloaded to ${outputPath}`);
78  })
79  .catch(error => {
80    console.error('Error downloading file:', error.message);
81  });
82}