API-documentatie - Bank-Statement-Conversion

Bank Statement Conversion API

Voeg conversie toe met een duidelijke upload-, status- en downloadflow.

Overzicht

De Bank Statement Conversion API is bedoeld voor ontwikkelaars die conversie aan hun eigen app willen toevoegen. Deze documentatie beschrijft de publieke conversiestroom: optioneel accountcapaciteit controleren, bestanden uploaden, taakstatus opvragen en voltooide uitvoer downloaden met het teruggegeven token.

Deze referentie is bewust beperkt tot de publieke conversieworkflow.

Snelstart

Stap 1

Maak een API-token

Genereer een token in het dashboard en stuur het als Authorization: Bearer YOUR_API_TOKEN.

Stap 2

Upload een bestand

POST naar /api/upload met statement[], format en optionele conversie-instellingen.

Stap 3

Vraag taakstatus op

Gebruik de teruggegeven jobId met /api/conversion-status/{jobId} totdat een preview download_token bevat.

Stap 4

Download uitvoer

Doe GET naar /api/download/{downloadToken} en sla de binaire reactie op als geconverteerd bestand.

Authenticatie

API-tokenauthenticatie

Alle API-verzoeken moeten een API-token bevatten voor authenticatie. Tokens kunnen worden gegenereerd in het accountdashboard onder API Tokens.

Een API-token genereren

  1. Log in op je account
  2. Ga naar API Tokens in je dashboard
  3. Klik op "Create New Token" en geef je token een naam
  4. Kopieer en bewaar het gegenereerde token veilig. Het wordt maar één keer getoond.

Je API-token gebruiken

Neem je API-token op in de Authorization-header van je verzoeken:

Authorization: Bearer YOUR_API_TOKEN

AI-agenten

De API gebruiken met AI-agenten

AI-tools kunnen dezelfde openbare conversieworkflow integreren als ontwikkelaars. Gebruik het OpenAPI-schema, LLM-discoverybestanden of het MCP-eindpunt, zodat agenten weten welke conversie-eindpunten ze moeten aanroepen en welke acties bevestiging vereisen.

Agent-discovery

/api/openapi.json/llms.txt/llms-full.txt/mcp/bank-statement-conversion
  • Gebruik /api/openapi.json voor schema-aware tools zoals ChatGPT Actions of aangepaste agent-builders.
  • Gebruik /llms.txt en /llms-full.txt om agenten de canonieke product- en API-context te geven.
  • Gebruik /mcp/bank-statement-conversion voor MCP-compatibele agentclients die remote MCP-servers ondersteunen.

Eenmalige tokenconfiguratie

  1. Log één keer in en maak een API-token aan in het dashboard.
  2. Laat alle conversierechten ingeschakeld, tenzij je een beperkt token wilt.
  3. Stel het token in als BSC_API_TOKEN in de omgeving van de MCP-client.
  4. Trek het token in via het dashboard wanneer agenttoegang moet stoppen.

Codex, Claude, Cursor en andere AI-clients verbinden

Alle MCP-compatibele AI-clients gebruiken hetzelfde remote endpoint en bearer-token. Bewaar het token in een omgevingsvariabele, niet in prompts of broncode.

Remote MCP-endpoint
https://bank-statement-conversion.com/mcp/bank-statement-conversion
Authenticatieheader
Authorization: Bearer YOUR_API_TOKEN
Codex instellen

Voeg deze serververmelding toe aan je Codex-configuratie.

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"

Stel het token in je shell of systeemomgeving in en herstart daarna de AI-client.

Token environment variablebash
export BSC_API_TOKEN="YOUR_API_TOKEN_HERE"
Andere AI-clients
  • Claude, Cursor en andere MCP-clients moeten dezelfde endpoint-URL en Authorization bearer-token gebruiken.
  • ChatGPT Actions en aangepaste agent-builders moeten /api/openapi.json gebruiken in plaats van MCP wanneer ze een OpenAPI-schema nodig hebben.
  • Gebruik /llms.txt en /llms-full.txt als productcontext voor agents die kennisbestanden ondersteunen.

