API Bank Statement Conversion
Aggiungi la conversione con un flusso chiaro di caricamento, stato e download.
https://bank-statement-conversion.com/api/uploadEndpoint upload/conversion-status/{jobId}Endpoint stato/download/{downloadToken}Endpoint downloadPanoramica
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.
https://bank-statement-conversion.com/apiAvvio rapido
Crea un token API
Genera un token nella dashboard e invialo come Authorization: Bearer YOUR_API_TOKEN.
Carica un file
Fai POST a /api/upload con statement[], format e impostazioni opzionali.
Interroga lo stato del job
Usa il jobId restituito con /api/conversion-status/{jobId} finché una preview include download_token.
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
- Accedi al tuo account
- Vai alla sezione API Tokens nella dashboard
- Fai clic su "Create New Token" e assegna un nome al token
- 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_TOKENAgenti 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.jsonper strumenti compatibili con schema, come ChatGPT Actions o builder di agenti personalizzati. - Usa
/llms.txte/llms-full.txtper fornire agli agenti il contesto canonico del prodotto e dell’API. - Usa
/mcp/bank-statement-conversionper client agente compatibili con MCP che supportano server MCP remoti.
Configurazione token una tantum
- Accedi una volta e crea un token API nella dashboard.
- Mantieni abilitate tutte le autorizzazioni di conversione, salvo se vuoi un token limitato.
- Imposta il token come BSC_API_TOKEN nell’ambiente del client MCP.
- 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.
https://bank-statement-conversion.com/mcp/bank-statement-conversionAuthorization: Bearer YOUR_API_TOKENConfigurazione Codex
Aggiungi questa voce server alla configurazione di Codex.
[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.
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
Endpoint del flusso
Questi sono gli unici endpoint necessari per aggiungere la conversione dei documenti alla tua applicazione.
| Endpoint | Metodo | Descrizione |
|---|---|---|
/api/user-status | GET | Controllo preliminare opzionale per crediti, pagine e piano di abbonamento |
/api/upload | POST | Carica estratti conto bancari per la conversione |
/api/conversion-status/{jobId} | GET | Controlla lo stato di un job di conversione |
/api/download/{downloadToken} | GET | Scarica 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
| Campo | Tipo | Descrizione |
|---|---|---|
remaining_credits | integer | Crediti disponibili per conversioni basate su crediti. |
remaining_daily_pages | integer | Pagine giornaliere rimanenti per l’utente autenticato. |
remaining_premium_pages | integer | Pagine premium mensili rimanenti per il piano effettivo. |
plan_type | string | Piano di abbonamento effettivo per il token API. |
Esempio di risposta
{
"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
| Uso | Formati | Estensioni | Note |
|---|---|---|---|
| Conversioni standard | 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 | Usa per conversioni di estratti conto, fatture e ricevute. |
| Pulizia CSV | CSV, XLS, XLSX | .csv, .xls, .xlsx | Usa solo quando format è csv_clean. |
| Generazione file di pagamento | CSV, XLS, XLSX | .csv, .xls, .xlsx | Usa 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_type | Documento | Valori format consentiti |
|---|---|---|
bank_statement | Estratto 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 |
invoice | Fattura | csvexceljsonqb_onlineqb_desktopubl_xmlubl_peppolxrechnung_ublzugferd_pdffactur_x_pdf |
receipt | Ricevuta | csvexceljson |
payment_file | File di pagamento bancario | payment_nachapayment_cpa005payment_sepa_pain001payment_bacspayment_abapayment_nz |
Usa document_type=payment_file con payment_nacha, payment_cpa005, payment_sepa_pain001, payment_bacs, payment_aba o payment_nz. Carica CSV, XLS o XLSX come statement[]; la generazione usa il flusso esistente di crediti, cronologia e token di download.
Apri generatore di file di pagamentoUse 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 generatorParametri della richiesta
| Parametro | Tipo | Obbligatorio | Descrizione |
|---|---|---|---|
format | string | Sì | Formato di output. Usa uno dei valori format consentiti sopra per il document_type selezionato. |
document_type | string | No | Categoria documento: bank_statement, invoice, receipt o payment_file. Predefinito: bank_statement. |
statement | file array | Sì | File da convertire. Invia uno o più file come statement[]. |
separate_debit_credit | boolean | No | Se separare colonne debito e credito. Predefinito: false. |
combine_files | boolean | No | Se combinare più file in un unico output. Predefinito: false. |
Esempio di risposta
{
"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
| Parametro | Tipo | Descrizione |
|---|---|---|
jobId | string | L’ID job restituito dall’endpoint di upload |
Esempio di risposta in attesa
{
"stage": "processing",
"success": false,
"previews": []
}Esempio di risposta completata
{
"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
{
"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
| Parametro | Tipo | Descrizione |
|---|---|---|
downloadToken | string | Il download_token restituito per un file convertito nella risposta di stato. |
Esempio di richiesta
curl -L \
-H "Authorization: Bearer YOUR_API_TOKEN" \
-o converted_statement.csv \
"https://bank-statement-conversion.com/api/download/Y8Jm7qVf9sR2kP6nL4xA0bT3cD5eF1gH"Esempio di risposta
200 OKEsempio di header di risposta
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 stato | Descrizione |
|---|---|
| 200 OK | La richiesta è riuscita |
| 400 Bad Request | La richiesta non è valida o mancano parametri obbligatori |
| 401 Unauthorized | Autenticazione non riuscita o token non valido |
| 403 Forbidden | L’utente autenticato non ha il permesso di accedere alla risorsa |
| 422 Unprocessable Entity | Si sono verificati errori di validazione |
| 500 Internal Server Error | Si è verificato un errore sul server |
Esempi di risposte di errore
{
"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."
}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.
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}