API-dokumentation - Bank-Statement-Conversion

Bank Statement Conversion API

Lägg till konvertering med ett tydligt flöde för uppladdning, status och nedladdning.

Översikt

Bank Statement Conversion API är för utvecklare som vill lägga till konvertering i sin egen app. Den beskriver det publika flödet: kontrollera kontokapacitet vid behov, ladda upp filer, fråga efter jobbstatus och ladda ner färdiga resultat med den returnerade tokenen.

Den här referensen är avsiktligt begränsad till det publika konverteringsflödet.

Snabbstart

Steg 1

Skapa en API-token

Skapa en token i instrumentpanelen och skicka den som Authorization: Bearer YOUR_API_TOKEN.

Steg 2

Ladda upp en fil

POSTa till /api/upload med statement[], format och valfria inställningar.

Steg 3

Fråga jobbstatus

Använd returnerat jobId med /api/conversion-status/{jobId} tills en preview innehåller download_token.

Steg 4

Ladda ner resultat

GET /api/download/{downloadToken} och spara det binära svaret som den konverterade filen.

Autentisering

Autentisering med API-token

Alla API-anrop måste innehålla en API-token för autentisering. Tokens kan skapas i kontots instrumentpanel under API Tokens.

Så skapar du en API-token

  1. Logga in på ditt konto
  2. Gå till API Tokens i instrumentpanelen
  3. Klicka på "Create New Token" och ange ett namn
  4. Kopiera och spara tokenen säkert. Den visas bara en gång.

Använda din API-token

Inkludera API-tokenen i Authorization-headern:

Authorization: Bearer YOUR_API_TOKEN

AI-agenter

Använd API:t med AI-agenter

AI-verktyg kan integrera med samma offentliga konverteringsflöde som utvecklare. Använd OpenAPI-schemat, LLM-discoveryfiler eller MCP-slutpunkten så att agenter vet vilka konverteringsslutpunkter de ska anropa och vilka åtgärder som kräver bekräftelse.

Agent-discovery

/api/openapi.json/llms.txt/llms-full.txt/mcp/bank-statement-conversion
  • Använd /api/openapi.json för schema-aware verktyg som ChatGPT Actions eller egna agentbyggare.
  • Använd /llms.txt och /llms-full.txt för att ge agenter kanonisk produkt- och API-kontext.
  • Använd /mcp/bank-statement-conversion för MCP-kompatibla agentklienter som stödjer fjärr-MCP-servrar.

Engångsinställning av token

  1. Logga in en gång och skapa en API-token i dashboarden.
  2. Behåll alla konverteringsbehörigheter aktiverade om du inte vill ha en begränsad token.
  3. Sätt token som BSC_API_TOKEN i MCP-klientens miljö.
  4. Återkalla token från dashboarden när agentåtkomst ska stoppas.

Anslut Codex, Claude, Cursor och andra AI-klienter

Alla MCP-kompatibla AI-klienter använder samma fjärrendpoint och bearer-token. Förvara token i en miljövariabel, inte i prompts eller källkod.

Fjärr-MCP-endpoint
https://bank-statement-conversion.com/mcp/bank-statement-conversion
Autentiseringsheader
Authorization: Bearer YOUR_API_TOKEN
Codex-installation

Lägg till denna serverpost i din Codex-konfiguration.

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"

Sätt token i shell eller systemmiljö och starta sedan om AI-klienten.

Token environment variablebash
export BSC_API_TOKEN="YOUR_API_TOKEN_HERE"
Andra AI-klienter
  • Claude, Cursor och andra MCP-klienter bör använda samma endpoint-URL och Authorization bearer-token.
  • ChatGPT Actions och egna agentbyggare bör använda /api/openapi.json i stället för MCP när de behöver ett OpenAPI-schema.
  • Använd /llms.txt och /llms-full.txt som produktkontext för agenter som stödjer kunskapsfiler.

Token-behörigheter med scope

account:statusconversion:uploadconversion:readconversion:download

Workflow-endpoints

Detta är de enda endpoints som behövs för att lägga till dokumentkonvertering i din applikation.

EndpointMetodBeskrivning
/api/user-statusGETValfri förhandskontroll av krediter, sidkvot och abonnemangsplan
/api/uploadPOSTLadda upp bankutdrag för konvertering
/api/conversion-status/{jobId}GETKontrollera status för ett konverteringsjobb
/api/download/{downloadToken}GETLadda ner en färdig konvertering med tokenen från statussvaret

Kontostatus-endpoint

GET /api/user-status

Använd denna valfria endpoint före uppladdning när appen behöver bekräfta att API-tokenen har krediter, sidkvot eller betald åtkomst.

Användbara svarsfält

FältTypBeskrivning
remaining_creditsintegerTillgängliga krediter för kreditbaserade konverteringar.
remaining_daily_pagesintegerÅterstående daglig sidkvot för den autentiserade användaren.
remaining_premium_pagesintegerÅterstående månatlig premiumsidkvot för aktiv plan.
plan_typestringEffektiv abonnemangsplan för API-tokenen.

Exempelsvar

JSON-svarjson
Kopiera denna struktur för klienttolkning och felhantering.
{
  "success": true,
  "remaining_credits": 42,
  "remaining_daily_pages": 100,
  "remaining_premium_pages": 950,
  "plan_type": "premium"
}

Uppladdnings-endpoint

POST /api/upload

Med denna endpoint laddar du upp bankutdrag för konvertering. Processen är asynkron och du får ett jobb-ID för att kontrollera status senare.

