Procesar con la API

Esta guía le explica el flujo de trabajo de Vantage API: autentíquese, busque una skill, cargue un documento y descargue resultados estructurados. Lo que logrará: Envíe un documento a la API REST de Vantage y reciba datos extraídos estructurados en formato JSON. Tiempo estimado: ~10 minutos

Requisitos previos

Un tenant de Vantage con credenciales de cliente para la API (client_id y client_secret)
Un documento de ejemplo para procesar (PDF, TIFF, JPEG o PNG)

¿Aún no tienes credenciales? El administrador de tu tenant puede crear credenciales de cliente de API en Administración > Clientes de API.

Configure la URL base

Todas las solicitudes se envían al endpoint regional de su tenant. Seleccione su región a continuación (la asignación funciona tanto en shell como en Python); todos los ejemplos de esta guía usan BASE_URL:

BASE_URL="https://vantage-us.abbyy.com"

BASE_URL="https://vantage-eu.abbyy.com"

BASE_URL="https://vantage-au.abbyy.com"

Paso 1: Autenticarse

Obtenga un token de acceso con sus credenciales de cliente.

cURL
Python

curl -X POST "$BASE_URL/auth2/connect/token" \
  -d "grant_type=client_credentials" \
  -d "scope=openid permissions global.wildcard" \
  -d "client_id=YOUR_CLIENT_ID" \
  -d "client_secret=YOUR_CLIENT_SECRET"

import requests

response = requests.post(
    f"{BASE_URL}/auth2/connect/token",
    data={
        "grant_type": "client_credentials",
        "scope": "openid permissions global.wildcard",
        "client_id": "YOUR_CLIENT_ID",
        "client_secret": "YOUR_CLIENT_SECRET",
    },
)

token = response.json()["access_token"]

La respuesta incluye un access_token (válido por 24 horas). Úselo en el encabezado Authorization para todas las solicitudes posteriores.

Paso 2: Encontrar un skill

Enumere los skills disponibles en su tenant para encontrar el indicado para su documento.

cURL
Python

curl -X GET "$BASE_URL/api/publicapi/v1/skills" \
  -H "Authorization: Bearer $TOKEN"

skills = requests.get(
    f"{BASE_URL}/api/publicapi/v1/skills",
    headers={"Authorization": f"Bearer {token}"},
).json()

for skill in skills:
    print(f"{skill['id']}: {skill['name']}")

Anote el id del skill que desea utilizar (p. ej., un skill Invoice).

Paso 3: Procesar un documento

Cargue un documento y procéselo con un skill en una sola llamada de API.

cURL
Python

curl -X POST "$BASE_URL/api/publicapi/v1/transactions/launch?skillId=SKILL_ID" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: multipart/form-data" \
  -F 'Model={"files": [{}]}' \
  -F "Files=@invoice.pdf;type=application/pdf"

with open("invoice.pdf", "rb") as f:
    response = requests.post(
        f"{BASE_URL}/api/publicapi/v1/transactions/launch",
        params={"skillId": "SKILL_ID"},
        headers={"Authorization": f"Bearer {token}"},
        files={
            "Model": (None, '{"files": [{}]}', "application/json"),
            "Files": ("invoice.pdf", f, "application/pdf"),
        },
    )

transaction_id = response.json()["transactionId"]

Paso 4: Verificar el estado

Consulte la transacción hasta que el procesamiento se complete.

cURL
Python

curl -X GET "$BASE_URL/api/publicapi/v1/transactions/$TRANSACTION_ID" \
  -H "Authorization: Bearer $TOKEN"

import time

while True:
    status = requests.get(
        f"{BASE_URL}/api/publicapi/v1/transactions/{transaction_id}",
        headers={"Authorization": f"Bearer {token}"},
    ).json()

    print(f"Estado: {status['status']}")

    if status["status"] == "Processed":
        break
    if status["status"] in ("Failed", "Canceled"):
        raise Exception("Error de procesamiento")

    time.sleep(5)

Realice sondeos cada 5–10 segundos. El procesamiento suele tardar entre 10 y 30 segundos, según la complejidad del documento.

Paso 5: Descargar resultados

Obtenga los datos extraídos en formato JSON. Los identificadores de los archivos de resultado provienen de la respuesta de estado de la transacción que consultó en el Paso 4: cada entrada de documents[].resultFiles[] tiene un fileId y un type. De forma predeterminada, un Skill de documento genera dos archivos de resultado: type: "Json" (los resultados completos, incluidos los metadatos de los campos) y type: "FieldsJson" (los valores extraídos, el punto de partida más sencillo); la configuración de exportación del skill puede añadir otros formatos.

cURL
Python

# Obtener el estado de la transacción; buscar documents[].resultFiles[] en la respuesta
curl -X GET "$BASE_URL/api/publicapi/v1/transactions/$TRANSACTION_ID" \
  -H "Authorization: Bearer $TOKEN"

# Descargar un archivo de resultado usando su fileId
curl -X GET "$BASE_URL/api/publicapi/v1/transactions/$TRANSACTION_ID/files/$FILE_ID/download" \
  -H "Authorization: Bearer $TOKEN" \
  -o result.json

