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

Durante la conversione PDF, il nome dell'organizzazione destinataria nell'XML non proviene dal testo del PDF. Tale nome proviene dalla richiesta di conversione: il nome dell'organizzazione sulla piattaforma (registro delle imprese) oppure, se si utilizza questa API, il campo names nei data/dettagli della parte descritti sopra. L'IDR utilizza questo per l'arricchimento e la validazione e inserisce il risultato in AccountingCustomerParty. Una differenza di ortografia (per esempio un'abbreviazione come "Gebr" invece di "Gebrs") si trova quindi nei dati della parte inviati, non in un errore OCR sulla buyer party.

VAL-003: messaggio di validazione che indica che la denominazione sul documento differisce dal nome nella richiesta di conversione. Non è un errore OCR sulla buyer party; il confronto riguarda il nome del documento rispetto al nome della richiesta.

Modificare l'ortografia: non esiste un percorso tramite XML o un campo di testo libero. Il percorso corretto: modificare prima il nome nel registro delle imprese (denominazione statutaria o nome commerciale), poi utilizzare Aggiorna dati sulla piattaforma (selezionare il nome corretto dal menu a discesa in caso di più nomi commerciali) e, se si utilizza questa API, aggiornare anche il campo names nella richiesta di conversione. Vedere Modificare l'indirizzo, il nome o il logo della propria organizzazione per la procedura completa.

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.