API-documentatie

Volledige referentie voor integratie met de Balanzio bankafschriftconversie API

Introductie

De Balanzio API stelt u in staat om bankafschrift-PDF's te converteren naar gestructureerde gegevensformaten (CSV, XLSX, JSON). Onze API ondersteunt zowel tekstgebaseerde als beeldgebaseerde (gescande) PDF's met OCR-verwerking.

Snelle Verwerking

Tekst-PDF's in seconden, OCR in <30s per pagina

Veilig & AVG-compliant

Automatische verwijdering na 24u

Multi-bank Ondersteuning

100+ ondersteunde banken

Authenticatie

Alle API-verzoeken vereisen authenticatie met een Bearer token. Neem uw API-sleutel op in de Authorization header:

HTTP
Authorization: Bearer YOUR_API_KEY
Houd uw API-sleutel geheim!

Maak uw API-sleutel nooit openbaar in client-side code of commit deze niet naar versiebeheer.

Endpoints

Basis URL

https://api.balanzio.app/api/v1

Bankafschrift Uploaden

POST
/bank-statement

Upload één of meerdere PDF-bestanden voor verwerking. De API detecteert automatisch of de PDF tekstgebaseerd of beeldgebaseerd (gescand) is.

Verzoekparameters

ParameterTypeVereistBeschrijving
filesfile[]JaPDF-bestand(en) om te verwerken (max 3MB elk)

Verzoekvoorbeeld

curl
curl -X POST https://api.balanzio.app/api/v1/bank-statement \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -F "files=@statement.pdf"

Respons (201 Created)

json
[
  {
    "uuid": "550e8400-e29b-41d4-a716-446655440000",
    "filename": "statement.pdf",
    "pdfType": "TEXT_BASED",
    "state": "READY",
    "numberOfPages": 3
  }
]

Responsvelden

VeldTypeBeschrijving
uuidstringUnieke identificatie voor het geüploade bestand
filenamestringOriginele bestandsnaam
pdfTypestringTEXT_BASED of IMAGE_BASED
statestringREADY (tekst) of PROCESSING (OCR)
numberOfPagesnumberTotaal aantal pagina's in de PDF

Verwerkingsstatus Controleren

POST
/bank-statement/status

Controleer de verwerkingsstatus van geüploade bestanden. Gebruik dit endpoint om te pollen voor OCR-voltooiing.

Verzoekvoorbeeld

curl
curl -X POST https://api.balanzio.app/api/v1/bank-statement/status \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "uuids": ["550e8400-e29b-41d4-a716-446655440000"]
  }'

Respons (200 OK)

json
[
  {
    "uuid": "550e8400-e29b-41d4-a716-446655440000",
    "filename": "statement.pdf",
    "pdfType": "IMAGE_BASED",
    "state": "COMPLETED",
    "numberOfPages": 3,
    "progress": 100
  }
]

Converteren naar Formaat

POST
/bank-statement/convert

Converteer verwerkte afschriften naar CSV, XLSX of JSON formaat.

Query Parameters

ParameterTypeVereistBeschrijving
formatstringJaCSV, XLSX, of JSON

Verzoekvoorbeeld (CSV)

curl
curl -X POST "https://api.balanzio.app/api/v1/bank-statement/convert?format=CSV" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "uuid": "550e8400-e29b-41d4-a716-446655440000"
  }' \
  -o statement.csv

Verzoekvoorbeeld (JSON)

curl
curl -X POST "https://api.balanzio.app/api/v1/bank-statement/convert?format=JSON" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "uuid": "550e8400-e29b-41d4-a716-446655440000"
  }'

Respons (JSON formaat)

json
{
  "transactions": [
    {
      "date": "2024-01-15",
      "description": "VIREMENT SALAIRE",
      "amount": 3500.00,
      "balance": 4250.50,
      "currency": "EUR"
    },
    {
      "date": "2024-01-16",
      "description": "CARTE 12/01 SUPERMARCHE",
      "amount": -85.30,
      "balance": 4165.20,
      "currency": "EUR"
    }
  ],
  "metadata": {
    "bank": "BNP Paribas",
    "accountNumber": "****1234",
    "statementPeriod": "2024-01"
  },
  "warnings": []
}

PDF-wachtwoord Instellen

POST
/bank-statement/set-password

Geef wachtwoord voor met wachtwoord beveiligde PDF's.

Verzoekvoorbeeld

