# Référence API des lots — Démarrer, Exporter & Supprimer

> Lancez l'extraction sur un lot de documents téléchargés, listez et filtrez vos lots, interrogez l'état agrégé, récupérez les résultats JSON restructurés, exportez vers Excel/Word et supprimez des lots pour l'API v1 d'ImageToTable.ai.

Un **lot** est un groupe nommé d'un ou plusieurs [documents](/developers/reference/documents) que vous traitez, interrogez et dont vous récupérez les résultats ensemble. Vous ne créez pas explicitement un lot — il est créé implicitement la première fois que vous téléchargez un document avec ce `batch_name` (voir [Télécharger un document](/developers/reference/documents#upload-a-document)).

## Démarrer le traitement d'un lot

Lance l'extraction sur chaque document éligible actuellement dans le lot (tout document qui n'est pas déjà `processing` ou `succeeded`). C'est le point de terminaison qui consomme réellement des crédits — un par document mis en file d'attente.

`POST /api/v1/batches/{batch_name}/process`

### Paramètres

| Nom | Emplacement | Type | Description |
| --- | --- | --- | --- |
| batch_name | chemin | chaîne | Le lot à traiter. |
| template_id | corps (JSON) | entier, optionnel | Un modèle enregistré à appliquer. Prioritaire sur fields si les deux sont fournis. |
| fields | corps (JSON) | tableau, optionnel | Liste de champs ad hoc pour cette exécution uniquement — [{"name": "...", "format_requirement": "..."}] ou un simple tableau de noms de chaînes. Ignoré si template_id est fourni. Omettez les deux pour laisser le modèle inférer les colonnes lui-même. |
| quality | corps (JSON) | chaîne, optionnel | "fast" ou "high" . Omettez pour utiliser le paramètre thinking_type de votre compte — voir Paramètres du compte et comportement de l'API . |
| webhook_url | corps (JSON) | chaîne, optionnel | Enregistre (ou met à jour) le callback d'achèvement de ce lot dans le même appel — équivalent à appeler également Enregistrer un webhook de lot . Doit être http:// ou https:// . |
| Idempotency-Key | en-tête, optionnel | chaîne | Fortement recommandé — ce point de terminaison déduit des crédits. Voir Idempotence . |

`quality` est le seul paramètre du compte que l'API vous permet de remplacer par appel — tous les autres réglages au niveau du compte (bbox auto-annotation, politique de conservation) sont lus depuis votre compte et ne peuvent pas être remplacés par requête. Consultez [Paramètres du compte et comportement de l'API](/developers/guides/account-settings) pour une vue d'ensemble, y compris pourquoi `auto_annotate_bbox` peut faire que cet appel vous facture également l'annotation bbox, même si vous n'avez jamais appelé ce point de terminaison.

**Le champ `webhook_registered` de la réponse ne concerne que cet appel spécifique** — il est `true` si et seulement si *cette* requête incluait `webhook_url`, et non si le lot a un webhook en général. Un lot dont le webhook a été configuré précédemment via [Enregistrer un webhook de lot](/developers/reference/webhooks) (et non répété ici) déclenchera correctement son callback à la fin, mais ce champ renvoie toujours `false` pour cet appel — il ne vérifie pas si un `BatchWebhook` existe déjà. Ne considérez pas un `false` ici comme signifiant « aucun webhook ne se déclenchera pour ce lot. »

Appeler à nouveau ce point de terminaison sur un lot que vous avez déjà traité et dont vous avez été notifié — après y avoir téléchargé plus de documents — réarme automatiquement le webhook de ce lot s'il s'était déjà déclenché, afin que la fin de la nouvelle vague vous notifie également. Aucun appel supplémentaire n'est nécessaire pour cela ; consultez la section « Retraiter un lot » du [guide des webhooks](/developers/guides/webhooks#reprocessing-a-batch) pour la sémantique exacte (y compris ce qui se passe si deux vagues se chevauchent).

### Erreurs possibles

- `missing_api_key` / `invalid_api_key` / `plan_required` — voir [Gestion des erreurs](/developers/guides/errors).
- `batch_not_found` — aucun document n'existe sous ce `batch_name` sur votre compte.
- `invalid_parameter` — valeur incorrecte de `quality`/`webhook_url`/`template_id`, ou aucun document dans le lot n'est actuellement éligible au traitement (tous déjà terminés/en cours, ou le lot est vide).
- `template_not_found`
- `insufficient_credits` — pas assez de crédits disponibles pour couvrir les documents en file d'attente.

