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 estrutura 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 em 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 da Extração e Processamento Inteligente (IXP), você precisa de um aplicativo externo registrado no Automation Cloud.Isso fornece o AppID e o AppSecret que você usa para a autenticação OAuth.

Criação de um aplicativo externo.

1. Navegue até o Orchestrator no nível de tenant.
2. Selecione Gerenciar acesso, em seguida, Gerenciar contas e grupos.
3. No cabeçalho Administração da UiPath, selecione Aplicativos externos.
4. Selecione Adicionar aplicativo.
5. Preencha o Nome do aplicativo, por exemplo, DU API Client.
6. Selecione Aplicativo confidencial, 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 você não poderá recuperá-lo.Você pode gerar um novo mais tarde a partir da tela de edição.

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

Obtenção de um token de acesso

Use a ID do Aplicativo e o Segredo do aplicativo para solicitar um token 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 como Authorization: Bearer <token> em todas as chamadas de API subsequentes.

Observação:

Se você perder o Segredo do aplicativo, acesse Admin e, em seguida, 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 Document Understanding e da Extração e Processamento Inteligente (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 da 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	Especializado ou Generativo	Apenas generativo (GPT-4o, Gemini)
Definição de esquema	No projeto ou por meio de solicitações	Definido na interface gráfica do Extração e Processamento Inteligente (IXP) (da taxonomia)

O fluxo de trabalho da Extração e Processamento Inteligente (IXP)

1. Descobrir projeto e tags.
2. Digitalizar e extrair (em paralelo).
3. Validar (opcional).

Observação:

Não há etapa de classificação, pois a Extração e Processamento Inteligente (IXP) lida apenas com extrações.

Digitalização e extração paralelas (apenas IXP)

Para projetos de Extração e Processamento Inteligente (IXP), você pode pular a verificação periódica do resultado da digitalização e iniciar a extração imediatamente após enviar a digitalização.O backend executa ambas as operações em paralelo. A digitalização e a extração do Extração e Processamento Inteligente (IXP) ocorrem simultaneamente, e o sistema retorna o resultado final da extração apenas após a conclusão de ambos.

Essa é uma otimização específica do IXP que não funciona com Projetos do Document Understanding Clássico ou Moderno, nos quais 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 período de inatividade entre a digitalização e a extração, reduzindo a latência total.

Etapa 1: descobrir o projeto de Extração e Processamento Inteligente (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>'

Na resposta, observe o id do projeto de Extração e Processamento Inteligente (IXP).

Obter tags (versões publicadas)

As tags correspondem a versões do modelo publicadas marcadas como Preparação ou Produção na interface do usuário de 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 documentos

Para obter tipos de documentos, 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 de Extração e Processamento Inteligente (IXP) suporta as seguintes abordagens de roteamento:

• Baseado em tags - Roteamento por tag e documentTypeId. Recomendamos isso para fluxos de trabalho de produção ou preparação.
• Baseado em ExtractorId - Roteie 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": "..." }. Sondar 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>'

Sonde até que status seja Succeeded ou Failed.

Extração baseada no ExtractorId

Usa os mesmos pontos de extremidade baseados em extrator que o Document Understanding clássico ou moderno.O ExtractorId para Extração e Processamento Inteligente (IXP) segue o formato gpt_ixp_[version], visível na resposta de 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 à extração do IXP

API v1 ou v1.1

Nas versões v1 e v1.1, os grupos de campos de Extração e Processamento Inteligente (IXP) correspondem a FieldType: "Table" na resposta, com campos individuais como colunas da tabela.O sistema representa todos os valores como texto (string), independentemente de seu tipo de dados de Extração e Processamento Inteligente (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 estruturais 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 agrupados em uma estrutura de linhas de tabela.
• O array Tables contém os valores reais das células.

API v2

Na v2, os Grupos de campos de Extração e Processamento Inteligente (IXP) mapeiam até FieldType: "FieldGroup" em vez de Table.Esse é um mapeamento exato do conceito de grupo de campos de IXP. Cada campo preserva seu tipo de dados de Extração e Processamento Inteligente (IXP) real, 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 para obter detalhes.

{
  "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".
• Removemos o Array Tables.Os grupos de campos são retornados diretamente em Fields.
• Os campos individuais preservam seus tipos de dados de Extração e Processamento Inteligente (IXP) em vez de todos serem strings.
• Os FieldIds usam notação de pontos, por exemplo, Default.Seller.Name).

Estrutura de resposta de descoberta de IXP

Os projetos de Extração e Processamento Inteligente (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, mapeia para o rótulo produção ou preparação na interface do usuário do Extração e Processamento Inteligente (IXP).

Consider the following when calling the IXP extraction endpoints:

• No prompts needed: Unlike the Document Understanding generative extractor or classifier, IXP extraction schema is pre-defined in the IXP project taxonomy. You do not pass prompts in the API call.
• Tag = versão do modelo: use a tag que corresponde à versão de produção ou de preparação que deseja chamar.
• IDdoTipoDeDocumento: projetos de Extração e Processamento Inteligente (IXP) normalmente usam um único tipo de documento padrão (00000000-0000-0000-0000-000000000000).
• Limites de páginas: GPT-4o até 50 páginas, Gemini até 500 páginas por chamada.
• Metering: IXP extraction is charged as follows depending on the pricing plan you have:
  • Flex Plan: 1 AI Unit per page, or 0.8 AI Units per page when the page is already classified upstream, for example, in a Document Understanding modern project.
  • Unified Pricing: 0.2 Platform Units per page. Failed requests do not consume units.
• Data retention: Digitization 7 days, extraction 24 hours.

Observação:

Document Understanding and IXP licenses can be used together. For more details, refer to Metering and charging logic (Flex Plan) and IXP Flex Pricing Plan.