Documentazione API - Bank-Statement-Conversion
Riferimento API

API Bank Statement Conversion

Aggiungi la conversione con un flusso chiaro di caricamento, stato e download.

Autenticazione Endpoint upload Endpoint del flusso
api.bsc / v1
URL base
https://bank-statement-conversion.com/api
Endpoint del flusso
POST/uploadEndpoint upload
GET/conversion-status/{jobId}Endpoint stato
GET/download/{downloadToken}Endpoint download

Panoramica

L’API Bank Statement Conversion è pensata per gli sviluppatori che vogliono aggiungere la conversione alla propria app. Documenta il flusso pubblico: controllare opzionalmente la capacità dell’account, caricare i file, interrogare lo stato del job e scaricare gli output completati con il token restituito.

Questa reference è intenzionalmente limitata al flusso pubblico di conversione.

Avvio rapido

Passo 1

Crea un token API

Genera un token nella dashboard e invialo come Authorization: Bearer YOUR_API_TOKEN.

Passo 2

Carica un file

Fai POST a /api/upload con statement[], format e impostazioni opzionali.

Passo 3

Interroga lo stato del job

Usa il jobId restituito con /api/conversion-status/{jobId} finché una preview include download_token.

Passo 4

Scarica l’output

Fai GET su /api/download/{downloadToken} e salva la risposta binaria come file convertito.

Autenticazione

Autenticazione con token API

Tutte le richieste API devono includere un token API per l’autenticazione. I token possono essere generati nella dashboard dell’account, nella sezione API Tokens.

Come generare un token API

  1. Accedi al tuo account
  2. Vai alla sezione API Tokens nella dashboard
  3. Fai clic su "Create New Token" e assegna un nome al token
  4. Copia e conserva il token in modo sicuro. Verrà mostrato una sola volta.

Usare il token API

Includi il token API nell’header Authorization delle richieste:

Authorization: Bearer YOUR_API_TOKEN

Agenti IA

Usare l’API con agenti IA

Gli strumenti di IA possono integrarsi con lo stesso flusso di conversione pubblico usato dagli sviluppatori. Usa lo schema OpenAPI, i file di discovery LLM o l’endpoint MCP affinché gli agenti sappiano quali endpoint di conversione chiamare e quali azioni richiedono conferma.

Discovery per agenti

/api/openapi.json/llms.txt/llms-full.txt/mcp/bank-statement-conversion
  • Usa /api/openapi.json per strumenti compatibili con schema, come ChatGPT Actions o builder di agenti personalizzati.
  • Usa /llms.txt e /llms-full.txt per fornire agli agenti il contesto canonico del prodotto e dell’API.
  • Usa /mcp/bank-statement-conversion per client agente compatibili con MCP che supportano server MCP remoti.

Configurazione token una tantum

  1. Accedi una volta e crea un token API nella dashboard.
  2. Mantieni abilitate tutte le autorizzazioni di conversione, salvo se vuoi un token limitato.
  3. Imposta il token come BSC_API_TOKEN nell’ambiente del client MCP.
  4. Revoca il token dalla dashboard quando l’accesso dell’agente deve terminare.

Collegare Codex, Claude, Cursor e altri client IA

Tutti i client IA compatibili con MCP usano lo stesso endpoint remoto e token bearer. Conserva il token in una variabile d’ambiente, non nei prompt o nel codice sorgente.

Endpoint MCP remoto
https://bank-statement-conversion.com/mcp/bank-statement-conversion
Header di autenticazione
Authorization: Bearer YOUR_API_TOKEN
Configurazione Codex

Aggiungi questa voce server alla configurazione di 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"

Imposta il token nella shell o nell’ambiente di sistema, poi riavvia il client IA.

Token environment variablebash
export BSC_API_TOKEN="YOUR_API_TOKEN_HERE"
Altri client IA
  • Claude, Cursor e altri client MCP devono usare lo stesso endpoint e lo stesso token bearer Authorization.
  • ChatGPT Actions e i builder di agenti personalizzati devono usare /api/openapi.json invece di MCP quando serve uno schema OpenAPI.
  • Usa /llms.txt e /llms-full.txt come contesto prodotto per gli agenti che supportano file di conoscenza.

Autorizzazioni token con scope

account:statusconversion:uploadconversion:readconversion:download

Endpoint del flusso

Questi sono gli unici endpoint necessari per aggiungere la conversione dei documenti alla tua applicazione.

EndpointMetodoDescrizione
/api/user-statusGETControllo preliminare opzionale per crediti, pagine e piano di abbonamento
/api/uploadPOSTCarica estratti conto bancari per la conversione
/api/conversion-status/{jobId}GETControlla lo stato di un job di conversione
/api/download/{downloadToken}GETScarica una conversione completata usando il token restituito nella risposta di stato

Endpoint stato account

GET /api/user-status

Usa questo endpoint opzionale prima del caricamento quando la tua app deve confermare che il token API abbia crediti, pagine disponibili o accesso a un piano a pagamento.

Campi utili della risposta

CampoTipoDescrizione
remaining_creditsintegerCrediti disponibili per conversioni basate su crediti.
remaining_daily_pagesintegerPagine giornaliere rimanenti per l’utente autenticato.
remaining_premium_pagesintegerPagine premium mensili rimanenti per il piano effettivo.
plan_typestringPiano di abbonamento effettivo per il token API.

Esempio di risposta

Risposta JSONjson
Copia questa struttura per il parsing lato client e la gestione degli errori.
{
  "success": true,
  "remaining_credits": 42,
  "remaining_daily_pages": 100,
  "remaining_premium_pages": 950,
  "plan_type": "premium"
}