curl
curl -X POST https://api.balanzio.app/api/v1/bank-statement/set-password \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "uuid": "550e8400-e29b-41d4-a716-446655440000",
    "password": "mySecretPassword123"
  }'

Respons (200 OK)

json
{
  "uuid": "550e8400-e29b-41d4-a716-446655440000",
  "state": "READY",
  "passwordSet": true
}

Gebruikersinfo Ophalen

GET
/user

Haal huidige gebruikersinformatie op, inclusief credits en abonnementsdetails.

Verzoekvoorbeeld

curl
curl -X GET https://api.balanzio.app/api/v1/user \
  -H "Authorization: Bearer YOUR_API_KEY"

Respons (200 OK)

json
{
  "user": {
    "userId": 123,
    "firstName": "John",
    "lastName": "Doe",
    "email": "john@example.com",
    "emailVerified": true,
    "referralCode": "ABC123"
  },
  "credits": {
    "paidCredits": 1000,
    "freeCredits": 50
  },
  "unlimitedCredits": false,
  "subscriptionCount": 1,
  "plan": "pro",
  "saveConvertedFiles": false,
  "hasPaymentMethod": true
}

Foutcodes

Alle fouten retourneren een JSON-respons met een foutcode en bericht:

json
{
  "error": "INVALID_FILE_TYPE",
  "message": "Only PDF files are accepted",
  "recovery": "Please upload a PDF file"
}
StatusFoutcodeBeschrijving
400
INVALID_FILE_TYPEBestand is geen PDF
400
INVALID_FORMATOngeldige formaatparameter (moet CSV, XLSX of JSON zijn)
401
UNAUTHORIZEDOngeldige of ontbrekende API-sleutel
403
INSUFFICIENT_CREDITSNiet genoeg credits om bestand te verwerken
404
FILE_NOT_FOUNDBestand UUID niet gevonden
413
FILE_TOO_LARGEBestand overschrijdt 3MB-limiet
422
PASSWORD_REQUIREDPDF is met wachtwoord beveiligd
422
INVALID_PASSWORDOnjuist PDF-wachtwoord
429
RATE_LIMIT_EXCEEDEDTe veel verzoeken
500
INTERNAL_ERRORServerfout, probeer het opnieuw

Rate Limits

Anonieme Gebruikers

10 verzoeken per minuut

1 pagina per dag

Geen gelijktijdige uploads

Geauthenticeerde Gebruikers

60 verzoeken per minuut

Op credits gebaseerd (afhankelijk van abonnement)

Tot 5 gelijktijdige uploads

Rate limit headers: Alle responsen bevatten X-RateLimit-Limit, X-RateLimit-Remaining en X-RateLimit-Reset headers.

Volledige Codevoorbeelden

Python

python
import requests
import time

API_KEY = "YOUR_API_KEY"
BASE_URL = "https://api.balanzio.app/api/v1"
HEADERS = {"Authorization": f"Bearer {API_KEY}"}

# 1. Upload PDF
with open("statement.pdf", "rb") as f:
    files = {"files": f}
    response = requests.post(
        f"{BASE_URL}/bank-statement",
        headers=HEADERS,
        files=files
    )
    data = response.json()
    file_uuid = data[0]["uuid"]
    pdf_type = data[0]["pdfType"]
    print(f"Uploaded: {file_uuid} ({pdf_type})")

# 2. Poll status if OCR is needed
if pdf_type == "IMAGE_BASED":
    while True:
        response = requests.post(
            f"{BASE_URL}/bank-statement/status",
            headers=HEADERS,
            json={"uuids": [file_uuid]}
        )
        status = response.json()[0]
        if status["state"] == "COMPLETED":
            print("Processing complete!")
            break
        elif status["state"] == "ERROR":
            print("Processing failed:", status.get("error"))
            break
        print(f"Progress: {status.get('progress', 0)}%")
        time.sleep(3)

# 3. Convert to JSON
response = requests.post(
    f"{BASE_URL}/bank-statement/convert",
    headers=HEADERS,
    params={"format": "JSON"},
    json={"uuid": file_uuid}
)

transactions = response.json()
print(f"Found {len(transactions['transactions'])} transactions")
for txn in transactions["transactions"]:
    print(f"{txn['date']}: {txn['description']} - {txn['amount']} {txn['currency']}")

Node.js

javascript
const FormData = require('form-data');
const fs = require('fs');
const fetch = require('node-fetch');

const API_KEY = 'YOUR_API_KEY';
const BASE_URL = 'https://api.balanzio.app/api/v1';
const HEADERS = { 'Authorization': `Bearer ${API_KEY}` };