## Lister les lots

Renvoie une liste paginée et filtrable de vos lots — l'équivalent du « Files Filter » pour les consommateurs de l'API. Cela ne renvoie que des résumés (`document_count`, `status` agrégé) ; utilisez [Obtenir les résultats d'un lot](#get-batch-results) pour les données complètes par document d'un lot spécifique.

`GET /api/v1/batches`

### Paramètres

| Nom | Emplacement | Type | Description |
| --- | --- | --- | --- |
| source | query, facultatif | string | Une valeur parmi direct , collect , email_inbox , api (téléversé via POST /documents , distinct de direct qui est l'application web principale), ou share (un alias couvrant à la fois collect et email_inbox ). Omettre pour toutes les sources. |
| q | query, facultatif | string | Correspondance partielle insensible à la casse avec les noms de fichiers dans le lot. |
| date_from | query, facultatif | string ( YYYY-MM-DD ) | Limite inférieure inclusive sur la date de téléversement. |
| date_to | query, facultatif | string ( YYYY-MM-DD ) | Limite supérieure inclusive sur la date de téléversement (fin de journée). |
| status | query, facultatif | string | Liste séparée par des virgules des statuts publics ( queued,processing,succeeded,failed,canceled ) pour filtrer. |
| template_id | query, facultatif | integer | Uniquement les lots ayant utilisé ce modèle. |
| mode | query, facultatif | string | La seule valeur acceptée pour l'instant est "table" (le seul mode actuellement pris en charge par v1). Réservé pour de futurs modes d'extraction. |
| limit | query, facultatif | integer | 1–100. Par défaut 20. |
| page_token | query, facultatif | string | Curseur opaque provenant du next_page_token d'une réponse précédente. Voir Pagination . |

### Erreurs possibles

- `missing_api_key` / `invalid_api_key` / `plan_required` — voir [Gestion des erreurs](/developers/guides/errors).
- `invalid_parameter` — `mode`, `limit`, `status` ou `page_token` invalide.

## Obtenir le statut d'un lot

Statut agrégé léger pour un lot — comptages par statut public plus un indicateur `all_done`, utile pour une boucle d'interrogation économique qui n'a pas encore besoin de la charge utile complète des résultats.

`GET /api/v1/batches/{batch_name}`

### Paramètres

| Nom | Emplacement | Type | Description |
| --- | --- | --- | --- |
| batch_name | path | string | Le lot à vérifier. |

### Erreurs possibles

- `missing_api_key` / `invalid_api_key` / `plan_required` — voir [Gestion des erreurs](/developers/guides/errors).
- `batch_not_found`

## Obtenir les résultats d'un lot

Le moyen principal de récupérer les données extraites. Chaque document du lot est renvoyé avec ses `line_items` remodelés — un tableau d'objets `{field_name: value}`, un par ligne extraite. Les valeurs au niveau des champs sont des scalaires bruts par défaut (une chaîne, un nombre, etc.).

`GET /api/v1/batches/{batch_name}/results`

### Paramètres

| Nom | Emplacement | Type | Description |
| --- | --- | --- | --- |
| batch_name | path | string | Le lot dont il faut récupérer les résultats. |
| include | query, optionnel | string | "bbox" — lorsqu'il est défini, chaque valeur de champ devient {"value": ..., "bbox": {...}|null} au lieu d'un scalaire brut, et chaque document reçoit un champ bbox_status . Voir ci-dessous — cela ne déclenche jamais un nouveau job bbox, cela renvoie uniquement ce qui a déjà été calculé. |

`?include=bbox` lit uniquement les résultats déjà calculés — il n'appelle pas [Déclencher l'annotation bbox](/developers/reference/documents#trigger-bbox-annotation) pour vous. Si bbox n'a jamais été déclenché pour un document (manuellement, ou via le paramètre `auto_annotate_bbox` de votre compte), les champs de ce document sont simplement renvoyés avec `"bbox": null`.

**Les champs de localisation pure sont une troisième forme distincte.** Certains champs de modèle demandent au modèle de localiser quelque chose plutôt que de transcrire du texte (par exemple, « localiser la photo du portrait »). Pour ces champs, la valeur entière *est* une localisation — donc au lieu d'un scalaire ou de la paire `{"value","bbox"}` ci-dessus, vous obtenez `{"type": "image_region", "bbox": {...}, "image_url": "..."}`, **que `?include=bbox` soit défini ou non** — la boîte n'est pas une métadonnée optionnelle ici, c'est le seul contenu du champ. `image_url` pointe vers un JPEG recadré prêt à être récupéré (voir [Obtenir l'image d'un document](/developers/reference/documents#get-a-document-image)) pour que vous n'ayez pas à recadrer l'original vous-même à partir de quatre nombres.

Chaque objet `bbox` — quelle que soit sa forme — utilise `"unit": "normalized"` : les coordonnées sont des flottants de 0 à 1 par rapport à la largeur/hauteur de la page, et non des pixels ou une échelle de 0 à 1000. Consultez le guide [Boîtes englobantes](/developers/guides/bbox) pour la mise en garde sur la précision — ces coordonnées proviennent directement du modèle sans vérification au niveau du pixel, considérez-les donc comme « approximatives » plutôt qu'exactes sur des documents denses ou complexes.

### Erreurs possibles

- `missing_api_key` / `invalid_api_key` / `plan_required` — voir [Gestion des erreurs](/developers/guides/errors).
- `batch_not_found`

## Exporter un lot

Un téléchargement pratique — `results` ci-dessus est le format structuré canonique autour duquel cette API est construite ; ce point de terminaison existe pour extraire les mêmes données dans un tableur sans écrire vous-même de code de remodelage. xlsx uniquement — v1 ne prend en charge que le mode table (extraction), et l'export Word (docx) sur l'application principale est exclusivement la sortie native du mode page_word (une invite et une forme de résultat entièrement différentes), que v1 n'expose pas. Il n'y a pas d'option « données de tableau en tant que document Word » ici.

`GET /api/v1/batches/{batch_name}/export`

### Paramètres

| Nom | Emplacement | Type | Description |
| --- | --- | --- | --- |
| batch_name | chemin | chaîne | Le lot à exporter. |
| format | requête, optionnel | chaîne | Seul xlsx (la valeur par défaut) est accepté. |

La réponse est un téléchargement de fichier (`Content-Type: application/vnd.openxmlformats-officedocument.spreadsheetml.sheet`), pas du JSON — il n'y a pas d'exemple de réponse JSON pour ce point de terminaison.

### Erreurs possibles

- `missing_api_key` / `invalid_api_key` / `plan_required` — voir [Gestion des erreurs](/developers/guides/errors).
- `batch_not_found`
- `invalid_parameter` (`param: "format"`) — toute valeur autre que `xlsx`.

## Supprimer un lot

Supprime définitivement tous les documents du lot. Tout document encore `queued` est remboursé avant la suppression. Cela supprime également l'enregistrement du webhook du lot (le cas échéant) et toute tâche d'annotation bbox liée à ses documents.

`DELETE /api/v1/batches/{batch_name}`

### Paramètres

| Nom | Emplacement | Type | Description |
| --- | --- | --- | --- |
| batch_name | chemin | string | Le lot à supprimer. |

### Erreurs possibles

- `missing_api_key` / `invalid_api_key` / `plan_required` — voir [Gestion des erreurs](/developers/guides/errors).
- `batch_not_found` — contrairement à d'autres ressources, la suppression d'un `batch_name` qui ne vous appartient pas (ou qui n'existe pas) renvoie une erreur 404 ici, et non une opération silencieuse sans effet.

## Code Examples

### Démarrer le traitement d'un lot

POST /api/v1/batches/{batch_name}/process

**cURL**

```bash
curl -X POST https://imagetotable.ai/api/v1/batches/july-invoices/process \
  -H "Authorization: Bearer $API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
        "fields": [
          {"name": "invoice_number"},
          {"name": "invoice_date", "format_requirement": "YYYY-MM-DD"},
          {"name": "total_amount"}
        ],
        "quality": "high",
        "webhook_url": "https://example.com/webhooks/imagetotable"
      }'
```

**Python**

```python
import os
import uuid
import requests

response = requests.post(
    "https://imagetotable.ai/api/v1/batches/july-invoices/process",
    headers={
        "Authorization": f"Bearer {os.environ['API_KEY']}",
        "Idempotency-Key": str(uuid.uuid4()),
    },
    json={
        "fields": [
            {"name": "invoice_number"},
            {"name": "invoice_date", "format_requirement": "YYYY-MM-DD"},
            {"name": "total_amount"},
        ],
        "quality": "high",
        "webhook_url": "https://example.com/webhooks/imagetotable",
    },
)
print(response.json())
```

**Javascript**

```javascript
const response = await fetch("https://imagetotable.ai/api/v1/batches/july-invoices/process", {
  method: "POST",
  headers: {
    "Authorization": `Bearer ${process.env.API_KEY}`,
    "Idempotency-Key": crypto.randomUUID(),
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    fields: [
      { name: "invoice_number" },
      { name: "invoice_date", format_requirement: "YYYY-MM-DD" },
      { name: "total_amount" },
    ],
    quality: "high",
    webhook_url: "https://example.com/webhooks/imagetotable",
  }),
});
console.log(await response.json());
```

### Réponse

```json
{
  "batch_name": "july-invoices",
  "queued": 3,
  "quality": "high",
  "webhook_registered": true
}
```

### Démarrer le traitement — avec un modèle enregistré

POST /api/v1/batches/{batch_name}/process

L'autre des deux façons de spécifier quoi extraire — `template_id` a priorité sur `fields` si vous envoyez les deux, et c'est le choix le plus courant une fois que vous réutilisez la même liste de colonnes d'un lot à l'autre au lieu de la déclarer ad-hoc à chaque fois.

**cURL**

```bash
curl -X POST https://imagetotable.ai/api/v1/batches/july-invoices/process \
  -H "Authorization: Bearer $API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{"template_id": 42}'
```

**Python**

```python
import os
import uuid
import requests

response = requests.post(
    "https://imagetotable.ai/api/v1/batches/july-invoices/process",
    headers={
        "Authorization": f"Bearer {os.environ['API_KEY']}",
        "Idempotency-Key": str(uuid.uuid4()),
    },
    json={"template_id": 42},
)
print(response.json())
```

**Javascript**

```javascript
const response = await fetch("https://imagetotable.ai/api/v1/batches/july-invoices/process", {
  method: "POST",
  headers: {
    "Authorization": `Bearer ${process.env.API_KEY}`,
    "Idempotency-Key": crypto.randomUUID(),
    "Content-Type": "application/json",
  },
  body: JSON.stringify({ template_id: 42 }),
});
console.log(await response.json());
```

### Réponse

```json
{
  "batch_name": "july-invoices",
  "queued": 3,
  "quality": "fast",
  "webhook_registered": false
}
```

`quality` est ici `"fast"` car il a été omis de la requête et est revenu au paramètre `thinking_type` du compte, et non parce qu'un modèle a été utilisé — `template_id`/`fields` et `quality` sont des paramètres indépendants.

### Lister les lots

GET /api/v1/batches

**cURL**

```bash
curl "https://imagetotable.ai/api/v1/batches?status=succeeded&limit=20" \
  -H "Authorization: Bearer $API_KEY"
```

**Python**

```python
import os
import requests

response = requests.get(
    "https://imagetotable.ai/api/v1/batches",
    headers={"Authorization": f"Bearer {os.environ['API_KEY']}"},
    params={"status": "succeeded", "limit": 20},
)
print(response.json())
```

**Javascript**

```javascript
const url = new URL("https://imagetotable.ai/api/v1/batches");
url.searchParams.set("status", "succeeded");
url.searchParams.set("limit", "20");

const response = await fetch(url, {
  headers: { "Authorization": `Bearer ${process.env.API_KEY}` },
});
console.log(await response.json());
```

### Réponse

```json
{
  "data": [
    {
      "batch_name": "july-invoices",
      "status": "succeeded",
      "document_count": 3,
      "created_at": "2026-07-16T09:12:03+00:00"
    }
  ],
  "has_more": false,
  "next_page_token": null
}
```

### Obtenir le statut d'un lot

GET /api/v1/batches/{batch_name}

**cURL**

```bash
curl https://imagetotable.ai/api/v1/batches/july-invoices \
  -H "Authorization: Bearer $API_KEY"
```

**Python**

```python
import os
import requests

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

**Javascript**

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

### Réponse

```json
{
  "batch_name": "july-invoices",
  "document_count": 3,
  "status_counts": {
    "queued": 0,
    "processing": 0,
    "succeeded": 3,
    "failed": 0,
    "canceled": 0
  },
  "all_done": true,
  "created_at": "2026-07-16T09:12:03+00:00"
}
```

### Obtenir les résultats d'un lot

GET /api/v1/batches/{batch_name}/results

**cURL**

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

**Python**

```python
import os
import requests

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

**Javascript**

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

### Réponse — par défaut (sans include)

```json
{
  "batch_name": "july-invoices",
  "status": "succeeded",
  "created_at": "2026-07-16T09:12:03+00:00",
  "started_at": "2026-07-16T09:12:05+00:00",
  "completed_at": "2026-07-16T09:12:14+00:00",
  "documents": [
    {
      "document_id": "8f14e45f-ceea-467e-9de1-a3e9c93a9c95",
      "filename": "invoice_042.jpg",
      "status": "succeeded",
      "created_at": "2026-07-16T09:12:03+00:00",
      "started_at": "2026-07-16T09:12:05+00:00",
      "completed_at": "2026-07-16T09:12:14+00:00",
      "line_items": [
        {
          "invoice_number": "INV-1042",
          "invoice_date": "2026-07-01",
          "total_amount": "1,204.50"
        }
      ]
    }
  ]
}
```

### Résultats du lot — avec bbox

GET /api/v1/batches/{batch_name}/results?include=bbox

**cURL**

```bash
curl "https://imagetotable.ai/api/v1/batches/july-invoices/results?include=bbox" \
  -H "Authorization: Bearer $API_KEY"
```

**Python**

```python
import os
import requests

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

**Javascript**

```javascript
const url = new URL("https://imagetotable.ai/api/v1/batches/july-invoices/results");
url.searchParams.set("include", "bbox");

const response = await fetch(url, {
  headers: { "Authorization": `Bearer ${process.env.API_KEY}` },
});
console.log(await response.json());
```

### Réponse — `?include=bbox`

```json
{
  "batch_name": "july-invoices",
  "status": "succeeded",
  "created_at": "2026-07-16T09:12:03+00:00",
  "started_at": "2026-07-16T09:12:05+00:00",
  "completed_at": "2026-07-16T09:12:14+00:00",
  "documents": [
    {
      "document_id": "8f14e45f-ceea-467e-9de1-a3e9c93a9c95",
      "filename": "invoice_042.jpg",
      "status": "succeeded",
      "created_at": "2026-07-16T09:12:03+00:00",
      "started_at": "2026-07-16T09:12:05+00:00",
      "completed_at": "2026-07-16T09:12:14+00:00",
      "bbox_status": "succeeded",
      "line_items": [
        {
          "invoice_number": {
            "value": "INV-1042",
            "bbox": {"x1": 0.121, "y1": 0.084, "x2": 0.418, "y2": 0.112, "unit": "normalized"}
          },
          "total_amount": {
            "value": "1,204.50",
            "bbox": null
          },
          "portrait_photo": {
            "type": "image_region",
            "bbox": {"x1": 0.740, "y1": 0.060, "x2": 0.920, "y2": 0.260, "unit": "normalized"},
            "image_url": "https://imagetotable.ai/api/v1/documents/8f14e45f-ceea-467e-9de1-a3e9c93a9c95/image?crop=0.7241%2C0.0426%2C0.9359%2C0.2774"
          }
        }
      ]
    }
  ]
}
```

### Exporter un lot

GET /api/v1/batches/{batch_name}/export

**cURL**

```bash
curl "https://imagetotable.ai/api/v1/batches/july-invoices/export?format=xlsx" \
  -H "Authorization: Bearer $API_KEY" \
  -o july-invoices.xlsx
```

**Python**

```python
import os
import requests

response = requests.get(
    "https://imagetotable.ai/api/v1/batches/july-invoices/export",
    headers={"Authorization": f"Bearer {os.environ['API_KEY']}"},
    params={"format": "xlsx"},
)
with open("july-invoices.xlsx", "wb") as f:
    f.write(response.content)
```

**Javascript**

```javascript
import { writeFile } from "node:fs/promises";

const url = new URL("https://imagetotable.ai/api/v1/batches/july-invoices/export");
url.searchParams.set("format", "xlsx");

const response = await fetch(url, {
  headers: { "Authorization": `Bearer ${process.env.API_KEY}` },
});
await writeFile("july-invoices.xlsx", Buffer.from(await response.arrayBuffer()));
```

### Supprimer un lot

DELETE /api/v1/batches/{batch_name}

**cURL**

```bash
curl -X DELETE https://imagetotable.ai/api/v1/batches/july-invoices \
  -H "Authorization: Bearer $API_KEY"
```

**Python**

```python
import os
import requests

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

**Javascript**

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

### Réponse

```json
{
  "batch_name": "july-invoices",
  "deleted": 3,
  "canceled": 1
}
```

---

Source: https://imagetotable.ai/fr/developers/reference/batches