Consumir modelos a través de la API de Document Understanding

Los proyectos de Documentos complejos y no estructurados de Extracción y Procesamiento Inteligentes (IXP) son accesibles a través de la misma API del marco de Document Understanding. Los proyectos de Extracción y Procesamiento Inteligentes (IXP) aparecen como ProjectType: "IXP" en Discovery y admiten tanto puntos finales basados en etiquetas como puntos finales basados en extractorId para la extracción. Documentación relacionada:

• Descripción general de la API de Document Understanding
• Crear una aplicación externa para Document Understanding
• Administrar aplicaciones externas

Requisitos previos

Antes de llamar a cualquier API de Document Understanding o Extracción y Procesamiento Inteligentes (IXP), necesitas una aplicación externa registrada en Automation Cloud. Esto proporciona los AppID y AppSecret utilizados para la autenticación OAuth.

Crear una aplicación externa

1. Navega a Orchestrator en el nivel de tenant.
2. Selecciona Gestionar acceso y luego Gestionar cuentas y grupos.
3. Desde el encabezado Administración de UiPath , selecciona Aplicaciones externas.
4. Selecciona Añadir aplicación.
5. Rellena el Nombre de la aplicación, por ejemplo, DU API Client.
6. Selecciona Aplicación confidencial, que es necesaria para obtener un secreto de aplicación.
7. En Recursos, selecciona Añadir ámbitos:

• Selecciona Document Understanding en el menú desplegable Recurso .
• Cambia a la pestaña Ámbitos de aplicación .
• Marca los ámbitos que necesitas:
  • Du.Digitization.Api — digitalizar documentos
  • Du.Classification.Api — clasificar documentos
  • Du.Extraction.Api — extraer datos
  • Du.Validation.Api — crear tareas de validación
  • Du.DataDeletion.Api — eliminar datos del documento
• Selecciona Guardar.

8. Selecciona Añadir para crear el registro.

Nota:

La ventana emergente Copiar el secreto de la aplicación inmediatamente solo se muestra una vez y no se puede recuperar. Puedes generar uno nuevo más tarde desde la pantalla de edición.

El ID de la aplicación es visible en la página Aplicaciones externas en cualquier momento.

Obtener un token de acceso

Utiliza el ID de la aplicación y el Secreto de la aplicación para solicitar un token OAuth a través del flujo de credenciales del cliente:

curl -X POST 'https://cloud.uipath.com/identity_/connect/token' \
  -d 'grant_type=client_credentials' \
  -d 'client_id=<APP_ID>' \
  -d 'client_secret=<APP_SECRET>' \
  -d 'scope=Du.Digitization.Api Du.Extraction.Api'

Respuesta:

{
  "access_token": "eyJh...CRaKrg",
  "expires_in": 3600,
  "token_type": "Bearer",
  "scope": "Du.Digitization.Api Du.Extraction.Api"
}

El token caduca después de 1 hora. Úsalo como Authorization: Bearer <token> en todas las llamadas a la API posteriores.

Nota:

Si pierdes el secreto de la aplicación, ve a Administrador y luego a Aplicaciones externas, edita la aplicación y selecciona Generar nuevo en Secreto de la aplicación. Actualiza todas las integraciones con el nuevo secreto.

Diferencias clave

La siguiente tabla muestra las diferencias clave entre los proyectos de Document Understanding y IXP:

	Document Understanding (clásico o moderno)	IXP (Extracción y Procesamiento Inteligentes)
Tipo de proyecto	Classic o Modern	IXP
Clasificación	Sí	No (solo extracción)
Enrutamiento de extracción	Por tag + documentTypeId (recomendado) o extractorId	Por tag + documentTypeId o por extractorId (gpt_ixp_[version])
Control de versiones	Extractores/clasificadores	Etiquetas (escenario, producción)
Modelo de extracción	Especializado o Generativo	Solo generativo (GPT-4o, Gemini)
Definición de esquema	En el proyecto o a través de solicitudes	Definido en la IU de Extracción y Procesamiento Inteligentes (IXP) (taxonomía)

