;
};
Esta guía le explica paso a paso el flujo de trabajo de la Vantage API: autenticarse, encontrar un skill, cargar un documento y descargar los resultados estructurados.
**Lo que lograrás:** Enviar un documento a la API REST de Vantage y recibir los 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**.
## Paso 1: Autenticarse
Obtenga un token de acceso con sus credenciales de cliente.
```bash theme={null}
curl -X POST "https://vantage-us.abbyy.com/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"
```
```python theme={null}
import requests
response = requests.post(
"https://vantage-us.abbyy.com/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.
Usa el selector **Tenant Region** en la parte superior de esta página para actualizar todas las URL según tu región.
## Paso 2: Encontrar un skill
Enumere los skills disponibles en su tenant para encontrar el indicado para su documento.
```bash theme={null}
curl -X GET "https://vantage-us.abbyy.com/api/publicapi/v1/skills" \
-H "Authorization: Bearer $TOKEN"
```
```python theme={null}
skills = requests.get(
"https://vantage-us.abbyy.com/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 a la API.
```bash theme={null}
curl -X POST "https://vantage-us.abbyy.com/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"
```
```python theme={null}
with open("invoice.pdf", "rb") as f:
response = requests.post(
"https://vantage-us.abbyy.com/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.
```bash theme={null}
curl -X GET "https://vantage-us.abbyy.com/api/publicapi/v1/transactions/$TRANSACTION_ID" \
-H "Authorization: Bearer $TOKEN"
```
```python theme={null}
import time
while True:
status = requests.get(
f"https://vantage-us.abbyy.com/api/publicapi/v1/transactions/{transaction_id}",
headers={"Authorization": f"Bearer {token}"},
).json()
print(f"Estado: {status['status']}")
if status["status"] in ("Processed", "ProcessedWithWarnings"):
break
if status["status"] == "NotProcessed":
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.
```bash theme={null}
# Listar los documentos de la transacción
curl -X GET "https://vantage-us.abbyy.com/api/publicapi/v1/transactions/$TRANSACTION_ID/documents" \
-H "Authorization: Bearer $TOKEN"
# Descargar el archivo de resultado
curl -X GET "https://vantage-us.abbyy.com/api/publicapi/v1/transactions/$TRANSACTION_ID/files/$FILE_ID/download" \
-H "Authorization: Bearer $TOKEN" \
-o result.json
```
```python theme={null}
# Obtener documentos
docs = requests.get(
f"https://vantage-us.abbyy.com/api/publicapi/v1/transactions/{transaction_id}/documents",
headers={"Authorization": f"Bearer {token}"},
).json()
# Descargar el resultado del primer documento
result_file_id = docs[0]["resultFiles"][0]["id"]
result = requests.get(
f"https://vantage-us.abbyy.com/api/publicapi/v1/transactions/{transaction_id}/files/{result_file_id}/download",
headers={"Authorization": f"Bearer {token}"},
).json()
print(result)
```
El resultado contiene campos extraídos con valores y puntuaciones de confianza.
```json theme={null}
{
"SkillName": "ABBYY Invoice",
"Documents": [
{
"ExtractedData": {
"RootObject": {
"Fields": [
{
"Name": "InvoiceNumber",
"List": [{
"Value": "INV-2024-0042",
"Annotation": { "Confidence": 97, "RawValue": "INV-2024-0042" },
"NeedVerification": false
}]
},
{
"Name": "VendorName",
"List": [{
"Value": "Acme Corp",
"Annotation": { "Confidence": 95, "RawValue": "Acme Corp" },
"NeedVerification": false
}]
},
{
"Name": "TotalAmount",
"List": [{
"Value": "1,250.00",
"Annotation": { "Confidence": 88, "RawValue": "1,250.00" },
"NeedVerification": false
}]
}
]
}
}
}
]
}
```
Cada campo incluye un `Value` (el texto extraído tras la normalización), una puntuación `Annotation.Confidence` de 0 a 100 y un indicador `NeedVerification` que señala si se recomienda revisión humana. Los campos con baja confianza o con errores en las reglas de validación se marcan automáticamente.
Para obtener una descripción completa de la estructura de salida, consulte [Descripción de los resultados](/es/vantage/getting-started/results).
## Ejemplo completo
```python theme={null}
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: Autenticar
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"Skills disponibles: {[s['name'] for s in skills]}")
# Paso 3: Procesar 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"Transacción: {transaction_id}")
# Paso 4: Consultar hasta completar
while True:
tx = requests.get(
f"{BASE_URL}/api/publicapi/v1/transactions/{transaction_id}",
headers=headers,
).json()
print(f"Estado: {tx['status']}")
if tx["status"] in ("Processed", "ProcessedWithWarnings"):
break
if tx["status"] == "NotProcessed":
raise Exception(f"Error en el procesamiento")
time.sleep(5)
# Paso 5: Descargar resultados
docs = requests.get(
f"{BASE_URL}/api/publicapi/v1/transactions/{transaction_id}/documents",
headers=headers,
).json()
for doc in docs:
for rf in doc.get("resultFiles", []):
result = requests.get(
f"{BASE_URL}/api/publicapi/v1/transactions/{transaction_id}/files/{rf['id']}/download",
headers=headers,
).json()
print(result)
```
## Próximos pasos
Aprenda a interpretar los campos extraídos, las puntuaciones de confianza y los datos tabulares.
Documentación completa de la API con zona de pruebas interactiva.
Flujo de código de autorización, ROPC y otros métodos de autenticación.
Procese varios documentos con llamadas independientes a la API para tener más control.