Dokumentacja API

Spis treści

• Przegląd
• Uwierzytelnianie
• Przesyłanie dokumentu
• Pobieranie skanów
• Lista szablonów
• Sprawdzanie salda
• Webhooki
• Kody błędów

Przegląd

• Bazowy adres URL: https://app.dokuscan.com/api/v1
• Odpowiedzi mają format JSON. Wysyłaj nagłówek Accept: application/json, aby błędy również wracały jako JSON.
• Znaczniki czasu mają format ISO 8601.
• Dostęp jest częścią pakietu Business (od 2000 skanów).

Uwierzytelnianie

Klucze API tworzysz w aplikacji w sekcji „API i webhooki” (do 5 kluczy). Klucz jest w pełni widoczny tylko podczas tworzenia. Wysyłaj go w każdym żądaniu jako token Bearer lub w nagłówku X-API-Key.

curl https://app.dokuscan.com/api/v1/account \
  -H "Authorization: Bearer dsk_xxxxxxxx" \
  -H "Accept: application/json"

Jeśli brakuje klucza lub jest nieprawidłowy, API odpowiada kodem 401. Jeśli konto nie ma pakietu Business, odpowiada kodem 403.

Przesyłanie dokumentu

POST /scans tworzy skan. Przetwarzanie odbywa się w tle. Wynik pobierzesz przez GET /scans/{id} lub otrzymasz go przez webhook.

curl -X POST https://app.dokuscan.com/api/v1/scans \
  -H "Authorization: Bearer dsk_xxxxxxxx" \
  -H "Accept: application/json" \
  -F "template_id=12" \
  -F "file=@lieferschein.pdf"

Odpowiedź przy powodzeniu (201):

{
  "id": 4711,
  "status": "uploaded",
  "template_id": 12,
  "filename": "lieferschein.pdf",
  "created_at": "2026-10-18T09:15:00+00:00"
}

Skan zużywa jeden kredyt skanu. Wielostronicowe pliki PDF nie są dzielone przez API; plik liczy się jako jeden skan.

Pobieranie skanów

GET /scans/{id} zwraca jeden skan. GET /scans zwraca listę, od najnowszych, po 25 wpisów na stronę. Filtry: status, template_id. Strona: page.

{
  "id": 4711,
  "status": "completed",
  "filename": "lieferschein.pdf",
  "template_id": 12,
  "confidence": 92,
  "extracted_data": {
    "lieferant": "Baustoffe Huber GmbH",
    "datum": "12.10.2026",
    "rows": [
      { "artikel": "Zement CEM II 25 kg", "menge": 40, "einheit": "Sack" },
      { "artikel": "Kantholz 8x10 cm", "menge": 24, "einheit": "Stk" }
    ]
  },
  "reviewed_data": null,
  "validation_errors": null,
  "is_partial": false,
  "error_message": null,
  "created_at": "2026-10-18T09:15:00+00:00",
  "updated_at": "2026-10-18T09:15:21+00:00"
}

Struktura extracted_data odpowiada polom szablonu: pojedyncze wartości znajdują się pod kluczem pola, wiersze tabeli jako lista pod rows lub pod kluczem pola tabeli. reviewed_data zawiera ręcznie poprawione wartości, jeśli skan był weryfikowany. confidence to wartość od 0 do 100, a is_partial oznacza wynik częściowy.

Lista szablonów

GET /templates zwraca aktywne szablony konta. extraction_mode to scalar, tabular, mixed lub vision.

{
  "data": [
    {
      "id": 12,
      "name": "Lieferschein Huber",
      "extraction_mode": "mixed",
      "usage_count": 58,
      "created_at": "2026-09-20T10:02:11.000000Z"
    }
  ]
}

Sprawdzanie salda

GET /account zwraca pozostałe saldo skanów.

{
  "remaining_scans": 1842,
  "total_scans": 2000,
  "used_scans": 158
}

Webhooki

Webhooki powiadamiają Twoją aplikację, gdy skan zostanie ukończony lub się nie powiedzie. Możesz je utworzyć w aplikacji w sekcji „API i webhooki” lub przez API: GET /webhooks, POST /webhooks (name, url, events), DELETE /webhooks/{id} oraz GET /webhooks/{id}/logs.

• Adres URL musi być publicznie dostępnym adresem HTTPS.
• DokuScan wysyła POST z treścią JSON i czeka do 10 sekund. Każdy status 2xx jest uznawany za sukces.
• Po 10 kolejnych błędach webhook jest automatycznie dezaktywowany.
• Przy tworzeniu webhooka wyświetlany jest sekret. W pełni widoczny jest tylko raz.

Przykładowa treść dla scan.completed:

{
  "event": "scan.completed",
  "timestamp": "2026-10-18T09:15:21+00:00",
  "data": {
    "scan_id": 4711,
    "filename": "lieferschein.pdf",
    "template_id": 12,
    "status": "completed",
    "confidence": 92,
    "extracted_data": { "lieferant": "Baustoffe Huber GmbH", "rows": [] },
    "validation_errors": [],
    "is_partial": false
  }
}

Weryfikacja podpisu

Każde żądanie zawiera nagłówki X-DokuScan-Event i X-DokuScan-Signature. Podpis to sha256= oraz HMAC-SHA256 surowej treści żądania z użyciem Twojego sekretu. Zweryfikuj go przed przetworzeniem treści.

// PHP
$raw = file_get_contents('php://input');
$expected = 'sha256=' . hash_hmac('sha256', $raw, $secret);
if (!hash_equals($expected, $_SERVER['HTTP_X_DOKUSCAN_SIGNATURE'] ?? '')) {
    http_response_code(401);
    exit;
}

// Node.js (Express, raw body)
const crypto = require('crypto');
const expected = 'sha256=' + crypto.createHmac('sha256', secret).update(rawBody).digest('hex');
const valid = crypto.timingSafeEqual(Buffer.from(expected), Buffer.from(req.get('X-DokuScan-Signature') || ''));

Kody błędów

Błędy mają postać {"error": "…"}. Przy 404 i 422 odpowiedź zawiera pole message, a przy 422 dodatkowo errors.

Przejdź do centrum pomocy · Zobacz cennik

Stan: październik 2026