Intelligent Document Recognizer (IDR) automatycznie konwertuje faktury PDF na ustrukturyzowane e-faktury. Przez API PSB steruje się IDR za pomocą recognize hooków, konfigurujących proces rozpoznawania: poziom jakości, priorytet, funkcje ekstrakcji i dane podmiotu. Ten artykuł opisuje, jak wykorzystać IDR przez API.

IDR działa jako hook w systemie hooków PSB. Rejestruje się recognize hook nasłuchujący na topiku (np. InvoiceReceived). Gdy dokument PDF przychodzi przez ten topik, PSB automatycznie przekazuje go do IDR w celu rozpoznania. Po przetworzeniu IDR publikuje wynik na topiku callback.

Akcja hooka dla IDR ma następujący format:

recognize://idr?quality={quality}&priority={priority}&features={features}&data={base64-data}

Poziom jakości określa, jak ściśle IDR ocenia wynik rozpoznawania:

Priorytet określa kolejność przetwarzania w kolejce IDR:

Feature aktywują dodatkowe możliwości ekstrakcji. Można łączyć wiele feature (oddzielonych przecinkami):

Przykład: features=iban,g-account,order-reference

Pole data zawiera JSON zakodowany w base64 z danymi organizacji odbierającej. IDR wykorzystuje te informacje do wzbogacania i walidacji wyniku rozpoznawania. JSON zawiera nazwy, identyfikatory, adres e-mail i adresy organizacji.

Przykład JSON przed kodowaniem base64:

{
  "names": ["Bedrijfsnaam B.V."],
  "identifiers": [
    { "type": "KVK", "value": "12345678" }
  ],
  "email": "facturen@bedrijf.nl",
  "addresses": [
    {
      "street": "Voorbeeldstraat 1",
      "postcode": "1234 AB",
      "city": "Utrecht",
      "country": "NL"
    }
  ]
}

Kompletny recognize hook wygląda następująco:

{
  "action": "recognize://idr?quality=default&priority=medium&features=iban,order-reference&data={base64-encoded-party-details}",
  "topics": ["InvoiceReceived"]
}

Rejestracja tego hooka przez endpoint Hook:

POST /api/v1/hook

Lub włączenie hooka bezpośrednio w żądanie Enrollment.

Po przetworzeniu IDR publikuje wynik na jednym z następujących topików:

Należy skonfigurować webhook lub mailhook na tych topikach, aby otrzymać wynik. Na przykład:

{
  "action": "https://api.bedrijf.nl/idr/callback",
  "topics": ["PurchaseInvoiceRecognized", "PurchaseInvoiceRecognizedError"]
}

Maksymalny rozmiar pliku dla uploadów IDR wynosi 15 MB. Pliki większe niż 15 MB generują kod błędu HTTP 413 (Content Too Large).

IDR obsługuje następujące typy plików:

Inne typy plików (Word, Excel, HTML) nie są obsługiwane i skutkują błędem IDR422 Invalid PDF Content. Pliki PDF zabezpieczone hasłem lub DRM generują podobny komunikat błędu.

Pełny proces IDR przez API przebiega w czterech etapach:

1. Dokument PDF wpływa przez PSB (upload lub odbiór przez Peppol/SFTP/e-mail)
2. Recognize hook przekazuje dokument do IDR ze skonfigurowanymi parametrami
3. IDR przetwarza dokument i publikuje wynik na odpowiednim topiku callback
4. Rozpoznany dokument otrzymuje się przez webhook lub pobiera przez endpointy PurchaseInvoice

Chcą Państwo dowiedzieć się więcej o architekturze hooków PSB? Artykuł o konfiguracji i zabezpieczaniu webhooków.