El flujo de trabajo de Extracción y Procesamiento Inteligentes (IXP)

1. Descubre proyectos y etiquetas.
2. Digitalizar y extraer (en paralelo).
3. Validar (opcional).

Nota:

No hay paso de clasificación, ya que Extracción y Procesamiento Inteligentes (IXP) solo maneja extracciones.

Digitalización y extracción en paralelo (solo Extracción y Procesamiento Inteligentes (IXP))

Para proyectos de Extracción y Procesamiento Inteligentes (IXP), puedes omitir el sondeo del resultado de la digitalización e iniciar inmediatamente la extracción después de enviar la digitalización. El backend ejecuta ambas operaciones en paralelo. La digitalización y la extracción de Extracción y Procesamiento Inteligentes (IXP) proceden de forma simultánea, y el resultado final de la extracción solo se devuelve después de que ambas se completen. Esta es una optimización específica de Extracción y Procesamiento Inteligentes (IXP) que no funciona con proyectos de Document Understanding clásico o moderno, donde debes esperar a que finalice la digitalización antes de llamar a la extracción. El flujo optimizado:

# 1. Start digitization (fire and forget — do not poll for result).
POST /projects/{projectId}/digitization/start
# → returns { "documentId": "..." }
# 2. Immediately start extraction with the documentId (no need to wait).
POST /projects/{projectId}/{tag}/document-types/{documentTypeId}/extraction/start
# → returns { "operationId": "..." }
# 3. Poll extraction result only — it waits for both digitization and extraction.
GET /projects/{projectId}/{tag}/document-types/{documentTypeId}/extraction/result/{operationId}

Este flujo elimina el tiempo de inactividad entre la digitalización y la extracción, reduciendo la latencia total.

Paso 1: descubre el proyecto de Extracción y Procesamiento Inteligentes (IXP)

# List all projects — filter for type "IXP"
curl -X GET \
  'https://cloud.uipath.com/<Org>/<Tenant>/du_/api/framework/projects?api-version=1' \
  -H 'Authorization: Bearer <TOKEN>'

En la respuesta, ten en cuenta el id del proyecto de Extracción y Procesamiento Inteligentes (IXP).

Obtener etiquetas (versiones publicadas)

Las etiquetas corresponden a versiones de modelo publicadas marcadas como Clasificación o Producción en la interfaz de usuario de Extracción y Procesamiento Inteligentes (IXP). Cada etiqueta incluye sus extractores y tipos de documentos asociados. Para obtener etiquetas, ejecuta lo siguiente:

curl -X GET \
  'https://cloud.uipath.com/<Org>/<Tenant>/du_/api/framework/projects/<ProjectID>/tags?api-version=1' \
  -H 'Authorization: Bearer <TOKEN>'

Obtener tipos de documentos

Para obtener tipos de documentos, ejecuta lo siguiente:

curl -X GET \
  'https://cloud.uipath.com/<Org>/<Tenant>/du_/api/framework/projects/<ProjectID>/document-types?api-version=1' \
  -H 'Authorization: Bearer <TOKEN>'

Paso 2: digitaliza el documento

De forma similar a Document Understanding, carga el archivo para obtener un documentId:

curl -X POST \
  'https://cloud.uipath.com/<Org>/<Tenant>/du_/api/framework/projects/<ProjectID>/digitization/start?api-version=1' \
  -H 'Authorization: Bearer <TOKEN>' \
  -H 'Content-Type: multipart/form-data' \
  -F 'file=@document.pdf;type=application/pdf'

Devuelve { "documentId": "..." }.

Paso 3: Extraer

La extracción IXP admite los siguientes enfoques de enrutamiento:

• Basado en etiquetas : enrutar por tag y documentTypeId. Esto se recomienda para flujos de trabajo de producción o preparación.
• Basado en ExtractorId : enrutar por extractorId utilizando el formato: gpt_ixp_[version]. Por ejemplo, gpt_ixp_67), lo mismo que para los proyectos de Document Understanding clásico o moderno.

Extracción basada en etiquetas

Utiliza la ruta basada en etiquetas con documentTypeId de Discovery.

