;
};
Ce guide vous accompagne pas à pas dans le workflow de l'API Vantage : authentifiez-vous, trouvez une compétence, téléversez un document et téléchargez les résultats structurés.
**Ce que vous allez accomplir :** Soumettre un document à l'API REST Vantage et recevoir des données extraites structurées au format JSON.
**Durée estimée :** \~10 minutes
## Prérequis
* Un tenant Vantage avec des identifiants d’un 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**.
## Étape 1 : S'authentifier
Obtenez un jeton d'accès à l'aide de vos identifiants client.
```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 réponse inclut un `access_token` (valide 24 heures). Utilisez-le dans l'en-tête `Authorization` pour toutes les requêtes ultérieures.
Utilisez le sélecteur **Tenant Region** en haut de cette page pour mettre à jour toutes les URL afin qu’elles correspondent à votre région.
## Étape 2 : Trouver une compétence
Répertoriez les compétences disponibles dans votre tenant pour trouver celle qui correspond à votre document.
```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']}")
```
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.
```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"]
```
## Étape 4 : Vérifier le statut
Interrogez la transaction jusqu'à la fin du traitement.
```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"Status: {status['status']}")
if status["status"] in ("Processed", "ProcessedWithWarnings"):
break
if status["status"] == "NotProcessed":
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.
```bash theme={null}
# Lister les documents de la transaction
curl -X GET "https://vantage-us.abbyy.com/api/publicapi/v1/transactions/$TRANSACTION_ID/documents" \
-H "Authorization: Bearer $TOKEN"
# Télécharger le fichier de résultat
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}
# Récupérer les documents
docs = requests.get(
f"https://vantage-us.abbyy.com/api/publicapi/v1/transactions/{transaction_id}/documents",
headers={"Authorization": f"Bearer {token}"},
).json()
# Télécharger le résultat du premier document
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)
```
Le résultat contient des champs extraits avec leurs valeurs et scores de confiance.
```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
}]
}
]
}
}
}
]
}
```
Chaque champ comprend une `Value` (le texte extrait après normalisation), un score `Annotation.Confidence` de 0 à 100, ainsi qu'un indicateur `NeedVerification` précisant si une vérification humaine est recommandée. Les champs dont le niveau de confiance est faible ou dont les règles de validation ont échoué sont automatiquement signalés.
Pour une présentation complète de la structure de sortie, consultez [Comprendre vos résultats](/fr/vantage/getting-started/results).
## Exemple complet
```python theme={null}
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"] in ("Processed", "ProcessedWithWarnings"):
break
if tx["status"] == "NotProcessed":
raise Exception(f"Processing failed")
time.sleep(5)
# Étape 5 : Télécharger les résultats
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)
```
## Étapes suivantes
Découvrez comment interpréter les champs extraits, les scores de confiance et les données de tableau.
Documentation complète de l’API avec environnement de test interactif.
Flux Authorization Code, ROPC et autres méthodes d’authentification.
Traitez plusieurs documents avec des appels d’API distincts pour un meilleur contrôle.