Intelligent Document Recognizer (IDR) automaticky konvertuje PDF faktury na strukturované e-faktury. Přes PSB API ovládáte IDR pomocí recognize hooků, prostřednictvím kterých konfigurujete proces rozpoznávání: úroveň kvality, prioritu, extrakční funkce a údaje o stranách. Tento článek popisuje, jak IDR přes API nasadíte.

IDR funguje jako hook v hook systému PSB. Zaregistrujete recognize hook, který reaguje na topik (např. InvoiceReceived). Když přijde PDF dokument přes tento topik, PSB ho automaticky přepošle na IDR k rozpoznání. Po zpracování IDR publikuje výsledek na callback topik.

Hook action pro IDR má následující formát:

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

Úroveň kvality určuje, jak přísně IDR hodnotí výsledek rozpoznání:

Priorita určuje pořadí zpracování ve frontě IDR:

Features aktivují další extrakční možnosti. Více features můžete kombinovat (oddělené čárkou):

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

Pole data obsahuje base64 zakódovaný JSON s údaji o přijímající organizaci. IDR tyto informace používá pro obohacení a validaci výsledku rozpoznání. JSON obsahuje názvy, identifikátory, e-mailovou adresu a adresy organizace.

Příklad JSON před base64 kódování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 vypadá takto:

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

Tento hook zaregistrujte přes Hook endpoint:

POST /api/v1/hook

Nebo zahrňte hook přímo do Enrollment požadavku.

Po zpracování IDR publikuje výsledek na jeden z následujících topiků:

Na tyto topiky nastavte webhook nebo mail hook pro přijímání výsledků. Například:

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

Maximální velikost souboru pro IDR uploady je 15 MB. Soubory větší než 15 MB vrátí chybový kód HTTP 413 (Content Too Large).

IDR podporuje následující typy souborů:

Jiné typy souborů (Word, Excel, HTML) nejsou podporovány a vedou k chybě IDR422 Invalid PDF Content. PDF soubory chráněné heslem nebo DRM generují podobnou chybovou zprávu.

Kompletní IDR proces přes API probíhá ve čtyřech krocích:

1. PDF dokument přijde přes PSB (upload nebo příjem přes Peppol/SFTP/e-mail)
2. Recognize hook odešle dokument na IDR s nakonfigurovanými parametry
3. IDR zpracuje dokument a publikuje výsledek na příslušném callback topiku
4. Rozpoznaný dokument přijmete přes Váš webhook nebo ho stáhnete přes PurchaseInvoice endpointy

Chcete vědět více o hook architektuře PSB? Přečtěte si článek o nastavení a zabezpečení webhooků.