Intelligent Document Recognizer (IDR) automaticky konvertuje PDF faktúry na štruktúrované e-faktúry. Cez PSB API ovládate IDR pomocou recognize hookov, prostredníctvom ktorých konfigurujete proces rozpoznávania: úroveň kvality, prioritu, extrakčné funkcie a údaje o stranách. Tento článok popisuje, ako IDR cez API nasadíte.

IDR funguje ako hook v hook systéme PSB. Zaregistrujete recognize hook, ktorý reaguje na topik (napr. InvoiceReceived). Keď príde PDF dokument cez tento topik, PSB ho automaticky prepošle na IDR na rozpoznanie. Po spracovaní IDR publikuje výsledok na callback topik.

Hook action pre IDR má nasledujúci formát:

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

Úroveň kvality určuje, ako prísne IDR hodnotí výsledok rozpoznania:

Priorita určuje poradie spracovania vo fronte IDR:

Features aktivujú ďalšie extrakčné možnosti. Viaceré features môžete kombinovať (oddelené čiarkou):

Príklad: features=iban,g-account,order-reference

Pole data obsahuje base64 zakódovaný JSON s údajmi o prijímajúcej organizácii. IDR tieto informácie používa na obohatenie a validáciu výsledku rozpoznania. JSON obsahuje názvy, identifikátory, e-mailovú adresu a adresy organizácie.

Príklad JSON pred base64 kódovaním:

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

Kompletný recognize hook vyzerá takto:

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

Tento hook zaregistrujte cez Hook endpoint:

POST /api/v1/hook

Alebo zahrňte hook priamo do Enrollment požiadavky.

Po spracovaní IDR publikuje výsledok na jeden z nasledujúcich topikov:

Na tieto topiky nastavte webhook alebo mail hook na prijímanie výsledkov. Napríklad:

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

Maximálna veľkosť súboru pre IDR uploady je 15 MB. Súbory väčšie ako 15 MB vrátia chybový kód HTTP 413 (Content Too Large).

IDR podporuje nasledovné typy súborov:

Iné typy súborov (Word, Excel, HTML) nie sú podporované a vedú k chybe IDR422 Invalid PDF Content. PDF súbory chránené heslom alebo DRM generujú podobnú chybovú správu.

Kompletný IDR proces cez API prebieha v štyroch krokoch:

1. PDF dokument príde cez PSB (upload alebo príjem cez Peppol/SFTP/e-mail)
2. Recognize hook odošle dokument na IDR s nakonfigurovanými parametrami
3. IDR spracuje dokument a publikuje výsledok na príslušnom callback topiku
4. Rozpoznaný dokument prijmete cez Váš webhook alebo ho stiahnete cez PurchaseInvoice endpointy

Chcete vedieť viac o hook architektúre PSB? Prečítajte si článok o nastavení a zabezpečení webhookov.