Traiter via l’API

Ce guide vous accompagne tout au long du flux de travail de l’API Vantage : authentifiez-vous, recherchez une compétence, téléversez un document et téléchargez les résultats structurés. Ce que vous accomplirez : vous soumettrez un document à l’API REST Vantage et recevrez des données extraites structurées au format JSON. Durée estimée : ~10 minutes

Prérequis

Un tenant Vantage avec des identifiants client API (client_id et client_secret)
Un exemple de document à traiter (PDF, TIFF, JPEG ou PNG)

Vous n’avez pas encore d’identifiants ? Votre administrateur de tenant peut créer des identifiants client API dans Administration > Clients API.

Définissez l’URL de base

Toutes les requêtes sont envoyées au point de terminaison régional de votre tenant. Sélectionnez votre région ci-dessous (cette affectation fonctionne aussi bien dans le shell que dans Python) ; tous les exemples de ce guide utilisent BASE_URL :

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

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

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

Étape 1 : S’authentifier

Obtenez un jeton d’accès à l’aide de vos identifiants client.

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 réponse inclut un access_token (valide 24 heures). Utilisez-le dans l’en-tête Authorization pour toutes les requêtes ultérieures.

Étape 2 : Trouver une compétence

Répertoriez les compétences disponibles dans votre tenant pour trouver celle qui correspond à votre document.

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

Notez l’id de la compétence que vous souhaitez utiliser (par exemple, une compétence Invoice).

Étape 3 : Traiter un document

Téléversez un document et traitez-le avec une compétence en un seul appel 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"]

Étape 4 : Vérifier le statut

Interrogez la transaction jusqu’à la fin du traitement.

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)

Interrogez toutes les 5 à 10 secondes. Le traitement prend généralement 10 à 30 secondes, selon la complexité du document.

Étape 5 : Télécharger les résultats

Obtenez les données extraites au format JSON. Les identifiants des fichiers de résultat proviennent de la réponse de statut de la transaction que vous avez interrogée à l’étape 4 : chaque entrée de documents[].resultFiles[] comporte un fileId et un type. Par défaut, une Compétence de document produit deux fichiers de résultat : type: "Json" (les résultats complets, y compris les métadonnées des champs) et type: "FieldsJson" (les valeurs extraites, le point de départ le plus simple) ; les paramètres d’export de la compétence permettent d’ajouter d’autres formats.

cURL
Python

# Obtenir le statut de la transaction ; recherchez documents[].resultFiles[] dans la réponse
curl -X GET "$BASE_URL/api/publicapi/v1/transactions/$TRANSACTION_ID" \
  -H "Authorization: Bearer $TOKEN"

# Télécharger un fichier de résultat à l’aide de son fileId
curl -X GET "$BASE_URL/api/publicapi/v1/transactions/$TRANSACTION_ID/files/$FILE_ID/download" \
  -H "Authorization: Bearer $TOKEN" \
  -o result.json

# La réponse de statut de l’étape 4 répertorie les fichiers de résultat
result_files = status["documents"][0]["resultFiles"]

# Sélectionner le fichier contenant uniquement les valeurs
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)

Le résultat contenant uniquement les valeurs met en correspondance chaque champ défini par la compétence avec sa valeur extraite. Si des vérifications de règles ont échoué pendant le traitement, le fichier contient également un tableau RuleErrors de premier niveau, aux côtés de Version et Fields.

Afficher Exemple : résultat de l’extraction d’une facture (valeurs uniquement)

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

Les libellés exacts des champs et leur imbrication dépendent de la compétence. Pour obtenir les scores de confiance, les coordonnées des caractères et les autres métadonnées de champ, téléchargez plutôt le fichier de résultat type: "Json" ; sa structure est décrite dans la référence du JSON Schema. Pour une présentation complète de la structure de sortie, consultez Comprendre vos résultats.

Exemple complet

Afficher Script Python complet

import requests
import time

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

# Étape 1 : authentification
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}"}

# Étape 2 : rechercher les compétences
skills = requests.get(f"{BASE_URL}/api/publicapi/v1/skills", headers=headers).json()
print(f"Available skills: {[s['name'] for s in skills]}")

# Étape 3 : traiter le document
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}")

# Étape 4 : interroger jusqu'à la fin du traitement
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)

# Étape 5 : télécharger les résultats (les identifiants des fichiers de résultats proviennent de la réponse de statut)
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

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

# Étape 1 : authentification
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}"}

# Étape 2 : rechercher les compétences
skills = requests.get(f"{BASE_URL}/api/publicapi/v1/skills", headers=headers).json()
print(f"Available skills: {[s['name'] for s in skills]}")

# Étape 3 : traiter le document
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}")

# Étape 4 : interroger l'état jusqu'à la fin du traitement
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)

# Étape 5 : télécharger les résultats (les identifiants des fichiers de résultats proviennent de la réponse d'état)
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

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

# Étape 1 : s'authentifier
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}"}

# Étape 2 : rechercher les compétences
skills = requests.get(f"{BASE_URL}/api/publicapi/v1/skills", headers=headers).json()
print(f"Available skills: {[s['name'] for s in skills]}")

# Étape 3 : traiter le document
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}")

# Étape 4 : interroger jusqu'à la fin du traitement
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)

# Étape 5 : télécharger les résultats (les ID des fichiers de résultats proviennent de la réponse de statut)
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)

Étapes suivantes

Comprendre vos résultats

Découvrez comment interpréter les champs extraits, les scores de confiance et les données de tableaux.

Référence de l’API

Documentation complète de l’API avec environnement de test interactif.

Options d’authentification

Authorization Code Flow, ROPC et autres méthodes d’authentification.

Traitement par lots

Traitez plusieurs documents à l’aide d’appels d’API distincts pour un meilleur contrôle.

Getting Started

Go Deeper

Prérequis

Définissez l’URL de base

Étape 1 : S’authentifier

Étape 2 : Trouver une compétence

Étape 3 : Traiter un document

Étape 4 : Vérifier le statut

Étape 5 : Télécharger les résultats

Exemple complet

Étapes suivantes

Comprendre vos résultats

Référence de l’API

Options d’authentification

Traitement par lots

​Prérequis

​Définissez l’URL de base

​Étape 1 : S’authentifier

​Étape 2 : Trouver une compétence

​Étape 3 : Traiter un document

​Étape 4 : Vérifier le statut

​Étape 5 : Télécharger les résultats

​Exemple complet

​Étapes suivantes

Comprendre vos résultats

Référence de l’API

Options d’authentification

Traitement par lots

Prérequis

Définissez l’URL de base

Étape 1 : S’authentifier

Étape 2 : Trouver une compétence

Étape 3 : Traiter un document

Étape 4 : Vérifier le statut

Étape 5 : Télécharger les résultats

Exemple complet

Étapes suivantes