# La respuesta de estado del paso 4 enumera los archivos de resultado
result_files = status["documents"][0]["resultFiles"]

# Seleccionar el archivo que contiene solo valores
fields_file = next(f for f in result_files if f["type"] == "FieldsJson")

result = requests.get(
    f"{BASE_URL}/api/publicapi/v1/transactions/{transaction_id}/files/{fields_file['fileId']}/download",
    headers={"Authorization": f"Bearer {token}"},
).json()

print(result)

El resultado de solo valores asigna a cada campo definido por el skill su valor extraído. Si alguna comprobación de regla falló durante el procesamiento, el archivo también incluye un array RuleErrors de nivel superior junto con Version y Fields.

Mostrar Ejemplo: resultado de la extracción de facturas (solo valores)

{
  "Version": "3.0",
  "Fields": {
    "Invoice Number": "INV-2024-0042",
    "Invoice Date": "01/15/2024",
    "Currency": "USD",
    "Total": "1,250.00",
    "Business Unit": {
      "Name": "Acme Corp",
      "City": "Springfield",
      "CountryCode": "US"
    },
    "Line Items": [
      {
        "Description": "Widget, industrial grade",
        "Quantity": "2",
        "Unit Price": "625.00",
        "Total Price": "1,250.00"
      }
    ]
  }
}

Los nombres exactos de los campos y su anidamiento dependen del skill. Para obtener las puntuaciones de confianza, las coordenadas de los caracteres y otros metadatos de los campos, descargue en su lugar el archivo de resultado type: "Json"; su estructura está documentada en la referencia del esquema JSON. Para obtener una descripción completa de la estructura de salida, consulte Descripción de los resultados.

Ejemplo completo

Mostrar Script de Python completo

import requests
import time

# Configuración
BASE_URL = "https://vantage-us.abbyy.com"
CLIENT_ID = "YOUR_CLIENT_ID"
CLIENT_SECRET = "YOUR_CLIENT_SECRET"
SKILL_ID = "YOUR_SKILL_ID"
FILE_PATH = "invoice.pdf"

# Paso 1: autenticarse
auth = requests.post(
    f"{BASE_URL}/auth2/connect/token",
    data={
        "grant_type": "client_credentials",
        "scope": "openid permissions global.wildcard",
        "client_id": CLIENT_ID,
        "client_secret": CLIENT_SECRET,
    },
)
token = auth.json()["access_token"]
headers = {"Authorization": f"Bearer {token}"}

# Paso 2: buscar los skills
skills = requests.get(f"{BASE_URL}/api/publicapi/v1/skills", headers=headers).json()
print(f"Available skills: {[s['name'] for s in skills]}")

# Paso 3: procesar el documento
with open(FILE_PATH, "rb") as f:
    launch = requests.post(
        f"{BASE_URL}/api/publicapi/v1/transactions/launch",
        params={"skillId": SKILL_ID},
        headers=headers,
        files={
            "Model": (None, '{"files": [{}]}', "application/json"),
            "Files": (FILE_PATH, f, "application/pdf"),
        },
    )
transaction_id = launch.json()["transactionId"]
print(f"Transaction: {transaction_id}")

# Paso 4: consultar periódicamente hasta que finalice
while True:
    tx = requests.get(
        f"{BASE_URL}/api/publicapi/v1/transactions/{transaction_id}",
        headers=headers,
    ).json()
    print(f"Status: {tx['status']}")
    if tx["status"] == "Processed":
        break
    if tx["status"] in ("Failed", "Canceled"):
        raise Exception(f"Processing failed")
    time.sleep(5)

# Paso 5: descargar los resultados (los id de los archivos de resultados provienen de la respuesta de estado)
for doc in tx["documents"]:
    for rf in doc["resultFiles"]:
        if rf["type"] != "FieldsJson":
            continue
        result = requests.get(
            f"{BASE_URL}/api/publicapi/v1/transactions/{transaction_id}/files/{rf['fileId']}/download",
            headers=headers,
        ).json()
        print(result)

import requests
import time

# Configuración
BASE_URL = "https://vantage-eu.abbyy.com"
CLIENT_ID = "YOUR_CLIENT_ID"
CLIENT_SECRET = "YOUR_CLIENT_SECRET"
SKILL_ID = "YOUR_SKILL_ID"
FILE_PATH = "invoice.pdf"

# Paso 1: Autenticarse
auth = requests.post(
    f"{BASE_URL}/auth2/connect/token",
    data={
        "grant_type": "client_credentials",
        "scope": "openid permissions global.wildcard",
        "client_id": CLIENT_ID,
        "client_secret": CLIENT_SECRET,
    },
)
token = auth.json()["access_token"]
headers = {"Authorization": f"Bearer {token}"}

# Paso 2: Buscar skills
skills = requests.get(f"{BASE_URL}/api/publicapi/v1/skills", headers=headers).json()
print(f"Available skills: {[s['name'] for s in skills]}")

