De Intelligent Document Recognizer (IDR) converteert PDF-facturen automatisch naar gestructureerde e-facturen. Via de PSB API stuur je de IDR aan met recognize hooks, waarmee je het herkenningsproces configureert: kwaliteitsniveau, prioriteit, extractiefeatures en partijgegevens. Dit artikel beschrijft hoe je de IDR via de API inzet.

De IDR werkt als een hook in het PSB hook-systeem. Je registreert een recognize hook die luistert op een topic (bijv. InvoiceReceived). Wanneer een PDF-document binnenkomt via dat topic, stuurt de PSB het automatisch door naar de IDR voor herkenning. Na verwerking publiceert de IDR het resultaat op een callback-topic.

De hook-action voor IDR heeft het volgende formaat:

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

Het kwaliteitsniveau bepaalt hoe streng de IDR het herkenningsresultaat beoordeelt:

De prioriteit bepaalt de verwerkingsvolgorde in de IDR-queue:

Features activeren extra extractiemogelijkheden. Je kunt meerdere features combineren (komma-gescheiden):

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

Het data-veld bevat base64-encoded JSON met gegevens van de ontvangende organisatie. De IDR gebruikt deze informatie om het herkenningsresultaat te verrijken en te valideren. De JSON bevat namen, identifiers, e-mailadres en adressen van de organisatie.

Voorbeeld van de JSON vóór base64-encoding:

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

Een complete recognize hook ziet er zo uit:

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

Registreer deze hook via het Hook endpoint:

POST /api/v1/hook

Of neem de hook direct op in een Enrollment-request.

Na verwerking publiceert de IDR het resultaat op een van de volgende topics:

Stel een webhook of mailhook in op deze topics om het resultaat te ontvangen. Bijvoorbeeld:

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

De maximale bestandsgrootte voor IDR-uploads is 15 MB. Bestanden groter dan 15 MB geven een HTTP 413 (Content Too Large) foutcode.

De IDR ondersteunt de volgende bestandstypen:

Andere bestandstypen (Word, Excel, HTML) worden niet ondersteund en resulteren in een IDR422 Invalid PDF Content-fout. Beveiligde PDF's met wachtwoordbeveiliging of DRM geven een vergelijkbare foutmelding.

Het volledige IDR-proces via de API verloopt in vier stappen:

1. Een PDF-document komt binnen via de PSB (upload of ontvangst via Peppol/SFTP/e-mail)
2. De recognize hook stuurt het document naar de IDR met de geconfigureerde parameters
3. De IDR verwerkt het document en publiceert het resultaat op het juiste callback-topic
4. Je ontvangt het herkende document via je webhook of haalt het op via de PurchaseInvoice-endpoints

Meer weten over de PSB hook-architectuur? Lees het artikel over webhooks instellen en beveiligen.