Síncrono (hasta 5 páginas)

curl -X POST \
  'https://cloud.uipath.com/<Org>/<Tenant>/du_/api/framework/projects/<ProjectID>/<Tag>/document-types/<DocumentTypeId>/extraction?api-version=1' \
  -H 'Authorization: Bearer <TOKEN>' \
  -H 'Content-Type: application/json' \
  -d '{ "documentId": "<documentId>" }'

Asíncrono (varias páginas)

Inicio:

curl -X POST \
  'https://cloud.uipath.com/<Org>/<Tenant>/du_/api/framework/projects/<ProjectID>/<Tag>/document-types/<DocumentTypeId>/extraction/start?api-version=1' \
  -H 'Authorization: Bearer <TOKEN>' \
  -H 'Content-Type: application/json' \
  -d '{ "documentId": "<documentId>" }'

Devuelve { "operationId": "..." }. Sondeo para el resultado:

curl -X GET \
  'https://cloud.uipath.com/<Org>/<Tenant>/du_/api/framework/projects/<ProjectID>/<Tag>/document-types/<DocumentTypeId>/extraction/result/<operationId>?api-version=1' \
  -H 'Authorization: Bearer <TOKEN>'

Sondee hasta que status sea Succeeded o Failed.

Extracción basada en ExtractorId

Utiliza los mismos puntos finales basados en extractores que Document Understanding clásico o moderno. El ExtractorId para Extracción y Procesamiento Inteligentes (IXP) sigue el formato gpt_ixp_[version], que es visible en la respuesta de descubrimiento. Síncrono (hasta 5 páginas):

curl -X POST \
  'https://cloud.uipath.com/<Org>/<Tenant>/du_/api/framework/projects/<ProjectID>/extractors/<ExtractorId>/extraction?api-version=1' \
  -H 'Authorization: Bearer <TOKEN>' \
  -H 'Content-Type: application/json' \
  -d '{ "documentId": "<documentId>" }'

Asíncrono (multipágina):

curl -X POST \
  'https://cloud.uipath.com/<Org>/<Tenant>/du_/api/framework/projects/<ProjectID>/extractors/<ExtractorId>/extraction/start?api-version=1' \
  -H 'Authorization: Bearer <TOKEN>' \
  -H 'Content-Type: application/json' \
  -d '{ "documentId": "<documentId>" }'

Paso 4: Validar (opcional)

curl -X POST \
  'https://cloud.uipath.com/<Org>/<Tenant>/du_/api/framework/projects/<ProjectID>/<Tag>/document-types/<DocumentTypeId>/validation/start?api-version=1' \
  -H 'Authorization: Bearer <TOKEN>' \
  -H 'Content-Type: application/json' \
  -d '{
    "documentId": "<documentId>",
    "actionTitle": "Review IXP extraction",
    "actionPriority": "Medium",
    "actionCatalog": "default_du_actions",
    "actionFolder": "Shared",
    "storageBucketName": "du_storage_bucket",
    "storageBucketDirectoryPath": "du_storage_bucket",
    "extractionResult": { }
  }'

Estructura de respuesta de extracción de Extracción y Procesamiento Inteligentes (IXP)

API v1 o v1.1

En v1 y v1.1, los grupos de campos de Extracción y Procesamiento Inteligentes (IXP) se asignan a FieldType: "Table" en la respuesta, con campos individuales como columnas de la tabla. Todos los valores se representan como texto (cadena), independientemente de su tipo de datos de Extracción y Procesamiento Inteligentes (IXP) original:

{
  "extractionResult": {
    "DocumentId": "...",
    "ResultsDocument": {
      "DocumentTypeId": "00000000-0000-0000-0000-000000000000",
      "DocumentTypeName": "Default",
      "Fields": [
        {
          "FieldId": "Fleet member transaction details",
          "FieldName": "Fleet member transaction details",
          "FieldType": "Table",
          "Values": []
        }
      ],
      "Tables": [
        {
          "FieldId": "Fleet member transaction details",
          "FieldName": "Fleet member transaction details",
          "Values": [
            {
              "Cells": [
                { "FieldId": "Fleet Code", "Value": "FL-7892", "Confidence": 0.95 },
                { "FieldId": "Fuel type", "Value": "Diesel", "Confidence": 0.97 }
              ]
            }
          ]
        }
      ]
    }
  }
}