# Paso 3: Procesar el documento
with open(FILE_PATH, "rb") as f:
    launch = requests.post(
        f"{BASE_URL}/api/publicapi/v1/transactions/launch",
        params={"skillId": SKILL_ID},
        headers=headers,
        files={
            "Model": (None, '{"files": [{}]}', "application/json"),
            "Files": (FILE_PATH, f, "application/pdf"),
        },
    )
transaction_id = launch.json()["transactionId"]
print(f"Transaction: {transaction_id}")

# Paso 4: Consultar el estado hasta que finalice
while True:
    tx = requests.get(
        f"{BASE_URL}/api/publicapi/v1/transactions/{transaction_id}",
        headers=headers,
    ).json()
    print(f"Status: {tx['status']}")
    if tx["status"] == "Processed":
        break
    if tx["status"] in ("Failed", "Canceled"):
        raise Exception(f"Processing failed")
    time.sleep(5)

# Paso 5: Descargar los resultados (los id de los archivos de resultados provienen de la respuesta de estado)
for doc in tx["documents"]:
    for rf in doc["resultFiles"]:
        if rf["type"] != "FieldsJson":
            continue
        result = requests.get(
            f"{BASE_URL}/api/publicapi/v1/transactions/{transaction_id}/files/{rf['fileId']}/download",
            headers=headers,
        ).json()
        print(result)

import requests
import time

# Configuración
BASE_URL = "https://vantage-au.abbyy.com"
CLIENT_ID = "YOUR_CLIENT_ID"
CLIENT_SECRET = "YOUR_CLIENT_SECRET"
SKILL_ID = "YOUR_SKILL_ID"
FILE_PATH = "invoice.pdf"

# Paso 1: autenticarse
auth = requests.post(
    f"{BASE_URL}/auth2/connect/token",
    data={
        "grant_type": "client_credentials",
        "scope": "openid permissions global.wildcard",
        "client_id": CLIENT_ID,
        "client_secret": CLIENT_SECRET,
    },
)
token = auth.json()["access_token"]
headers = {"Authorization": f"Bearer {token}"}

# Paso 2: buscar los skills
skills = requests.get(f"{BASE_URL}/api/publicapi/v1/skills", headers=headers).json()
print(f"Available skills: {[s['name'] for s in skills]}")

# Paso 3: procesar el documento
with open(FILE_PATH, "rb") as f:
    launch = requests.post(
        f"{BASE_URL}/api/publicapi/v1/transactions/launch",
        params={"skillId": SKILL_ID},
        headers=headers,
        files={
            "Model": (None, '{"files": [{}]}', "application/json"),
            "Files": (FILE_PATH, f, "application/pdf"),
        },
    )
transaction_id = launch.json()["transactionId"]
print(f"Transaction: {transaction_id}")

# Paso 4: consultar el estado hasta que finalice
while True:
    tx = requests.get(
        f"{BASE_URL}/api/publicapi/v1/transactions/{transaction_id}",
        headers=headers,
    ).json()
    print(f"Status: {tx['status']}")
    if tx["status"] == "Processed":
        break
    if tx["status"] in ("Failed", "Canceled"):
        raise Exception(f"Processing failed")
    time.sleep(5)

# Paso 5: descargar los resultados (los id de los archivos de resultados se obtienen de la respuesta de estado)
for doc in tx["documents"]:
    for rf in doc["resultFiles"]:
        if rf["type"] != "FieldsJson":
            continue
        result = requests.get(
            f"{BASE_URL}/api/publicapi/v1/transactions/{transaction_id}/files/{rf['fileId']}/download",
            headers=headers,
        ).json()
        print(result)

Próximos pasos

Comprender los resultados

Aprenda a interpretar los campos extraídos, las puntuaciones de confianza y los datos de las tablas.

Referencia de la API

Documentación completa de la API con un entorno interactivo.

Opciones de autenticación

Flujo de código de autorización, ROPC y otros métodos de autenticación.

Procesamiento de lote

Procese varios documentos con llamadas de API independientes para tener un mayor control.

Getting Started

Go Deeper

Requisitos previos

Configure la URL base

Paso 1: Autenticarse

Paso 2: Encontrar un skill

Paso 3: Procesar un documento

Paso 4: Verificar el estado

Paso 5: Descargar resultados

Ejemplo completo

Próximos pasos

Comprender los resultados

Referencia de la API

Opciones de autenticación

Procesamiento de lote

​Requisitos previos

​Configure la URL base

​Paso 1: Autenticarse

​Paso 2: Encontrar un skill

​Paso 3: Procesar un documento

​Paso 4: Verificar el estado

​Paso 5: Descargar resultados

​Ejemplo completo

​Próximos pasos

Comprender los resultados

Referencia de la API

Opciones de autenticación

Procesamiento de lote

Requisitos previos

Configure la URL base

Paso 1: Autenticarse

Paso 2: Encontrar un skill

Paso 3: Procesar un documento

Paso 4: Verificar el estado

Paso 5: Descargar resultados

Ejemplo completo

Próximos pasos