Consumo de modelos por meio da API do Document Understanding

Os projetos de Documentos complexos e não estruturados do IXP são acessíveis por meio da mesma API de framework do Document Understanding. Os projetos do IXP aparecem como ProjectType: "IXP" no Discovery e são compatíveis com pontos de extremidade baseados em tags e pontos de extremidade baseados no extractorId para extração. Documentação relacionada:

• Visão geral da API do Document Understanding
• Criar aplicativo externo para o Document Understanding
• Gerenciando aplicativos externos

Pré-requisitos

Antes de chamar qualquer API do Document Understanding ou do IXP, você precisa de um aplicativo externo registrado no Automation Cloud. Isso fornece o AppID e AppSecret usados para a autenticação do OAuth.

Criação de um aplicativo externo

1. Navegue até o Orchestrator no nível de tenant.
2. Selecione Gerenciar acesso e, em seguida, Gerenciar contas e grupos.
3. No cabeçalho da UiPath Administration , selecione Aplicativos externos.
4. Selecione Adicionar aplicativo.
5. Preencha o Nome do Aplicativo, por exemplo, DU API Client.
6. Selecione Aplicativo confidencial, que é necessário para obter um segredo do aplicativo.
7. Em Recursos, selecione Adicionar escopos:

• Selecione Document Understanding no menu suspenso Recurso .
• Alterne para a guia Escopo(s) do aplicativo .
• Verifique os escopos de que você precisa:
  • Du.Digitization.Api — digitalizar documentos
  • Du.Classification.Api — classificar documentos
  • Du.Extraction.Api — extrair dados
  • Du.Validation.Api — criar tarefas de validação
  • Du.DataDeletion.Api — excluir dados do documento
• Selecione Salvar.

8. Selecione Adicionar para criar o registro.

Observação:

O pop-up Copiar o segredo do aplicativo imediatamente é exibido apenas uma vez e não pode ser recuperado. Você pode gerar um novo posteriormente na tela de edição.

O ID do aplicativo é visível na página Aplicativos externos a qualquer momento.

Como obter um token de acesso

Use o ID do aplicativo e o Segredo do aplicativo para solicitar um token do OAuth por meio do fluxo de credenciais do 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'

Resposta:

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

O token expira após 1 hora. Use-o Authorization: Bearer <token> em todas as chamadas de API subsequentes.

Observação:

Se você perder o Segredo do aplicativo, acesse Admin, depois Aplicativos externos, edite o aplicativo e selecione Gerar novo em Segredo do aplicativo. Atualize todas as integrações com o novo segredo.

Principais diferenças

A tabela a seguir mostra as principais diferenças entre projetos do Document Understanding e IXP:

	Document Understanding (Clássico ou Moderno)	IXP (Extração e Processamento Inteligente)
Tipo de Projeto	Classic ou Modern	IXP
Classificação	Sim	Não (apenas extração)
Roteamento de extração	Por tag + documentTypeId (recomendado) ou extractorId	Por tag + documentTypeId ou por extractorId (gpt_ixp_[version])
Controle de versão	Extratores/classificadores	Tags (preparação, produção)
Modelo de extração	Especialista ou Generativo	Apenas generativo (GPT-4o, Gemini)
Definição de esquema	No projeto ou por meio de prompts	Definido na interface gráfica do IXP (taxonomia)

O fluxo de trabalho do IXP

1. Descubra o projeto e as tags.
2. Digitalizar e extrair (em paralelo).
3. Validar (opcional).

Observação:

Não há etapa de classificação, pois o IXP lida apenas com extrações.

Digitalização e extração paralelas (apenas Extração e Processamento Inteligente (IXP))

Para projetos de Extração e Processamento Inteligente (IXP), você pode ignorar a pesquisa para o resultado da digitalização e iniciar imediatamente a extração após enviar a digitalização. O back-end executa ambas as operações em paralelo. A digitalização e a extração do IXP prosseguem simultaneamente, e o resultado final da extração é retornado apenas após ambas serem concluídas. Essa é uma otimização específica do IXP que não funciona com projetos do Document Understanding Classic ou Modern, onde você deve aguardar a digitalização terminar antes de chamar a extração. O fluxo otimizado:

# 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}

Esse fluxo elimina o tempo ocioso entre a digitalização e a extração, reduzindo a latência total.

