PDF-facturen automatisch laten herkennen en converteren naar e-facturen via recognize hooks.
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:
defaulthqlqDe prioriteit bepaalt de verwerkingsvolgorde in de IDR-queue:
highmediumlowFeatures activeren extra extractiemogelijkheden. Je kunt meerdere features combineren (komma-gescheiden):
ibang-accountorder-referenceproject-referencecontract-referenceVoorbeeld: 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": "[email protected]",
"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:
PurchaseInvoiceRecognizedPurchaseInvoiceRecognizedPendingPurchaseInvoiceRecognizedRejectedPurchaseInvoiceRecognizedErrorStel 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:
Naast PDF ondersteunt de IDR ook JPEG, PNG en TIFF (multi-page scans). Andere bestandstypen zoals Word, Excel of HTML worden niet ondersteund en resulteren in een foutmelding. Beveiligde PDF's met wachtwoordbeveiliging of DRM worden eveneens afgewezen.
Na verwerking publiceert de IDR het resultaat op een callback-topic. Bij succesvolle herkenning verschijnt het op PurchaseInvoiceRecognized. Stel een webhook of mailhook in op dit topic om het resultaat automatisch te ontvangen. Bij fouten verschijnt het op PurchaseInvoiceRecognizedError.
De maximale bestandsgrootte is 15 MB. Bestanden groter dan 15 MB geven een HTTP 413 (Content Too Large) foutcode. Zorg ervoor dat gescande documenten geoptimaliseerd zijn qua bestandsgrootte, bijvoorbeeld door de resolutie te verlagen als die onnodig hoog is.
Meer weten over de PSB hook-architectuur? Lees het artikel over webhooks instellen en beveiligen.
Open de API-referentie