Diferencias estructurales clave con Document Understanding (v1 o v1.1):

• Todos los campos pertenecen a grupos de campos, que aparecen como tipo Table en la respuesta.
• Incluso los campos de valor único se envuelven en una estructura de fila de tabla.
• La matriz Tables contiene los valores reales de las celdas.

API v2

En v2, los grupos de campos de Extracción y Procesamiento Inteligentes (IXP) se asignan a FieldType: "FieldGroup" en lugar de a Table. Esta es una asignación exacta del concepto de grupo de campos de Extracción y Procesamiento Inteligentes (IXP). Cada campo conserva su tipo de datos de Extracción y Procesamiento Inteligentes (IXP) real, como Texto, Número, Fecha, Cantidad Monetaria, en lugar de representar todo como cadenas. Para obtener más información, consulta Migrar de la API v1 a v2 .

{
  "extractionResult": {
    "ResultsDocument": {
      "Fields": [
        {
          "FieldId": "Default.Seller",
          "FieldName": "Seller",
          "FieldType": "FieldGroup",
          "IsMissing": false,
          "DataSource": "Automatic",
          "Values": [
            {
              "Components": [
                {
                  "FieldId": "Default.Seller.Name",
                  "FieldName": "Name",
                  "FieldType": "Text",
                  "Values": [
                    {
                      "Value": "John Doe",
                      "Confidence": 0.9999834
                    }
                  ]
                }
              ]
            }
          ]
        }
      ]
    }
  }
}

Diferencias clave con respecto a v1:

• FieldType: "FieldGroup" reemplaza FieldType: "Table".
• Se elimina la matriz Tables . Los grupos de campos se devuelven directamente en Fields.
• Los campos individuales conservan sus tipos de datos de Extracción y Procesamiento Inteligentes (IXP) en lugar de ser cadenas.
• Los IDDeCampo utilizan la notación de puntos, por ejemplo, Default.Seller.Name).

Estructura de respuesta de descubrimiento de Extracción y Procesamiento Inteligentes (IXP)

Los proyectos de Extracción y Procesamiento Inteligentes (IXP) exponen el control de versiones a través de etiquetas y projectVersions:

{
  "id": "044fedbc-40a6-8078-8f06-02a0d362ab44",
  "name": "Transcom Invoices - Andras",
  "type": "IXP",
  "properties": ["SupportsTags", "SupportsVersions"],
  "extractors": [
    {
      "id": "gpt_ixp_67",
      "documentTypeId": "00000000-0000-0000-0000-000000000000",
      "projectVersion": 67
    }
  ],
  "projectVersions": [
    { "version": 67, "tag": "live", "deployed": true }
  ],
  "classifiers": []
}

El nombre de la etiqueta, por ejemplo, live se asigna a la etiqueta Producción o Clasificación en la interfaz de usuario de Extracción y Procesamiento Inteligentes (IXP).

Nota:

• No se necesitan solicitudes: a diferencia del extractor/clasificador generativo de DU, el esquema de extracción de Extracción y Procesamiento Inteligentes (IXP) está predefinido en la taxonomía del proyecto de Extracción y Procesamiento Inteligentes (IXP). No transmite prompts en la llamada a la API.
• Etiqueta = versión del modelo: utiliza la etiqueta que corresponde a la versión de producción o clasificación a la que deseas llamar.
• DocumentTypeId: los proyectos de Extracción y Procesamiento Inteligentes (IXP) suelen utilizar un único tipo de documento predeterminado (00000000-0000-0000-0000-000000000000).
• Límites de páginas: GPT-4o hasta 50 páginas, Gemini hasta 500 páginas por llamada.
• Medición: 1 AI Unit por página (plan Flex) o 0,2 Platform Units por página (Unified Pricing). Las solicitudes fallidas no consumen unidades.
• Retención de datos: digitalización 7 días, extracción 24 horas.