Endpoint upload

POST /api/upload

Questo endpoint consente di caricare estratti conto bancari per la conversione. Il processo è asincrono e riceverai un ID job per controllare lo stato in seguito.

Formati di input supportati

UsoFormatiEstensioniNote
Conversioni standardPDF, 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, .camt053Usa per conversioni di estratti conto, fatture e ricevute.
Pulizia CSVCSV, XLS, XLSX.csv, .xls, .xlsxUsa solo quando format è csv_clean.
Generazione file di pagamentoCSV, XLS, XLSX.csv, .xls, .xlsxUsa per righe di pagamento CSV o Excel che generano file ACH/NACHA, CPA005, SEPA XML, BACS, ABA o NZ pronti per la revisione bancaria.

Formati di output supportati

document_typeDocumentoValori format consentiti
bank_statementEstratto conto
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
invoiceFattura
csvexceljsonqb_onlineqb_desktopubl_xmlubl_peppolxrechnung_ublzugferd_pdffactur_x_pdf
receiptRicevuta
csvexceljson
payment_fileFile di pagamento bancario
payment_nachapayment_cpa005payment_sepa_pain001payment_bacspayment_abapayment_nz

Parametri della richiesta

ParametroTipoObbligatorioDescrizione
formatstringFormato di output. Usa uno dei valori format consentiti sopra per il document_type selezionato.
document_typestringNoCategoria documento: bank_statement, invoice, receipt o payment_file. Predefinito: bank_statement.
statementfile arrayFile da convertire. Invia uno o più file come statement[].
separate_debit_creditbooleanNoSe separare colonne debito e credito. Predefinito: false.
combine_filesbooleanNoSe combinare più file in un unico output. Predefinito: false.

Esempio di risposta

Risposta JSONjson
Copia questa struttura per il parsing lato client e la gestione degli errori.
{
  "stage": "pending",
  "jobId": "5f3a7d8c-8a91-4a2e-9d3b-4c84f0636c12"
}

Endpoint stato

GET /api/conversion-status/{jobId}

Questo endpoint consente di controllare lo stato di un job di conversione. Interrogalo finché il job non è completato.

Parametri del percorso

ParametroTipoDescrizione
jobIdstringL’ID job restituito dall’endpoint di upload

Esempio di risposta in attesa

Risposta JSONjson
Copia questa struttura per il parsing lato client e la gestione degli errori.
{
  "stage": "processing",
  "success": false,
  "previews": []
}

Esempio di risposta completata

Risposta JSONjson
Copia questa struttura per il parsing lato client e la gestione degli errori.
{
  "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
}

Esempio di risposta fallita

Risposta JSONjson
Copia questa struttura per il parsing lato client e la gestione degli errori.
{
  "stage": "complete",
  "success": false,
  "error": "An error occurred during the conversion process.",
  "message": "The uploaded file could not be processed.",
  "previews": []
}

Endpoint download

GET /api/download/{downloadToken}

Usa il download_token restituito in una risposta di stato completata. Non costruire token di download manualmente.

Parametri del percorso

ParametroTipoDescrizione
downloadTokenstringIl download_token restituito per un file convertito nella risposta di stato.

Esempio di richiesta

Scarica con cURLbash
Esegui dal terminale dopo aver sostituito token e token di download.
curl -L \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -o converted_statement.csv \
  "https://bank-statement-conversion.com/api/download/Y8Jm7qVf9sR2kP6nL4xA0bT3cD5eF1gH"

Esempio di risposta

200 OK
Restituisce il file convertito come download binario con Content-Disposition: attachment. L’estensione dipende dal formato di output richiesto, ad esempio .csv, .xlsx, .qbo, .ofx, .xml, .json, .ach, .txt o .aba.

Esempio di header di risposta

Header di rispostahttp
L’endpoint di download restituisce uno stream di file invece di un corpo 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
}

Gestione errori

L’API usa codici di stato HTTP standard per indicare il successo o il fallimento delle richieste.

Codice di statoDescrizione
200 OKLa richiesta è riuscita
400 Bad RequestLa richiesta non è valida o mancano parametri obbligatori
401 UnauthorizedAutenticazione non riuscita o token non valido
403 ForbiddenL’utente autenticato non ha il permesso di accedere alla risorsa
422 Unprocessable EntitySi sono verificati errori di validazione
500 Internal Server ErrorSi è verificato un errore sul server

Esempi di risposte di errore

401 Non autorizzatojson
Copia questa struttura per il parsing lato client e la gestione degli errori.
{
  "message": "Unauthenticated."
}
422 Errore di validazionejson
Copia questa struttura per il parsing lato client e la gestione degli errori.
{
  "message": "The given data was invalid.",
  "errors": {
    "statement": [
      "The statement field is required."
    ],
    "format": [
      "The selected format is invalid."
    ]
  }
}
403 Capacità insufficientejson
Copia questa struttura per il parsing lato client e la gestione degli errori.
{
  "success": false,
  "error": "Insufficient credits or page allowance for this conversion."
}

Limiti di frequenza

Per garantire un uso equo dell’API, i limiti dipendono dal piano di abbonamento:

  • Utenti premium: 100 richieste al minuto
  • Dimensione massima: 100MB per file
  • Massimo per richiesta: 5 file

Esempi di codice

Esempi end-to-end del flusso di conversione: carica, interroga, scarica.

1. Carica2. Interroga stato3. Scarica
JavaScript esempiojavascript
Usa axios e form-data per caricare, interrogare e scaricare il file convertito.
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}