Dokumentacja API

Kompletne odniesienie do integracji API konwersji wyciągów bankowych Balanzio

Wprowadzenie

API Balanzio umożliwia konwersję wyciągów bankowych PDF na formaty ustrukturyzowanych danych (CSV, XLSX, JSON). Nasze API obsługuje zarówno pliki PDF tekstowe, jak i obrazowe (skanowane) z przetwarzaniem OCR.

Szybkie przetwarzanie

Pliki PDF tekstowe w sekundach, OCR w <30s na stronę

Bezpieczne i zgodne z RODO

Automatyczne usuwanie po 24h

Obsługa wielu banków

Ponad 100 obsługiwanych banków

Uwierzytelnianie

Wszystkie żądania API wymagają uwierzytelniania za pomocą tokena Bearer. Dołącz swój klucz API w nagłówku Authorization:

HTTP
Authorization: Bearer YOUR_API_KEY
Zachowaj swój klucz API w tajemnicy!

Nigdy nie ujawniaj swojego klucza API w kodzie po stronie klienta ani nie umieszczaj go w kontroli wersji.

Punkty końcowe

Podstawowy URL

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

Prześlij wyciąg bankowy

POST
/bank-statement

Prześlij jeden lub wiele plików PDF do przetworzenia. API automatycznie wykryje, czy plik PDF jest tekstowy, czy obrazowy (skanowany).

Parametry żądania

ParametrTypWymaganyOpis
filesfile[]TakPlik(i) PDF do przetworzenia (maks. 3 MB każdy)

Przykład żądania

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

Odpowiedź (201 Created)

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

Pola odpowiedzi

PoleTypOpis
uuidstringUnikalny identyfikator przesłanego pliku
filenamestringOryginalna nazwa pliku
pdfTypestringTEXT_BASED lub IMAGE_BASED
statestringREADY (tekst) lub PROCESSING (OCR)
numberOfPagesnumberCałkowita liczba stron w PDF

Sprawdź status przetwarzania

POST
/bank-statement/status

Sprawdź status przetwarzania przesłanych plików. Użyj tego punktu końcowego do odpytywania o zakończenie OCR.

Przykład żądania

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"]
  }'

Odpowiedź (200 OK)

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

Konwertuj do formatu

POST
/bank-statement/convert

Konwertuj przetworzone wyciągi do formatu CSV, XLSX lub JSON.

Parametry zapytania

ParametrTypWymaganyOpis
formatstringTakCSV, XLSX lub JSON

Przykład żądania (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

Przykład żądania (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"
  }'

Odpowiedź (format JSON)

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": []
}

Ustaw hasło PDF

POST
/bank-statement/set-password

Podaj hasło dla plików PDF chronionych hasłem.

Przykład żądania

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"
  }'

Odpowiedź (200 OK)

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

Pobierz informacje o użytkowniku

GET
/user

Pobierz bieżące informacje o użytkowniku, w tym kredyty i szczegóły planu.

Przykład żądania

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

Odpowiedź (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
}

Kody błędów

Wszystkie błędy zwracają odpowiedź JSON z kodem błędu i komunikatem:

json
{
  "error": "INVALID_FILE_TYPE",
  "message": "Only PDF files are accepted",
  "recovery": "Please upload a PDF file"
}
StatusKod błęduOpis
400
INVALID_FILE_TYPEPlik nie jest plikiem PDF
400
INVALID_FORMATNieprawidłowy parametr formatu (musi być CSV, XLSX lub JSON)
401
UNAUTHORIZEDNieprawidłowy lub brakujący klucz API
403
INSUFFICIENT_CREDITSNiewystarczające kredyty do przetworzenia pliku
404
FILE_NOT_FOUNDNie znaleziono UUID pliku
413
FILE_TOO_LARGEPlik przekracza limit 3 MB
422
PASSWORD_REQUIREDPlik PDF jest chroniony hasłem
422
INVALID_PASSWORDNieprawidłowe hasło PDF
429
RATE_LIMIT_EXCEEDEDZbyt wiele żądań
500
INTERNAL_ERRORBłąd serwera, spróbuj ponownie

Limity szybkości

Użytkownicy anonimowi

10 żądań na minutę

1 strona dziennie

Bez jednoczesnych przesyłań

Uwierzytelnieni użytkownicy

60 żądań na minutę

Oparte na kredytach (zależne od planu)

Do 5 jednoczesnych przesyłań

Nagłówki limitu szybkości: Wszystkie odpowiedzi zawierają nagłówki X-RateLimit-Limit, X-RateLimit-Remaining i X-RateLimit-Reset.

Kompletne przykłady kodu

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);
?>

Potrzebujesz pomocy?

Wsparcie

Nasz zespół wsparcia jest tutaj, aby pomóc Ci w pomyślnej integracji.

Kolekcja Postman

Pobierz naszą kolekcję Postman, aby łatwo przetestować wszystkie punkty końcowe.