# Écriture manuscrite vers Excel

Convertissez des tableaux, journaux ou registres manuscrits en classeurs XLSX modifiables grâce à une reconnaissance adaptée à l’écriture manuscrite.

Documentation officielle: https://img2excel.net/fr/docs/api/handwriting-to-excel

`POST /api/v1/handwriting-to-excel`

Convertissez des tableaux, journaux ou registres manuscrits en classeurs XLSX modifiables grâce à une reconnaissance adaptée à l’écriture manuscrite. L’interface synchrone attend la fin de la conversion. Les conversions échouées ne consomment pas de crédits.

Utilisez une image nette, uniformément éclairée, montrant le tableau entier. Vérifiez les noms, les dates et les valeurs extraites avant d’utiliser le classeur.

## Requête

### En-têtes

| En-tête | Obligatoire | Description |
| --- | --- | --- |
| `Authorization` | Oui | `Bearer $IMG2EXCEL_API_KEY`. Utilisez une clé API côté serveur. |
| `Content-Type` | Oui | `multipart/form-data` avec une délimitation boundary. Laissez le client HTTP définir cet en-tête lors de l’envoi du fichier. |
| `Idempotency-Key` | Non | Clé d’idempotence de 200 caractères maximum. Recommandée pour chaque envoi ; réutilisez la même valeur pour retenter le même envoi. |

### Corps

| Champ | Type | Obligatoire | Description |
| --- | --- | --- | --- |
| `file` | Fichier binaire | Oui | Une image PNG, JPG ou JPEG de 4 Mo maximum. |

Envoyez l’image sous forme de fichier, pas dans un corps JSON ni sous forme d’URL. Cette interface sélectionne automatiquement le profil de reconnaissance.

## Exemples de requêtes

Exécutez ces exemples sur votre serveur après avoir défini `IMG2EXCEL_API_KEY`. Pour Python, installez `requests` avec `pip install requests`. Node.js 20 ou ultérieur est requis.


### cURL

```bash
curl --fail-with-body --max-time 330 -i https://img2excel.net/api/v1/handwriting-to-excel \
  -H "Authorization: Bearer $IMG2EXCEL_API_KEY" \
  -H "Idempotency-Key: handwriting-to-excel-001" \
  -F "file=@handwritten-log.jpg"
```


### Python

```python
import os
import requests

with open("handwritten-log.jpg", "rb") as image:
    response = requests.post(
        "https://img2excel.net/api/v1/handwriting-to-excel",
        headers={
            "Authorization": f"Bearer {os.environ['IMG2EXCEL_API_KEY']}",
            "Idempotency-Key": "handwritten-log-001",
        },
        files={"file": ("handwritten-log.jpg", image, "image/jpeg")},
        timeout=330,
    )

response.raise_for_status()
job = response.json()
print(job["result"]["download_url"])
```


### Node.js

```ts
import { readFile } from 'node:fs/promises';

const file = await readFile('handwritten-log.jpg');
const form = new FormData();
form.set('file', new File([file], 'handwritten-log.jpg', { type: 'image/jpeg' }));

const response = await fetch('https://img2excel.net/api/v1/handwriting-to-excel', {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${process.env.IMG2EXCEL_API_KEY}`,
    'Idempotency-Key': 'handwritten-log-001',
  },
  body: form,
  signal: AbortSignal.timeout(330_000),
});

if (!response.ok) throw new Error(await response.text());
const job = await response.json();
console.log(job.result.download_url);
```




## Réponse

**200 OK** — conversion terminée. Téléchargez le fichier Excel via `result.download_url`. L’URL de cet exemple est fictive.

```json
{
  "id": "job_0123456789abcdef0123456789abcdef",
  "type": "handwriting-to-excel",
  "status": "succeeded",
  "credits_reserved": 2,
  "credits_used": 2,
  "created_at": "2026-10-04T09:00:00.000Z",
  "completed_at": "2026-10-04T09:00:08.000Z",
  "result": {
    "filename": "table_result.xlsx",
    "content_type": "application/vnd.openxmlformats-officedocument.spreadsheetml.sheet",
    "size_bytes": 17330,
    "download_url": "https://signed-storage-url.example/...",
    "download_url_expires_in": 900
  }
}
```

**422 Unprocessable Entity** — échec de conversion. La réponse contient l’ID de tâche, `status: "failed"`, `error.code` et `error.message`. Aucun crédit n’est consommé en cas d’échec.

Si la clé d’idempotence correspond à une conversion existante, `Idempotent-Replayed: true` est renvoyé. Une tâche terminée renvoie `200`, un résultat expiré `410`. Si la tâche initiale attend ou s’exécute encore, la nouvelle tentative renvoie `202` et un en-tête `Location`. Consultez cette URL au lieu de lancer une nouvelle conversion.

Consultez [Tâches et erreurs](https://img2excel.net/fr/docs/api/jobs) pour tous les champs de réponse. Les appels synchrones et asynchrones partagent les tâches, les limites de compte et les clés d’idempotence pour chaque type de conversion.

L’interface synchrone attend la fin de la conversion. Réglez le délai d’attente du client HTTP sur 330 secondes. En cas d’expiration de la connexion, réessayez avec la même `Idempotency-Key`. Une nouvelle clé lance une nouvelle conversion.

## Conversion asynchrone (facultative)

Utilisez `POST /api/v1/handwriting-to-excel/jobs` pour envoyer sans attendre. Les champs et l’authentification sont identiques. Une nouvelle tâche renvoie `202`, son ID et l’en-tête `Location`. Interrogez `GET /api/v1/jobs/{job_id}` toutes les 2 à 3 secondes jusqu’à `succeeded`, `failed` ou `expired`. En cas de réussite, téléchargez `result.download_url`. Un script est disponible dans [Tâches et erreurs](https://img2excel.net/fr/docs/api/jobs).

---

OpenAPI 3.1: https://img2excel.net/api/openapi.json
Documentation API complète: https://img2excel.net/fr/docs/api/text/llms-full.txt