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

Pri konverzii PDF názov prijímajúcej organizácie v XML nepochádza z textu na PDF. Tento názov pochádza z konverznej žiadosti: názvu organizácie na platforme (obchodný register) alebo, pri riadenom prístupe cez toto API, z poľíčka names v vyššie popísaných data/údajoch o strane. IDR to využíva na obohatenie a validáciu a výsledok vkladá do AccountingCustomerParty. Rozdiel v pravopise (napríklad skratka "Gebr" oproti "Gebrs") tak leží v zaslaných údajoch o strane, nie v chybe OCR na buyer party.

VAL-003: validačná správa označujúca, že názov na dokumente sa líši od názvu v konverznej žiadosti. Nejde o chybu OCR na buyer party; porovnanie sa týka názvu dokumentu oproti názvu zo žiadosti.

Zmena pravopisu názvu: neexistuje cesta cez XML alebo textové pole. Správna cesta: najprv zmeňte názov v obchodnom registri (štatutárny názov alebo obchodný názov), potom na platforme použite Obnoviť údaje (pri viacerých obchodných názvoch vyberte správny z rozbaľovacieho zoznamu) a pri riadenom prístupe cez toto API aktualizujte aj pole names v konverznej žiadosti. Postup pozri Zmena adresy, názvu alebo loga vašej organizácie.

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.