Tokenrechten met scope

account:statusconversion:uploadconversion:readconversion:download

Workflow-endpoints

Dit zijn de enige endpoints die nodig zijn om documentconversie aan je applicatie toe te voegen.

EndpointMethodeBeschrijving
/api/user-statusGETOptionele voorafcontrole voor credits, paginalimiet en abonnementsplan
/api/uploadPOSTBankafschriften uploaden voor conversie
/api/conversion-status/{jobId}GETDe status van een conversietaak controleren
/api/download/{downloadToken}GETEen voltooide conversie downloaden met het token uit de statusreactie

Accountstatus-endpoint

GET /api/user-status

Gebruik dit optionele endpoint vóór uploaden wanneer je app moet controleren of het API-token credits, paginalimiet of betaald toegangsniveau heeft.

Nuttige reactievelden

VeldTypeBeschrijving
remaining_creditsintegerBeschikbare credits voor conversies op basis van credits.
remaining_daily_pagesintegerResterende dagelijkse paginalimiet voor de geauthenticeerde gebruiker.
remaining_premium_pagesintegerResterende maandelijkse premium paginalimiet voor het actieve plan.
plan_typestringHet effectieve abonnementsplan voor het API-token.

Voorbeeldreactie

JSON-reactiejson
Kopieer deze structuur voor client-side parsing en foutafhandeling.
{
  "success": true,
  "remaining_credits": 42,
  "remaining_daily_pages": 100,
  "remaining_premium_pages": 950,
  "plan_type": "premium"
}

Upload-endpoint

POST /api/upload

Met dit endpoint upload je bankafschriften voor conversie. Het conversieproces is asynchroon en je ontvangt een taak-ID om later de status te controleren.

Ondersteunde invoerformaten

GebruikFormatenExtensiesNotities
StandaardconversiesPDF, 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, .camt053Gebruik voor conversies van bankafschriften, facturen en bonnen.
CSV-opschonerCSV, XLS, XLSX.csv, .xls, .xlsxGebruik alleen wanneer format csv_clean is.
Betalingsbestand genererenCSV, XLS, XLSX.csv, .xls, .xlsxGebruik voor CSV- of Excel-betaalregels die bankklare ACH/NACHA-, CPA005-, SEPA XML-, BACS-, ABA- of NZ-bestanden maken.

Ondersteunde uitvoerformaten

document_typeDocumentToegestane format-waarden
bank_statementBankafschrift
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
invoiceFactuur
csvexceljsonqb_onlineqb_desktopubl_xmlubl_peppolxrechnung_ublzugferd_pdffactur_x_pdf
receiptBon
csvexceljson
payment_fileBankbetalingsbestand
payment_nachapayment_cpa005payment_sepa_pain001payment_bacspayment_abapayment_nz

Verzoekparameters

ParameterTypeVereistBeschrijving
formatstringJaUitvoerformaat. Gebruik een van de toegestane format-waarden hierboven voor het gekozen document_type.
document_typestringNeeDocumentcategorie: bank_statement, invoice, receipt of payment_file. Standaard: bank_statement.
statementfile arrayJaBestanden om te converteren. Verstuur een of meer bestanden als statement[].
conversion_modestringNeeConversiemodus: precision of fast. Standaard is precision.
separate_debit_creditbooleanNeeOf debet- en creditkolommen moeten worden gescheiden. Standaard: false.
combine_filesbooleanNeeOf meerdere bestanden tot één uitvoer moeten worden gecombineerd. Standaard: false.

Voorbeeldreactie

JSON-reactiejson
Kopieer deze structuur voor client-side parsing en foutafhandeling.
{
  "stage": "pending",
  "jobId": "5f3a7d8c-8a91-4a2e-9d3b-4c84f0636c12"
}

Status-endpoint

