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

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.