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:
Authorization: Bearer YOUR_API_KEYMaak uw API-sleutel nooit openbaar in client-side code of commit deze niet naar versiebeheer.
Endpoints
Basis URL
https://api.balanzio.app/api/v1Bankafschrift Uploaden
/bank-statementUpload één of meerdere PDF-bestanden voor verwerking. De API detecteert automatisch of de PDF tekstgebaseerd of beeldgebaseerd (gescand) is.
Verzoekparameters
| Parameter | Type | Vereist | Beschrijving |
|---|---|---|---|
files | file[] | Ja | PDF-bestand(en) om te verwerken (max 3MB elk) |
Verzoekvoorbeeld
curl -X POST https://api.balanzio.app/api/v1/bank-statement \
-H "Authorization: Bearer YOUR_API_KEY" \
-F "files=@statement.pdf"Respons (201 Created)
[
{
"uuid": "550e8400-e29b-41d4-a716-446655440000",
"filename": "statement.pdf",
"pdfType": "TEXT_BASED",
"state": "READY",
"numberOfPages": 3
}
]Responsvelden
| Veld | Type | Beschrijving |
|---|---|---|
uuid | string | Unieke identificatie voor het geüploade bestand |
filename | string | Originele bestandsnaam |
pdfType | string | TEXT_BASED of IMAGE_BASED |
state | string | READY (tekst) of PROCESSING (OCR) |
numberOfPages | number | Totaal aantal pagina's in de PDF |
Verwerkingsstatus Controleren
/bank-statement/statusControleer de verwerkingsstatus van geüploade bestanden. Gebruik dit endpoint om te pollen voor OCR-voltooiing.
Verzoekvoorbeeld
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)
[
{
"uuid": "550e8400-e29b-41d4-a716-446655440000",
"filename": "statement.pdf",
"pdfType": "IMAGE_BASED",
"state": "COMPLETED",
"numberOfPages": 3,
"progress": 100
}
]Converteren naar Formaat
/bank-statement/convertConverteer verwerkte afschriften naar CSV, XLSX of JSON formaat.
Query Parameters
| Parameter | Type | Vereist | Beschrijving |
|---|---|---|---|
format | string | Ja | CSV, XLSX, of JSON |
Verzoekvoorbeeld (CSV)
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.csvVerzoekvoorbeeld (JSON)
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)
{
"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
/bank-statement/set-passwordGeef wachtwoord voor met wachtwoord beveiligde PDF's.
Verzoekvoorbeeld
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)
{
"uuid": "550e8400-e29b-41d4-a716-446655440000",
"state": "READY",
"passwordSet": true
}Gebruikersinfo Ophalen
/userHaal huidige gebruikersinformatie op, inclusief credits en abonnementsdetails.
Verzoekvoorbeeld
curl -X GET https://api.balanzio.app/api/v1/user \
-H "Authorization: Bearer YOUR_API_KEY"Respons (200 OK)
{
"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:
{
"error": "INVALID_FILE_TYPE",
"message": "Only PDF files are accepted",
"recovery": "Please upload a PDF file"
}| Status | Foutcode | Beschrijving |
|---|---|---|
400 | INVALID_FILE_TYPE | Bestand is geen PDF |
400 | INVALID_FORMAT | Ongeldige formaatparameter (moet CSV, XLSX of JSON zijn) |
401 | UNAUTHORIZED | Ongeldige of ontbrekende API-sleutel |
403 | INSUFFICIENT_CREDITS | Niet genoeg credits om bestand te verwerken |
404 | FILE_NOT_FOUND | Bestand UUID niet gevonden |
413 | FILE_TOO_LARGE | Bestand overschrijdt 3MB-limiet |
422 | PASSWORD_REQUIRED | PDF is met wachtwoord beveiligd |
422 | INVALID_PASSWORD | Onjuist PDF-wachtwoord |
429 | RATE_LIMIT_EXCEEDED | Te veel verzoeken |
500 | INTERNAL_ERROR | Serverfout, 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
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
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
$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);
?>