L'Intelligent Document Recognizer (IDR) convertit automatiquement les factures PDF en factures électroniques structurées. Via l'API PSB, vous pilotez l'IDR avec des recognize hooks, grâce auxquels vous configurez le processus de reconnaissance : niveau de qualité, priorité, fonctionnalités d'extraction et informations de la partie. Cet article décrit comment utiliser l'IDR via l'API.

L'IDR fonctionne comme un hook dans le système de hooks du PSB. Vous enregistrez un recognize hook qui écoute un topic (par ex. InvoiceReceived). Lorsqu'un document PDF arrive via ce topic, le PSB le transmet automatiquement à l'IDR pour reconnaissance. Après traitement, l'IDR publie le résultat sur un topic de callback.

L'action du hook pour l'IDR a le format suivant :

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

Le niveau de qualité détermine la rigueur avec laquelle l'IDR évalue le résultat de la reconnaissance :

La priorité détermine l'ordre de traitement dans la file d'attente de l'IDR :

Les features activent des capacités d'extraction supplémentaires. Vous pouvez combiner plusieurs features (séparées par des virgules) :

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

Le champ data contient du JSON encodé en base64 avec les informations de l'organisation destinataire. L'IDR utilise ces informations pour enrichir et valider le résultat de la reconnaissance. Le JSON contient les noms, identifiants, adresse e-mail et adresses de l'organisation.

Exemple du JSON avant l'encodage base64 :

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

Lors de la conversion PDF, le nom de l'organisation destinataire dans le XML ne provient pas du texte du PDF. Ce nom provient de la demande de conversion : le nom de l'organisation sur la plateforme (registre du commerce) ou, en cas de pilotage via cette API, le champ names dans les data/détails de la partie décrits ci-dessus. L'IDR utilise cela pour l'enrichissement et la validation et place le résultat dans AccountingCustomerParty. Une différence d'orthographe (par exemple une abréviation comme « Gebr » contre « Gebrs ») se trouve donc dans les données de la partie transmises, pas dans une erreur OCR sur la buyer party.

VAL-003 : message de validation indiquant que la dénomination sur le document diffère du nom dans la demande de conversion. Ce n'est pas une erreur OCR sur la buyer party ; la comparaison porte sur le nom du document par rapport au nom de la demande.

Modifier l'orthographe : il n'existe pas de voie via XML ou un champ de texte libre. La voie correcte : modifiez d'abord le nom au registre du commerce (nom statutaire ou nom commercial), utilisez ensuite Actualiser les données sur la plateforme (choisissez le bon nom dans la liste déroulante en cas de plusieurs noms commerciaux), et en cas de pilotage via cette API, adaptez également le champ names dans la demande de conversion. Voir Modifier l'adresse, le nom ou le logo de votre organisation pour la procédure complète.

Un recognize hook complet se présente comme suit :

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

Enregistrez ce hook via l'endpoint Hook :

POST /api/v1/hook

Ou incluez le hook directement dans une requête Enrollment.

Après traitement, l'IDR publie le résultat sur l'un des topics suivants :

Configurez un webhook ou un mailhook sur ces topics pour recevoir le résultat. Par exemple :

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

La taille maximale de fichier pour les uploads IDR est de 15 Mo. Les fichiers supérieurs à 15 Mo génèrent un code d'erreur HTTP 413 (Content Too Large).

L'IDR prend en charge les types de fichiers suivants :

Les autres types de fichiers (Word, Excel, HTML) ne sont pas pris en charge et génèrent une erreur IDR422 Invalid PDF Content. Les PDF protégés par mot de passe ou par DRM produisent un message d'erreur similaire.

Le processus IDR complet via l'API se déroule en quatre étapes :

1. Un document PDF arrive via le PSB (upload ou réception via Peppol/SFTP/e-mail)
2. Le recognize hook envoie le document à l'IDR avec les paramètres configurés
3. L'IDR traite le document et publie le résultat sur le topic de callback approprié
4. Vous recevez le document reconnu via votre webhook ou vous le récupérez via les endpoints PurchaseInvoice

Vous souhaitez en savoir plus sur l'architecture de hooks du PSB ? Consultez l'article sur la configuration et la sécurisation des webhooks.