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

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.