Etapa 1: descobrir o projeto do 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>'

A partir da resposta, observe o id do projeto IXP.

Obter tags (versões publicadas)

As tags correspondem às versões do modelo publicadas marcadas como Preparação ou Produção na interface do usuário da Extração e Processamento Inteligente (IXP). Cada tag inclui seus extratores e tipos de documentos associados. Para obter tags, execute o seguinte:

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

Obter tipos de documento

Para obter tipos de documento, execute o seguinte:

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

Etapa 2: digitalizar o documento

Semelhante ao Document Understanding, carregue o arquivo para obter um 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'

Retorna { "documentId": "..." }.

Etapa 3: extrair

A extração do IXP é compatível com as seguintes abordagens de roteamento:

• Baseado em tag - Rota por tag e documentTypeId. Isso é recomendado para fluxos de trabalho de Produção ou de Preparação.
• Baseado em ExtractorId - Rotear por extractorId usando o formato: gpt_ixp_[version]. Por exemplo, gpt_ixp_67), o mesmo que para projetos do Document Understanding Clássico ou Moderno.

Extração baseada em tags

Usa o caminho baseado em tags com o documentTypeId do Discovery.

Síncrono (até 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>" }'

Assíncrono (várias páginas)

Iniciar:

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

Retorna { "operationId": "..." }. Enquete do 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>'

Pesquise até que status seja Succeeded ou Failed.

Extração baseada em ExtractorId

Usa os mesmos pontos de extremidade baseados em extrator que o Document Understanding Clássico ou Moderno. O ExtractorId para IXP segue o formato gpt_ixp_[version], que fica visível na resposta da descoberta. Síncrono (até 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>" }'

Assíncrono (várias páginas):

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

Etapa 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": { }
  }'

Estrutura de resposta da extração do IXP

API v1 ou v1.1

Na v1 e v1.1, os grupos de campos do IXP são mapeados para FieldType: "Table" na resposta, com campos individuais como colunas de tabela. Todos os valores são representados como texto (string), independentemente do tipo de dados de 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 }
              ]
            }
          ]
        }
      ]
    }
  }
}

Principais diferenças estruturados do Document Understanding (v1 ou v1.1):

• Todos os campos pertencem a grupos de campos, que aparecem como tipo Table na resposta.
• Mesmo os campos de valor único são envolvidos em uma estrutura de linhas de tabela.
• A matriz Tables contém os valores das células reais.

API v2

Na v2, os grupos de campos do IXP são mapeados para FieldType: "FieldGroup" em vez de Table. Esse é um mapeamento exato do conceito de grupo de campos do IXP. Cada campo preserva seu tipo de dados de IXP, como Texto, Número, Data, Quantidade Monetária, em vez de representar tudo como strings. Para obter mais detalhes, consulte Migração da API v1 para 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
                    }
                  ]
                }
              ]
            }
          ]
        }
      ]
    }
  }
}

Principais diferenças da v1:

• FieldType: "FieldGroup" substitui FieldType: "Table".
• A matriz Tables é removida. Os grupos de campos são retornados diretamente em Fields.
• Os campos individuais preservam seus tipos de dados de IXP em vez de serem todos strings.
• FieldIds usam notação de ponto, por exemplo, Default.Seller.Name).

Estrutura da resposta à descoberta de Extração e Processamento Inteligente (IXP)

Os projetos do IXP expõem o controle de versão por meio de tags e 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": []
}

O nome da tag, por exemplo, live para o rótulo de Produção ou de Preparação na interface do usuário da Extração e Processamento Inteligente (IXP).

Observação:

• Nenhuma solicitação necessária: ao contrário do extrator/classificador generativo do DU, o esquema de extração do IXP é pré-definido na taxonomia do projeto do IXP. Você não passa prompts na chamada de API.
• Tag = versão do modelo: use a tag que corresponde à versão de Produção ou de Staging que deseja chamar.
• DocumentTypeId: projetos do IXP normalmente usam um único tipo de documento padrão (00000000-0000-0000-0000-000000000000).
• Limites de página: GPT-4o até 50 páginas, Gemini até 500 páginas por chamada.
• Medição: 1 AI Unit por página (plano Flex) ou 0,2 Platform Units por página (Unified Pricing). As solicitações com falha não consomem unidades.
• Retenção de dados: digitalização 7 dias, extração 24 horas.