# Démarrage rapide de l'API — Obtenez des résultats en 5 minutes

> Un parcours complet de bout en bout en cinq minutes avec l'API v1 d'ImageToTable.ai : obtenez votre clé, importez une facture, lancez le traitement et récupérez le JSON extrait.

Ce guide parcourt l'ensemble du processus — obtenir une clé, importer un document, lancer le traitement, récupérer les résultats — en prenant l'exemple d'une facture. Si vous n'avez pas encore installé `curl` ou configuré une variable d'environnement pour votre clé, consultez d'abord [Configuration de l'environnement](/developers/environment-setup).

## Étape 1 — Obtenez votre clé API

Votre clé API se trouve sur la [page des paramètres de votre compte](/profile/), dans la section Clé API. L'API v1 nécessite un forfait payant (Basique ou supérieur) — les clés du forfait Gratuit sont acceptées lors de la vérification d'authentification, mais chaque appel suivant renvoie une erreur `plan_required`. Les clés générées désormais ressemblent à `itt_live_<64 caractères hexadécimaux>` ; exportez la vôtre en tant que variable d'environnement pour éviter de la coder en dur dans un script :

```bash
export API_KEY="itt_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
```

## Étape 2 — Importez un document

`POST /api/v1/documents` accepte soit un `file` (multipart) soit une `url` que le serveur récupère pour vous — transmettez exactement un seul paramètre. `batch_name` est facultatif — omettez-le et l'API en génère un pour vous (renvoyé dans la réponse) ; tous les documents que vous souhaitez traiter ensemble doivent partager le même `batch_name`. Cet exemple utilise `url` avec une facture exemple hébergée sur notre propre site, il est donc exécutable tel quel, sans fichier local nécessaire :

**cURL**

```bash
curl -X POST https://imagetotable.ai/api/v1/documents \
  -H "Authorization: Bearer $API_KEY" \
  -F "url=https://imagetotable.ai/static/samples/invoice.webp"
```

**Python**

```python
import os
import requests

response = requests.post(
    "https://imagetotable.ai/api/v1/documents",
    headers={"Authorization": f"Bearer {os.environ['API_KEY']}"},
    data={"url": "https://imagetotable.ai/static/samples/invoice.webp"},
)
print(response.json())
```

**Javascript**

```javascript
const formData = new FormData();
formData.append("url", "https://imagetotable.ai/static/samples/invoice.webp");

const response = await fetch("https://imagetotable.ai/api/v1/documents", {
  method: "POST",
  headers: { "Authorization": `Bearer ${process.env.API_KEY}` },
  body: formData,
});
console.log(await response.json());
```

Vous avez un fichier local ? Remplacez `url` par un champ multipart `file` — consultez [Importer un document](/developers/reference/documents#upload-a-document) dans la Référence pour la liste complète des paramètres, y compris `batch_name`, `template_id` et `password`.

La réponse renvoie l'ID du nouveau document et le lot dans lequel il a été placé — conservez `batch_name`, vous en aurez besoin dans les deux étapes suivantes :

```json
{
  "document_id": "3f9c9e2a-1b7d-4e2b-9a3e-2f5b6c7d8e9f",
  "batch_name": "260716-4K9P",
  "remaining_batch_capacity": 199
}
```

L'import d'un PDF multipage fonctionne de la même manière qu'une image, sauf que `document_id` est renvoyé sous forme de *tableau* — un document par page — car chaque page est traitée indépendamment.

## Étape 3 — Lancer le traitement

`POST /api/v1/batches/{batch_name}/process` déclenche l'extraction. Vous pouvez le pointer vers un [Template](/developers/reference/templates-fields) sauvegardé via `template_id`, ou — comme ici — déclarer les champs souhaités directement avec `fields` pour une exécution ponctuelle :

**cURL**

```bash
curl -X POST https://imagetotable.ai/api/v1/batches/260716-4K9P/process \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
        "fields": [
          {"name": "invoice_number"},
          {"name": "invoice_date"},
          {"name": "vendor_name"},
          {"name": "total_amount"}
        ]
      }'
```

**Python**

```python
import os
import requests

response = requests.post(
    "https://imagetotable.ai/api/v1/batches/260716-4K9P/process",
    headers={"Authorization": f"Bearer {os.environ['API_KEY']}"},
    json={
        "fields": [
            {"name": "invoice_number"},
            {"name": "invoice_date"},
            {"name": "vendor_name"},
            {"name": "total_amount"},
        ]
    },
)
print(response.json())
```

**Javascript**

```javascript
const response = await fetch("https://imagetotable.ai/api/v1/batches/260716-4K9P/process", {
  method: "POST",
  headers: {
    "Authorization": `Bearer ${process.env.API_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    fields: [
      { name: "invoice_number" },
      { name: "invoice_date" },
      { name: "vendor_name" },
      { name: "total_amount" },
    ],
  }),
});
console.log(await response.json());
```

Cela débite les crédits immédiatement (un document débité par appel) et met le(s) document(s) en file d'attente pour un traitement en arrière-plan :

```json
{
  "batch_name": "260716-4K9P",
  "queued": 1,
  "quality": "fast",
  "webhook_registered": false
}
```

Omettez complètement `fields` et `template_id` et l'API déduit elle-même des noms de colonnes raisonnables. `quality` est également facultatif — si vous l'omettez, le traitement utilise le réglage vitesse/qualité par défaut de votre compte (voir [Paramètres du compte et comportement de l'API](/developers/guides/account-settings)). `webhook_registered: false` signifie simplement que cet appel particulier n'incluait pas `webhook_url` — cela ne signifie pas qu'aucun webhook n'est enregistré pour ce lot ; consultez la [référence des lots](/developers/reference/batches#start-processing-a-batch) si vous en enregistrez un séparément via `PUT .../webhook`.

## Étape 4 — Interrogez et récupérez vos résultats

Le traitement est asynchrone — interrogez `GET /api/v1/batches/{batch_name}` jusqu'à ce que `all_done` soit `true` (quelques secondes pour un seul document), ou enregistrez un [webhook](/developers/guides/webhooks) au lieu d'interroger. Le cycle de vie complet est décrit dans le guide du [Modèle de tâche asynchrone](/developers/guides/async-model).

Une fois terminé, récupérez les résultats transformés :

**cURL**

```bash
curl https://imagetotable.ai/api/v1/batches/260716-4K9P/results \
  -H "Authorization: Bearer $API_KEY"