GET /api/conversion-status/{jobId}

Met dit endpoint controleer je de status van een conversietaak. Poll dit endpoint totdat de taak is voltooid.

Padparameters

ParameterTypeBeschrijving
jobIdstringDe taak-ID die het uploadendpoint retourneert

Voorbeeldreactie in behandeling

JSON-reactiejson
Kopieer deze structuur voor client-side parsing en foutafhandeling.
{
  "stage": "processing",
  "success": false,
  "previews": []
}

Voorbeeldreactie voltooid

JSON-reactiejson
Kopieer deze structuur voor client-side parsing en foutafhandeling.
{
  "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
}

Voorbeeldreactie mislukt

JSON-reactiejson
Kopieer deze structuur voor client-side parsing en foutafhandeling.
{
  "stage": "complete",
  "success": false,
  "error": "An error occurred during the conversion process.",
  "message": "The uploaded file could not be processed.",
  "previews": []
}

Download-endpoint

GET /api/download/{downloadToken}

Gebruik de download_token uit een voltooide statusreactie. Maak downloadtokens niet zelf.

Padparameters

ParameterTypeBeschrijving
downloadTokenstringDe download_token die voor een geconverteerd bestand wordt teruggegeven in de statusreactie.

Voorbeeldverzoek

Downloaden met cURLbash
Voer uit in een terminal nadat token en downloadtoken zijn vervangen.
curl -L \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -o converted_statement.csv \
  "https://bank-statement-conversion.com/api/download/Y8Jm7qVf9sR2kP6nL4xA0bT3cD5eF1gH"

Voorbeeldreactie

200 OK
Geeft het geconverteerde bestand terug als binaire download met Content-Disposition: attachment. De extensie hangt af van het gevraagde uitvoerformaat, zoals .csv, .xlsx, .qbo, .ofx, .xml, .json, .ach, .txt of .aba.

Voorbeeldresponsheaders

Responsheadershttp
Het downloadendpoint retourneert een bestandsstream in plaats van een JSON-body.
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
}

Foutafhandeling

De API gebruikt standaard HTTP-statuscodes om aan te geven of verzoeken slagen of mislukken.

StatuscodeBeschrijving
200 OKHet verzoek is geslaagd
400 Bad RequestHet verzoek was ongeldig of mist verplichte parameters
401 UnauthorizedAuthenticatie is mislukt of token is ongeldig
403 ForbiddenDe geauthenticeerde gebruiker heeft geen toegang tot de resource
422 Unprocessable EntityEr zijn validatiefouten opgetreden
500 Internal Server ErrorEr is een serverfout opgetreden

Voorbeeldfoutreacties

401 Niet geautoriseerdjson
Kopieer deze structuur voor client-side parsing en foutafhandeling.
{
  "message": "Unauthenticated."
}
422 Validatiefoutjson
Kopieer deze structuur voor client-side parsing en foutafhandeling.
{
  "message": "The given data was invalid.",
  "errors": {
    "statement": [
      "The statement field is required."
    ],
    "format": [
      "The selected format is invalid."
    ]
  }
}
403 Onvoldoende capaciteitjson
Kopieer deze structuur voor client-side parsing en foutafhandeling.
{
  "success": false,
  "error": "Insufficient credits or page allowance for this conversion."
}

Snelheidslimieten

Om eerlijk gebruik van de API te garanderen, worden limieten toegepast op basis van je abonnementsplan:

  • Premiumgebruikers: 100 verzoeken per minuut
  • Maximale bestandsgrootte: 100MB per bestand
  • Maximaal aantal bestanden per verzoek: 5

Codevoorbeelden

End-to-end voorbeelden voor de conversiestroom: uploaden, opvragen en downloaden.

1. Uploaden2. Status opvragen3. Downloaden
JavaScript voorbeeldjavascript
Gebruikt axios en form-data om het geconverteerde bestand te uploaden, status op te vragen en te downloaden.
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}