Verarbeitung per API

In diesem Leitfaden erfahren Sie, wie Sie sich über die Vantage-API authentifizieren, einen Skill finden, ein Dokument hochladen und strukturierte Ergebnisse herunterladen. Das erreichen Sie: Sie übermitteln ein Dokument an die Vantage REST API und erhalten strukturierte extrahierte Daten im JSON-Format. Benötigte Zeit: ~10 Minuten

Voraussetzungen

Ein Vantage-Mandant mit API-Client-Zugangsdaten (client_id und client_secret)
Ein Beispieldokument zur Verarbeitung (PDF, TIFF, JPEG oder PNG)

Sie haben noch keine Zugangsdaten? Ihr Mandanten-Administrator kann unter Administration > API clients API-Client-Zugangsdaten erstellen.

Basis-URL festlegen

Alle Anfragen werden an den regionalen Endpoint Ihres Mandanten gesendet. Wählen Sie unten Ihre Region aus (die Zuweisung funktioniert sowohl in der Shell als auch in Python). Alle Beispiele in diesem Leitfaden verwenden BASE_URL:

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

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

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

Schritt 1: Authentifizieren

Rufen Sie ein Zugriffstoken mit Ihren API-Client-Zugangsdaten ab.

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

Die Antwort enthält ein access_token (gültig für 24 Stunden). Verwenden Sie es im Authorization-Header für alle weiteren Anfragen.

Schritt 2: Einen Skill finden

Listen Sie die in Ihrem Mandanten verfügbaren Skills auf, um den passenden für Ihr Dokument zu finden.

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

Notieren Sie sich die id des Skills, den Sie verwenden möchten (z. B. einen Invoice-Skill).

Schritt 3: Ein Dokument verarbeiten

Laden Sie ein Dokument hoch und verarbeiten Sie es mit einem Skill in einem einzigen API-Aufruf.

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

Schritt 4: Status prüfen

Fragen Sie den Vorgang ab, bis die Verarbeitung abgeschlossen ist.

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"Status: {status['status']}")

    if status["status"] == "Processed":
        break
    if status["status"] in ("Failed", "Canceled"):
        raise Exception("Processing failed")

    time.sleep(5)

Führen Sie die Abfrage alle 5–10 Sekunden durch. Die Verarbeitung dauert typischerweise je nach Komplexität des Dokuments 10–30 Sekunden.

Schritt 5: Ergebnisse herunterladen

Extrahierte Daten als JSON abrufen. Die Bezeichner der Ergebnisdateien stammen aus der Antwort zum Vorgangsstatus, die Sie in Schritt 4 abgefragt haben: Jeder Eintrag in documents[].resultFiles[] enthält eine fileId und einen type. Standardmäßig erzeugt ein Document-Skill zwei Ergebnisdateien: type: "Json" (die vollständigen Ergebnisse einschließlich Feld-Metadaten) und type: "FieldsJson" (die extrahierten Werte – der einfachste Einstiegspunkt). Über die Exporteinstellungen des Skills lassen sich weitere Formate hinzufügen.

cURL
Python

# Vorgangsstatus abrufen; documents[].resultFiles[] in der Antwort suchen
curl -X GET "$BASE_URL/api/publicapi/v1/transactions/$TRANSACTION_ID" \
  -H "Authorization: Bearer $TOKEN"

# Ergebnisdatei mithilfe ihrer fileId herunterladen
curl -X GET "$BASE_URL/api/publicapi/v1/transactions/$TRANSACTION_ID/files/$FILE_ID/download" \
  -H "Authorization: Bearer $TOKEN" \
  -o result.json

# Die Statusantwort aus Schritt 4 listet die Ergebnisdateien auf
result_files = status["documents"][0]["resultFiles"]

# Datei mit ausschließlich Werten auswählen
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)

Das Ergebnis mit ausschließlich Werten ordnet jedem vom Skill definierten Feld seinen extrahierten Wert zu. Sind während der Verarbeitung Regelprüfungen fehlgeschlagen, enthält die Datei zusätzlich ein RuleErrors-Array auf oberster Ebene neben Version und Fields.

Anzeigen Beispiel: Ergebnis der Rechnungsextraktion (nur Werte)

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

Die genauen Feldnamen und die Verschachtelung hängen vom Skill ab. Für Konfidenzwerte, Zeichenkoordinaten und weitere Feld-Metadaten laden Sie stattdessen die Ergebnisdatei mit type: "Json" herunter; deren Struktur ist in der JSON-Schema-Referenz dokumentiert. Eine vollständige Erläuterung der Ausgabestruktur finden Sie unter Understanding your results.

Vollständiges Beispiel

Anzeigen Vollständiges Python-Skript

import requests
import time

# Konfiguration
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"

# Schritt 1: Authentifizieren
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}"}

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

# Schritt 3: Dokument verarbeiten
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}")

# Schritt 4: Abschluss der Verarbeitung abfragen
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)

# Schritt 5: Ergebnisse herunterladen (die IDs der Ergebnisdateien stammen aus der Statusantwort)
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

# Konfiguration
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"

# Schritt 1: Authentifizieren
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}"}

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

# Schritt 3: Dokument verarbeiten
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}")

# Schritt 4: Status bis zum Abschluss abfragen
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)

# Schritt 5: Ergebnisse herunterladen (die IDs der Ergebnisdateien stammen aus der Status-Antwort)
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

# Konfiguration
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"

# Schritt 1: Authentifizieren
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}"}

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

# Schritt 3: Document verarbeiten
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}")

# Schritt 4: Status bis zum Abschluss abfragen
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)

# Schritt 5: Ergebnisse herunterladen (die IDs der Ergebnisdateien stammen aus der Status-Antwort)
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)

Nächste Schritte

Ihre Ergebnisse verstehen

Erfahren Sie, wie Sie extrahierte Felder, Konfidenzwerte und Tabellendaten interpretieren.

API-Referenz

Vollständige API-Dokumentation mit interaktivem Playground.

Authentifizierungsoptionen

Authorization Code Flow, ROPC und weitere Authentifizierungsmethoden.

Batchverarbeitung

Verarbeiten Sie mehrere Dokumente mit separaten API-Aufrufen, um mehr Kontrolle zu erhalten.

Erste Schritte

Vertiefung

Voraussetzungen

Basis-URL festlegen

Schritt 1: Authentifizieren

Schritt 2: Einen Skill finden

Schritt 3: Ein Dokument verarbeiten

Schritt 4: Status prüfen

Schritt 5: Ergebnisse herunterladen

Vollständiges Beispiel

Nächste Schritte

Ihre Ergebnisse verstehen

API-Referenz

Authentifizierungsoptionen

Batchverarbeitung

​Voraussetzungen

​Basis-URL festlegen

​Schritt 1: Authentifizieren

​Schritt 2: Einen Skill finden

​Schritt 3: Ein Dokument verarbeiten

​Schritt 4: Status prüfen

​Schritt 5: Ergebnisse herunterladen

​Vollständiges Beispiel

​Nächste Schritte

Ihre Ergebnisse verstehen

API-Referenz

Authentifizierungsoptionen

Batchverarbeitung

Voraussetzungen

Basis-URL festlegen

Schritt 1: Authentifizieren

Schritt 2: Einen Skill finden

Schritt 3: Ein Dokument verarbeiten

Schritt 4: Status prüfen

Schritt 5: Ergebnisse herunterladen

Vollständiges Beispiel

Nächste Schritte