Inmatningsformat som stöds

AnvändningFormatFiländelserAnteckningar
StandardkonverteringarPDF, 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, .camt053Använd för bankutdrag, fakturor och kvitton.
CSV-rensningCSV, XLS, XLSX.csv, .xls, .xlsxAnvänd endast när format är csv_clean.
Generering av betalningsfilerCSV, XLS, XLSX.csv, .xls, .xlsxAnvänd för CSV- eller Excel-betalningsrader som genererar bankklara ACH/NACHA-, CPA005-, SEPA XML-, BACS-, ABA- eller NZ-betalningsfiler.

Utmatningsformat som stöds

document_typeDokumentTillåtna format-värden
bank_statementBankutdrag
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
invoiceFaktura
csvexceljsonqb_onlineqb_desktopubl_xmlubl_peppolxrechnung_ublzugferd_pdffactur_x_pdf
receiptKvitto
csvexceljson
payment_fileBankbetalningsfil
payment_nachapayment_cpa005payment_sepa_pain001payment_bacspayment_abapayment_nz

Anropsparametrar

ParameterTypObligatoriskBeskrivning
formatstringJaUtmatningsformat. Använd ett av tillåtna format-värden ovan för valt document_type.
document_typestringNejDokumentkategori: bank_statement, invoice, receipt eller payment_file. Standard: bank_statement.
statementfile arrayJaFiler att konvertera. Skicka en eller flera filer som statement[].
conversion_modestringNejKonverteringsläge: precision eller fast. Standard är precision.
separate_debit_creditbooleanNejOm debet- och kreditkolumner ska separeras. Standard: false.
combine_filesbooleanNejOm flera filer ska kombineras till ett resultat. Standard: false.

Exempelsvar

JSON-svarjson
Kopiera denna struktur för klienttolkning och felhantering.
{
  "stage": "pending",
  "jobId": "5f3a7d8c-8a91-4a2e-9d3b-4c84f0636c12"
}

Status-endpoint

GET /api/conversion-status/{jobId}

Med denna endpoint kontrollerar du status för ett konverteringsjobb. Fråga tills jobbet är klart.

Sökvägsparametrar

ParameterTypBeskrivning
jobIdstringJobb-ID:t som returneras från uppladdnings-endpointen

Exempel på väntande svar

JSON-svarjson
Kopiera denna struktur för klienttolkning och felhantering.
{
  "stage": "processing",
  "success": false,
  "previews": []
}

Exempel på slutfört svar

JSON-svarjson
Kopiera denna struktur för klienttolkning och felhantering.
{
  "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
}

Exempel på misslyckat svar

JSON-svarjson
Kopiera denna struktur för klienttolkning och felhantering.
{
  "stage": "complete",
  "success": false,
  "error": "An error occurred during the conversion process.",
  "message": "The uploaded file could not be processed.",
  "previews": []
}

Nedladdnings-endpoint

GET /api/download/{downloadToken}

Använd download_token från ett slutfört statussvar. Skapa inte nedladdningstokens själv.

Sökvägsparametrar

ParameterTypBeskrivning
downloadTokenstringdownload_token som returneras för en konverterad fil i statussvaret.

Exempelanrop

Ladda ner med cURLbash
Kör i terminalen efter att token och nedladdningstoken har ersatts.
curl -L \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -o converted_statement.csv \
  "https://bank-statement-conversion.com/api/download/Y8Jm7qVf9sR2kP6nL4xA0bT3cD5eF1gH"

Exempelsvar

200 OK
Returnerar den konverterade filen som binär nedladdning med Content-Disposition: attachment. Filändelsen beror på önskat utmatningsformat, till exempel .csv, .xlsx, .qbo, .ofx, .xml, .json, .ach, .txt eller .aba.

Exempel på svarshuvuden

Svarshuvudenhttp
Nedladdnings-endpointen returnerar en filström i stället för 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
}

Felhantering

API:t använder standardiserade HTTP-statuskoder för att visa om anrop lyckas eller misslyckas.

StatuskodBeskrivning
200 OKAnropet lyckades
400 Bad RequestAnropet var ogiltigt eller saknade obligatoriska parametrar
401 UnauthorizedAutentisering misslyckades eller tokenen är ogiltig
403 ForbiddenDen autentiserade användaren har inte behörighet till resursen
422 Unprocessable EntityValideringsfel inträffade
500 Internal Server ErrorEtt serverfel inträffade

Exempel på felsvar

401 Obehörigjson
Kopiera denna struktur för klienttolkning och felhantering.
{
  "message": "Unauthenticated."
}
422 Valideringsfeljson
Kopiera denna struktur för klienttolkning och felhantering.
{
  "message": "The given data was invalid.",
  "errors": {
    "statement": [
      "The statement field is required."
    ],
    "format": [
      "The selected format is invalid."
    ]
  }
}
403 Otillräcklig kapacitetjson
Kopiera denna struktur för klienttolkning och felhantering.
{
  "success": false,
  "error": "Insufficient credits or page allowance for this conversion."
}

Hastighetsgränser

För rättvis API-användning gäller gränser baserat på din abonnemangsplan:

  • Premiumanvändare: 100 anrop per minut
  • Maximal filstorlek: 100MB per fil
  • Maximalt antal filer per anrop: 5

Kodexempel

Fullständiga exempel för flödet: ladda upp, fråga status och ladda ner.

1. Ladda upp2. Fråga status3. Ladda ner
JavaScript exempeljavascript
Använder axios och form-data för att ladda upp, fråga och ladda ner filen.
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}