async function convertBankStatement() {
  // 1. Upload PDF
  const form = new FormData();
  form.append('files', fs.createReadStream('statement.pdf'));

  let response = await fetch(`${BASE_URL}/bank-statement`, {
    method: 'POST',
    headers: HEADERS,
    body: form
  });

  const uploadData = await response.json();
  const fileUuid = uploadData[0].uuid;
  const pdfType = uploadData[0].pdfType;
  console.log(`Uploaded: ${fileUuid} (${pdfType})`);

  // 2. Poll status if OCR needed
  if (pdfType === 'IMAGE_BASED') {
    let completed = false;
    while (!completed) {
      response = await fetch(`${BASE_URL}/bank-statement/status`, {
        method: 'POST',
        headers: { ...HEADERS, 'Content-Type': 'application/json' },
        body: JSON.stringify({ uuids: [fileUuid] })
      });

      const statusData = await response.json();
      const status = statusData[0];

      if (status.state === 'COMPLETED') {
        console.log('Processing complete!');
        completed = true;
      } else if (status.state === 'ERROR') {
        throw new Error(`Processing failed: ${status.error}`);
      } else {
        console.log(`Progress: ${status.progress || 0}%`);
        await new Promise(resolve => setTimeout(resolve, 3000));
      }
    }
  }

  // 3. Convert to JSON
  response = await fetch(
    `${BASE_URL}/bank-statement/convert?format=JSON`,
    {
      method: 'POST',
      headers: { ...HEADERS, 'Content-Type': 'application/json' },
      body: JSON.stringify({ uuid: fileUuid })
    }
  );

  const transactions = await response.json();
  console.log(`Found ${transactions.transactions.length} transactions`);

  transactions.transactions.forEach(txn => {
    console.log(`${txn.date}: ${txn.description} - ${txn.amount} ${txn.currency}`);
  });
}

convertBankStatement().catch(console.error);

PHP

php
<?php

$apiKey = 'YOUR_API_KEY';
$baseUrl = 'https://api.balanzio.app/api/v1';

// 1. Upload PDF
$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, "$baseUrl/bank-statement");
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_POST, true);
curl_setopt($ch, CURLOPT_HTTPHEADER, [
    "Authorization: Bearer $apiKey"
]);

$file = new CURLFile('statement.pdf', 'application/pdf', 'statement.pdf');
curl_setopt($ch, CURLOPT_POSTFIELDS, ['files' => $file]);

$response = curl_exec($ch);
$data = json_decode($response, true);
$fileUuid = $data[0]['uuid'];
$pdfType = $data[0]['pdfType'];

echo "Uploaded: $fileUuid ($pdfType)\n";

// 2. Poll status if OCR needed
if ($pdfType === 'IMAGE_BASED') {
    do {
        sleep(3);

        $ch = curl_init();
        curl_setopt($ch, CURLOPT_URL, "$baseUrl/bank-statement/status");
        curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
        curl_setopt($ch, CURLOPT_POST, true);
        curl_setopt($ch, CURLOPT_HTTPHEADER, [
            "Authorization: Bearer $apiKey",
            "Content-Type: application/json"
        ]);
        curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode([
            'uuids' => [$fileUuid]
        ]));

        $response = curl_exec($ch);
        $statusData = json_decode($response, true);
        $status = $statusData[0];

        echo "Progress: " . ($status['progress'] ?? 0) . "%\n";
    } while ($status['state'] !== 'COMPLETED' && $status['state'] !== 'ERROR');

    echo "Processing complete!\n";
}

// 3. Convert to JSON
$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, "$baseUrl/bank-statement/convert?format=JSON");
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_POST, true);
curl_setopt($ch, CURLOPT_HTTPHEADER, [
    "Authorization: Bearer $apiKey",
    "Content-Type: application/json"
]);
curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode([
    'uuid' => $fileUuid
]));

$response = curl_exec($ch);
$transactions = json_decode($response, true);

echo "Found " . count($transactions['transactions']) . " transactions\n";

foreach ($transactions['transactions'] as $txn) {
    echo "{$txn['date']}: {$txn['description']} - {$txn['amount']} {$txn['currency']}\n";
}

curl_close($ch);
?>

Hulp Nodig?

Ondersteuning

Ons ondersteuningsteam helpt u graag met een succesvolle integratie.

Postman Collectie

Download onze Postman-collectie om alle endpoints eenvoudig te testen.