```

**Python**

```python
import os
import requests

response = requests.get(
    "https://imagetotable.ai/api/v1/batches/260716-4K9P/results",
    headers={"Authorization": f"Bearer {os.environ['API_KEY']}"},
)
print(response.json())
```

**Javascript**

```javascript
const response = await fetch("https://imagetotable.ai/api/v1/batches/260716-4K9P/results", {
  headers: { "Authorization": `Bearer ${process.env.API_KEY}` },
});
console.log(await response.json());
```

Le JSON de réponse n'est jamais segmenté par langue — sa structure ne change pas selon le client qui a envoyé la requête :

```json
{
  "batch_name": "260716-4K9P",
  "status": "succeeded",
  "created_at": "2026-07-16T09:12:03Z",
  "started_at": "2026-07-16T09:12:05Z",
  "completed_at": "2026-07-16T09:12:14Z",
  "documents": [
    {
      "document_id": "3f9c9e2a-1b7d-4e2b-9a3e-2f5b6c7d8e9f",
      "filename": "invoice.jpg",
      "status": "succeeded",
      "created_at": "2026-07-16T09:12:03Z",
      "started_at": "2026-07-16T09:12:05Z",
      "completed_at": "2026-07-16T09:12:14Z",
      "line_items": [
        {
          "invoice_number": "INV-1042",
          "invoice_date": "2026-06-30",
          "vendor_name": "Acme Supply Co.",
          "total_amount": "1,284.50"
        }
      ]
    }
  ]
}
```

`completed_at` est défini lorsqu'un document (ou, au niveau du lot, chaque document du lot) atteint un état terminal — `succeeded`, `failed` ou `canceled`. Il reste `null` tant qu'il est `queued` ou `processing`, et au niveau du lot, il reste également `null` jusqu'à ce que *tous* les documents du lot soient terminés, même si certains se sont terminés plus tôt.

## Prochaines étapes

À partir de là : lisez [Modèle de tâche asynchrone](/developers/guides/async-model) pour le cycle de vie complet des statuts, [Webhooks](/developers/guides/webhooks) pour être notifié au lieu d'interroger, et [Référence API](/developers/reference/) pour la liste complète des paramètres de chaque point d'accès.

---

Source: https://imagetotable.ai/fr/developers/quickstart