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

Se puede acceder a los proyectos de Documentos complejos y no estructurados de Extracción y Procesamiento Inteligentes (IXP) 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:

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

Requisitos previos

Antes de llamar a cualquier API de Document Understanding o de Extracción y Procesamiento Inteligentes (IXP), debes tener registrada una aplicación externa en Automation Cloud. Esto proporciona el AppID y el AppSecret que se utilizan para la autenticación de OAuth.

Crear una aplicación externa

1. Ve a Orchestrator a nivel de tenant.
2. Selecciona Gestionar acceso y luego Gestionar cuentas y grupos.
3. En 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 la aplicación.
7. En Recursos, selecciona Añadir ámbitos:

• Selecciona Document Understanding en la lista desplegable Recurso.
• Cambia a la pestaña Ámbitos de la 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 se muestra solo una vez y no se puede recuperar. Puedes generar otro más tarde en la pantalla de edición.

El ID de aplicación se muestra siempre en la página Aplicaciones externas.

Obtener un token de acceso

Usa el ID y el secreto de la aplicación para solicitar un token de OAuth a través del flujo de credenciales de 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 al cabo 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 Admin 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 secreto nuevo.

Principales diferencias

La siguiente tabla muestra las principales diferencias entre los proyectos de Document Understanding y de Extracción y Procesamiento Inteligentes (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 la extracción	Por tag + documentTypeId (recomendado) o extractorId	Por tag + documentTypeId o por extractorId (gpt_ixp_[version])
Control de versiones	Extractores/clasificadores	Etiquetas (preparación o producción)
Modelo de extracción	Especializado o generativo	Solo generativo (GPT-4o o Gemini)
Definición del 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. Descubrir el proyecto y las etiquetas.
2. Digitalizar y extraer (en paralelo).
3. Validar (opcional).

Nota:

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

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

Para los proyectos de Extracción y Procesamiento Inteligentes (IXP), puedes omitir los sondeos sobre el 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) prosiguen de forma concurrente, y el resultado de la extracción solo se devuelve después de que ambas se hayan completado.

Esta es una optimización específica de IXP que no funciona con proyectos clásicos o modernos de Document Understanding, en los que 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 periodo de inactividad entre la digitalización y la extracción, lo que reduce la latencia total.

Paso 1: descubrir 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>'

De la respuesta, apunta el id del proyecto de Extracción y Procesamiento Inteligentes (IXP)

Obtener etiquetas (versiones publicadas)

Las etiquetas corresponden a versiones del modelo publicadas y marcadas como Preparació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: digitalizar el documento

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 de Extracción y Procesamiento Inteligentes (IXP) admite los siguientes enfoques de enrutamiento:

• Basado en etiquetas: enruta por tag y documentTypeId. Se recomienda para los flujos de trabajo de producción o de preparación.
• Basado en ExtractorId - enruta por extractorId con el formato: gpt_ixp_[version]. Por ejemplo, gpt_ixp_67), lo mismo que para los proyectos clásicos o modernos de Document Understanding.

Extracción basada en etiquetas

Utiliza la ruta basada en etiquetas con el documentTypeId de Discovery.

Síncrona (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íncrona (multipágina)

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 sobre 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>'

Sondear hasta que status sea Succeeded o Failed.

Extracción basada en ExtractorId

Utiliza los mismos puntos finales basados en extractores que el Document Understanding clásico o moderno. El ExtractorId para Extracción y Procesamiento Inteligentes (IXP) sigue el formato gpt_ixp_[version], que se ve en la respuesta de Discovery. Síncrona (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íncrona (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 la respuesta de la 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, y los campos individuales son columnas de la tabla. Todos los valores se representan como texto (string), independientemente de su tipo de dato original en Extracción y Procesamiento Inteligentes (IXP):

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

Principales diferencias estructurales de Document Understanding (v1 o v1.1):

• Todos los campos pertenecen a grupos de campos, que aparecen con el tipo Table en la respuesta.
• Incluso los campos de un solo valor se incluyen en una estructura de filas de tabla.
• El array Tables contiene los valores reales de la celda.

API v2

En la 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 real en Extracción y Procesamiento Inteligentes (IXP), como Texto, Número, Fecha, Cantidad Monetaria, en lugar de todo ser 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
                    }
                  ]
                }
              ]
            }
          ]
        }
      ]
    }
  }
}

Principales diferencias clave con la v1:

• FieldType: "FieldGroup" reemplaza a FieldType: "Table".
• El array Tables se elimina. Los grupos de campos se devuelven directamente en Fields.
• Los campos individuales conservan los tipos de datos que tienen en Extracción y Procesamiento Inteligentes (IXP) en lugar de que todos sean cadenas.
• Los FieldIds utilizan la notación de puntos, por ejemplo, Default.Seller.Name).

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

Los proyectos de Extracción y Procesamiento Inteligentes (IXP) exponen las 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 NombreDeEtiqueta, por ejemplo, live se asigna a la etiqueta de producción o de preparació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 pasas 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 de preparación a la que quieres llamar.
• DocumentTypeId: los proyectos de Extracción y Procesamiento Inteligentes (IXP) suelen utilizar un solo 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.