El Intelligent Document Recognizer (IDR) convierte automáticamente facturas PDF en facturas electrónicas estructuradas. A través de la API de la PSB, usted controla el IDR mediante recognize hooks, con los que configura el proceso de reconocimiento: nivel de calidad, prioridad, funciones de extracción y datos de la parte. Este artículo describe cómo utilizar el IDR a través de la API.

El IDR funciona como un hook en el sistema de hooks de la PSB. Usted registra un recognize hook que escucha un topic (por ejemplo, InvoiceReceived). Cuando un documento PDF llega a través de ese topic, la PSB lo envía automáticamente al IDR para su reconocimiento. Tras el procesamiento, el IDR publica el resultado en un topic de callback.

La hook-action para IDR tiene el siguiente formato:

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

El nivel de calidad determina con qué rigor el IDR evalúa el resultado del reconocimiento:

La prioridad determina el orden de procesamiento en la cola del IDR:

Las features activan capacidades de extracción adicionales. Puede combinar múltiples features (separadas por comas):

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

El campo data contiene JSON codificado en base64 con los datos de la organización receptora. El IDR utiliza esta información para enriquecer y validar el resultado del reconocimiento. El JSON contiene nombres, identificadores, dirección de correo electrónico y direcciones de la organización.

Ejemplo del JSON antes de la codificación en 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 conversión de PDF, el nombre de la organización receptora en el XML no proviene del texto del PDF. Ese nombre proviene de la solicitud de conversión: el nombre de la organización en la plataforma (registro mercantil) o, al utilizar esta API, el campo names en los data/detalles de la parte descritos arriba. El IDR utiliza esto para el enriquecimiento y la validación y coloca el resultado en AccountingCustomerParty. Una diferencia de ortografía (por ejemplo, una abreviatura como "Gebr" frente a "Gebrs") se encuentra por tanto en los datos de la parte enviados, no en un error de OCR en la buyer party.

VAL-003: mensaje de validación que indica que la denominación en el documento difiere del nombre en la solicitud de conversión. No es un error de OCR en la buyer party; la comparación se refiere al nombre del documento frente al nombre de la solicitud.

Cambiar la ortografía: no existe una vía mediante XML o un campo de texto libre. La vía correcta: cambie primero el nombre en el registro mercantil (nombre estatutario o nombre comercial), luego use Actualizar datos en la plataforma (seleccione el nombre correcto en el desplegable si hay varios nombres comerciales) y, al utilizar esta API, actualice también el campo names en la solicitud de conversión. Consulte Cambiar la dirección, el nombre o el logotipo de su organización para el procedimiento completo.

Un recognize hook completo tiene el siguiente aspecto:

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

Registre este hook a través del endpoint de Hook:

POST /api/v1/hook

O inclúyalo directamente en una solicitud de Enrollment.

Tras el procesamiento, el IDR publica el resultado en uno de los siguientes topics:

Configure un webhook o mailhook para estos topics para recibir el resultado. Por ejemplo:

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

El tamaño máximo de archivo para uploads al IDR es de 15 MB. Los archivos mayores de 15 MB devuelven un código de error HTTP 413 (Content Too Large).

El IDR admite los siguientes tipos de archivo:

Otros tipos de archivo (Word, Excel, HTML) no son compatibles y generan un error IDR422 Invalid PDF Content. Los PDF protegidos con contraseña o DRM producen un mensaje de error similar.

El proceso completo del IDR a través de la API se realiza en cuatro pasos:

1. Un documento PDF llega a través de la PSB (carga o recepción a través de Peppol/SFTP/correo electrónico)
2. El recognize hook envía el documento al IDR con los parámetros configurados
3. El IDR procesa el documento y publica el resultado en el topic de callback correspondiente
4. Usted recibe el documento reconocido a través de su webhook o lo obtiene a través de los endpoints de PurchaseInvoice

¿Desea saber más sobre la arquitectura de hooks de la PSB? Lea el artículo sobre configurar y proteger webhooks.