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.
https://bank-statement-conversion.com/apiInicio rápido
Crear un token API
Genera un token en el panel y envíalo como Authorization: Bearer YOUR_API_TOKEN.
Subir un archivo
POST a /api/upload con statement[], format y opciones.
Consultar el estado
Usa el jobId con /api/conversion-status/{jobId} hasta recibir download_token.
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
- Inicia sesión
- Ve a API Tokens en el panel
- Haz clic en "Create New Token" y asigna un nombre
- 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_TOKENAgentes 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.jsonpara herramientas compatibles con esquemas, como ChatGPT Actions o constructores de agentes personalizados. - Usa
/llms.txty/llms-full.txtpara dar a los agentes el contexto canónico del producto y de la API. - Usa
/mcp/bank-statement-conversionpara clientes de agentes compatibles con MCP que admitan servidores MCP remotos.
Configuración única del token
- Inicia sesión una vez y crea un token de API en el panel.
- Mantén habilitadas todas las capacidades de conversión salvo que quieras un token restringido.
- Define el token como BSC_API_TOKEN en el entorno del cliente MCP.
- 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.
https://bank-statement-conversion.com/mcp/bank-statement-conversionAuthorization: Bearer YOUR_API_TOKENConfiguración de Codex
Añade esta entrada de servidor a tu configuración de Codex.
[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.
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
Endpoints del flujo
Estos son los únicos endpoints necesarios para añadir conversión a tu aplicación.
| Endpoint | Método | Descripción |
|---|---|---|
/api/user-status | GET | Comprobación opcional de créditos, páginas y plan |
/api/upload | POST | Subir extractos para conversión |
/api/conversion-status/{jobId} | GET | Comprobar el estado de un trabajo |
/api/download/{downloadToken} | GET | Descargar 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
| Campo | Tipo | Descripción |
|---|---|---|
remaining_credits | integer | Créditos disponibles para conversiones basadas en créditos. |
remaining_daily_pages | integer | Límite diario de páginas restante para el usuario autenticado. |
remaining_premium_pages | integer | Límite mensual premium de páginas restante para el plan efectivo. |
plan_type | string | Plan de suscripción efectivo del token API. |
Ejemplo de respuesta
{
"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
| Uso | Formatos | Extensiones | Notas |
|---|---|---|---|
| Conversiones estándar | PDF, 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 CSV | CSV, XLS, XLSX | .csv, .xls, .xlsx | Úsalo solo cuando format sea csv_clean. |
| Generación de archivos de pago | CSV, XLS, XLSX | .csv, .xls, .xlsx | Use 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_type | Documento | Valores format permitidos |
|---|---|---|
bank_statement | Extracto 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 |
invoice | Factura | csvexceljsonqb_onlineqb_desktopubl_xmlubl_peppolxrechnung_ublzugferd_pdffactur_x_pdf |
receipt | Recibo | csvexceljson |
payment_file | Archivo de pago bancario | payment_nachapayment_cpa005payment_sepa_pain001payment_bacspayment_abapayment_nz |
Use document_type=payment_file con payment_nacha, payment_cpa005, payment_sepa_pain001, payment_bacs, payment_aba o payment_nz. Suba CSV, XLS o XLSX como statement[]; la generación usa el flujo existente de créditos, historial y tokens de descarga.
Abrir generador de archivos de pagoUse document_type=positive_pay_file with format=positive_pay. Upload CSV, XLS, or XLSX check rows as statement[] and pass positive_pay_settings for Chase, TD, generic CSV, or fixed-width profiles.
Open Positive Pay file generatorParámetros de solicitud
| Parámetro | Tipo | Obligatorio | Descripción |
|---|---|---|---|
format | string | Sí | Formato de salida. Usa uno de los valores format permitidos arriba para el document_type seleccionado. |
document_type | string | No | Categoría de documento: bank_statement, invoice, receipt o payment_file. Predeterminado: bank_statement. |
statement | file array | Sí | Archivos a convertir. Envía uno o más archivos como statement[]. |
conversion_mode | string | No | Modo de conversión: precision o fast. Por defecto es precision. |
separate_debit_credit | boolean | No | Si deben separarse columnas de débito y crédito. Por defecto: false. |
combine_files | boolean | No | Si deben combinarse varios archivos en una sola salida. Por defecto: false. |
Ejemplo de respuesta
{
"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ámetro | Tipo | Descripción |
|---|---|---|
jobId | string | El ID de trabajo devuelto por el endpoint de carga |
Ejemplo de respuesta pendiente
{
"stage": "processing",
"success": false,
"previews": []
}Ejemplo de respuesta completada
{
"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
{
"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ámetro | Tipo | Descripción |
|---|---|---|
downloadToken | string | El download_token devuelto para un archivo convertido en la respuesta de estado. |
Ejemplo de solicitud
curl -L \
-H "Authorization: Bearer YOUR_API_TOKEN" \
-o converted_statement.csv \
"https://bank-statement-conversion.com/api/download/Y8Jm7qVf9sR2kP6nL4xA0bT3cD5eF1gH"Ejemplo de respuesta
200 OKEjemplo de cabeceras
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 estado | Descripción |
|---|---|
| 200 OK | La solicitud fue correcta |
| 400 Bad Request | La solicitud no es válida o faltan parámetros obligatorios |
| 401 Unauthorized | La autenticación falló o el token no es válido |
| 403 Forbidden | El usuario autenticado no tiene permiso para acceder al recurso |
| 422 Unprocessable Entity | Se produjeron errores de validación |
| 500 Internal Server Error | Se produjo un error en el servidor |
Ejemplos de errores
{
"message": "Unauthenticated."
}{
"message": "The given data was invalid.",
"errors": {
"statement": [
"The statement field is required."
],
"format": [
"The selected format is invalid."
]
}
}{
"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.
npm install axios form-dataPython: pip install requestsPHP: PHP cURL extension enabledcURL: curl and jq installedGo: Go 1.20+Ruby: gem install multipart-postC#: .NET 7+npm install axios form-data1// 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}