Der Intelligent Document Recognizer (IDR) konvertiert PDF-Rechnungen automatisch in strukturierte E-Rechnungen. Über die PSB API steuern Sie den IDR mit Recognize Hooks, mit denen Sie den Erkennungsprozess konfigurieren: Qualitätsstufe, Priorität, Extraktionsfeatures und Parteidaten. Dieser Artikel beschreibt, wie Sie den IDR über die API einsetzen.

Der IDR arbeitet als Hook im PSB-Hook-System. Sie registrieren einen Recognize Hook, der auf ein Topic lauscht (z.B. InvoiceReceived). Wenn ein PDF-Dokument über dieses Topic eingeht, leitet die PSB es automatisch zur Erkennung an den IDR weiter. Nach der Verarbeitung veröffentlicht der IDR das Ergebnis auf einem Callback-Topic.

Die Hook-Action für IDR hat folgendes Format:

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

Die Qualitätsstufe bestimmt, wie streng der IDR das Erkennungsergebnis bewertet:

Die Priorität bestimmt die Verarbeitungsreihenfolge in der IDR-Warteschlange:

Features aktivieren zusätzliche Extraktionsmöglichkeiten. Sie können mehrere Features kombinieren (kommagetrennt):

Beispiel: features=iban,g-account,order-reference

Das data-Feld enthält base64-codiertes JSON mit Angaben der empfangenden Organisation. Der IDR verwendet diese Informationen, um das Erkennungsergebnis anzureichern und zu validieren. Das JSON enthält Namen, Identifikatoren, E-Mail-Adresse und Adressen der Organisation.

Beispiel des JSON vor der Base64-Codierung:

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

Bei der PDF-Konvertierung stammt der Name der empfangenden Organisation in der XML nicht aus dem Text auf der PDF. Dieser Name stammt aus der Konvertierungsanfrage: dem Plattform-Organisationsnamen (aus dem Handelsregister) oder, bei Ansteuerung über diese API, aus dem Feld names in den oben beschriebenen data/Parteidaten. Die IDR nutzt dies zur Anreicherung und Validierung und setzt das Ergebnis in AccountingCustomerParty. Ein Schreibweise-Unterschied (zum Beispiel eine Abkürzung wie "Gebr" gegenüber "Gebrs") liegt somit in den mitgesendeten Parteidaten, nicht in einem OCR-Fehler bei der Buyer Party.

VAL-003: Validierungsmeldung, dass die Namensangabe auf dem Dokument von dem Namen in der Konvertierungsanfrage abweicht. Dies ist kein OCR-Fehler bei der Buyer Party; der Vergleich betrifft den Dokumentnamen gegenüber dem Request-Namen.

Schreibweise ändern: Es gibt keine Route über XML oder ein Freitextfeld. Der richtige Weg: Ändern Sie den Namen zuerst im Handelsregister (Firmenname oder Handelsname), verwenden Sie danach auf der Plattform Daten aktualisieren (bei mehreren Handelsnamen die richtige im Dropdown wählen) und passen Sie bei Ansteuerung über diese API auch das Feld names in der Konvertierungsanfrage an. Siehe Adressdaten, Name oder Logo Ihrer Organisation ändern für die vollständige Vorgehensweise.

Ein vollständiger Recognize Hook sieht so aus:

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

Registrieren Sie diesen Hook über den Hook-Endpoint:

POST /api/v1/hook

Oder nehmen Sie den Hook direkt in einen Enrollment-Request auf.

Nach der Verarbeitung veröffentlicht der IDR das Ergebnis auf einem der folgenden Topics:

Richten Sie einen Webhook oder Mailhook auf diese Topics ein, um das Ergebnis zu empfangen. Zum Beispiel:

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

Die maximale Dateigröße für IDR-Uploads beträgt 15 MB. Dateien größer als 15 MB geben einen HTTP 413 (Content Too Large) Fehlercode zurück.

Der IDR unterstützt die folgenden Dateitypen:

Andere Dateitypen (Word, Excel, HTML) werden nicht unterstützt und führen zu einem IDR422 Invalid PDF Content-Fehler. Passwortgeschützte oder DRM-geschützte PDFs erzeugen eine vergleichbare Fehlermeldung.

Der vollständige IDR-Prozess über die API verläuft in vier Schritten:

1. Ein PDF-Dokument geht über die PSB ein (Upload oder Empfang über Peppol/SFTP/E-Mail)
2. Der Recognize Hook sendet das Dokument mit den konfigurierten Parametern an den IDR
3. Der IDR verarbeitet das Dokument und veröffentlicht das Ergebnis auf dem entsprechenden Callback-Topic
4. Sie empfangen das erkannte Dokument über Ihren Webhook oder rufen es über die PurchaseInvoice-Endpoints ab

Möchten Sie mehr über die PSB-Hook-Architektur erfahren? Lesen Sie den Artikel über Webhooks einrichten und absichern.