L'Intelligent Document Recognizer (IDR) converte automaticamente fatture PDF in e-fatture strutturate. Tramite l'API PSB si controlla l'IDR con recognize hook, con cui configurare il processo di riconoscimento: livello di qualità, priorità, funzionalità di estrazione e dati della parte. Questo articolo descrive come utilizzare l'IDR tramite l'API.

L'IDR funziona come un hook nel sistema hook della PSB. Si registra un recognize hook che ascolta su un topic (ad es. InvoiceReceived). Quando un documento PDF arriva tramite quel topic, la PSB lo inoltra automaticamente all'IDR per il riconoscimento. Dopo l'elaborazione, l'IDR pubblica il risultato su un topic di callback.

L'action dell'hook per l'IDR ha il seguente formato:

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

Il livello di qualità determina quanto rigorosamente l'IDR valuta il risultato del riconoscimento:

La priorità determina l'ordine di elaborazione nella coda IDR:

Le feature attivano funzionalità di estrazione aggiuntive. È possibile combinare più feature (separate da virgola):

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

Il campo data contiene JSON codificato in base64 con i dati dell'organizzazione ricevente. L'IDR utilizza queste informazioni per arricchire e validare il risultato del riconoscimento. Il JSON contiene nomi, identificativi, indirizzo e-mail e indirizzi dell'organizzazione.

Esempio del JSON prima della codifica 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 completo si presenta così:

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

Registrare questo hook tramite l'endpoint Hook:

POST /api/v1/hook

Oppure includere l'hook direttamente in una richiesta Enrollment.

Dopo l'elaborazione, l'IDR pubblica il risultato su uno dei seguenti topic:

Configurare un webhook o un mailhook su questi topic per ricevere il risultato. Ad esempio:

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

La dimensione massima del file per gli upload IDR è 15 MB. File superiori a 15 MB generano un codice errore HTTP 413 (Content Too Large).

L'IDR supporta i seguenti tipi di file:

Altri tipi di file (Word, Excel, HTML) non sono supportati e generano un errore IDR422 Invalid PDF Content. I PDF protetti da password o DRM producono un messaggio di errore simile.

L'intero processo IDR tramite l'API si svolge in quattro fasi:

1. Un documento PDF arriva tramite la PSB (upload o ricezione via Peppol/SFTP/e-mail)
2. Il recognize hook inoltra il documento all'IDR con i parametri configurati
3. L'IDR elabora il documento e pubblica il risultato sul topic di callback appropriato
4. Si riceve il documento riconosciuto tramite il webhook oppure lo si recupera tramite gli endpoint PurchaseInvoice

Desidera saperne di più sull'architettura hook della PSB? Legga l'articolo su configurare e proteggere i webhook.