# Tâches asynchrones, traitements par lots et webhooks

`POST /generate` est le moyen le plus simple d'effectuer un essai : une seule requête, et l'image s'affiche. Utilisez les tâches asynchrones lorsque vous ne souhaitez pas maintenir une connexion ouverte, et les traitements par lots pour les opérations liées au catalogue. Les deux utilisent le même moteur, ont le même coût et remboursent chaque essai qui échoue.

|  | `POST /generate` (synchrone) | `POST /generations` (asynchrone) | `POST /batches` |
|---|---|---|---|
| Réponse | Le fichier PNG, dans la même requête | `202` avec un identifiant de tâche | `202` avec un identifiant de lot |
| Données d'entrée | Fichiers, base64 ou `garment_url` | Fichiers, base64 ou URL | `garment_url` et `person_url` par article |
| Résultat | Corps de la réponse | `GET /results/:id`, conservé pendant 7 jours | Idem, par article |
| Notification | Aucune nécessaire | Poll ou webhook | Webhook par élément, plus `batch.completed` |
| Crédits | Allocation gratuite ou crédits achetés | Crédits achetés | Crédits achetés, débités pour tous les éléments à la création du lot |
| Mode test | `?mock=true` | `?mock=true` | `?mock=true` |

## Lancer une tâche asynchrone

`POST https://www.tryoncloud.com/api/v1/generations`

Les mêmes en-têtes et champs d'image que [dans Générer](/docs/generate), ainsi que :

| Champ | Description |
|---|---|
| `person_url` | URL publique `https` de la photo de l'acheteur (alternative à un fichier ou à un code Base64) |
| `customer_id` | Votre identifiant pour l'utilisateur final, 128 caractères maximum. Utilisé lors de [la suppression d'un client](#delete-a-customers-data) |
| `metadata` | Un objet JSON d'une taille maximale de 2 Ko, renvoyé tel quel lors de l'exécution de la tâche et dans les webhooks |
| `webhook_url` | URL publique `https` permettant de recevoir les notifications `generation.completed` ou `generation.failed` |

```bash
curl -X POST https://www.tryoncloud.com/api/v1/generations \
  -H "X-API-KEY: $TRYONCLOUD_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -F "garment_image=@shirt.jpg" \
  -F "person_image=@person.jpg" \
  -F "customer_id=shopper_123" \
  -F "webhook_url=https://example.com/hooks/tryoncloud"
```

**202 Accepté**

```json
{
  "id": "6f0e3c1a-0d6a-4f7e-9a7b-2b2a1d3c4e5f",
  "object": "generation",
  "status": "queued",
  "mock": false,
  "batch_id": null,
  "customer_id": "shopper_123",
  "metadata": null,
  "result_id": null,
  "result_url": null,
  "error": null,
  "created_at": "2026-11-18T10:00:00.000Z",
  "completed_at": null
}
```

Le traitement commence dès l'envoi de la réponse. Vos images sont traitées en mémoire et ne sont jamais enregistrées ; seul le résultat final est conservé, pendant 7 jours.

## Consulter une offre d'emploi

`GET https://www.tryoncloud.com/api/v1/generations/:id`

`status` passe de `queued` à `processing`, puis à `completed` ou `failed`. Une tâche terminée dispose d'un `result_url` ; téléchargez-la à l'aide de votre clé :

```bash
curl https://www.tryoncloud.com/api/v1/results/RESULT_ID -H "X-API-KEY: $TRYONCLOUD_API_KEY" -o result.png
```

Une tâche ayant échoué présente l'un des codes d'erreur suivants : `error.code` : `CONTENT_FILTERED`, `GENERATION_FAILED` ou `INPUT_FETCH_FAILED`. Le crédit est remboursé dans tous les cas.

## Lots

`POST https://www.tryoncloud.com/api/v1/batches`, avec un corps JSON contenant jusqu'à 500 éléments :

```json
{
  "items": [
    { "garment_url": "https://cdn.example.com/kurta-1.jpg", "person_url": "https://cdn.example.com/model-a.jpg", "customer_id": "sku-1001" },
    { "garment_url": "https://cdn.example.com/saree-7.jpg", "person_url": "https://cdn.example.com/model-b.jpg" }
  ],
  "webhook_url": "https://example.com/hooks/tryoncloud"
}
```

- Un crédit est débité par article lors de la création du lot. Si votre solde est insuffisant, rien n'est créé (code `402 NO_CREDITS`).
- La requête `GET /batches/:id` renvoie le nombre d'éléments et la liste complète de ceux-ci.
- `DELETE /batches/:id` annule les tâches qui n'ont pas encore démarré et procède à leur remboursement. Les tâches en cours d'exécution sont menées à terme.
- Chaque élément envoie son propre webhook, et le lot envoie `batch.completed` une fois que chaque élément a un résultat.

## Webhooks

Nous envoyons une requête `POST` au format JSON vers votre `webhook_url` :

```json
{
  "event": "generation.completed",
  "created_at": "2026-11-18T10:00:21.000Z",
  "data": { "id": "6f0e3c1a-...", "object": "generation", "status": "completed", "result_url": "https://www.tryoncloud.com/api/v1/results/...", "customer_id": "shopper_123", "metadata": null }
}
```

Événements : `generation.completed`, `generation.failed`, `batch.completed` et `webhook.test` depuis le tableau de bord.

En-têtes : `x-tryoncloud-event`, `x-tryoncloud-delivery-id` (déduplication sur cet en-tête), `x-tryoncloud-timestamp` et `x-tryoncloud-signature-v2`.

**Point de terminaison du compte.** Au lieu d'envoyer l'`webhook_url` à chaque requête, enregistrez un point de terminaison dans le tableau de bord (**Clés API > Webhooks**) et sélectionnez les événements qu'il doit recevoir. L'`webhook_url` propre à chaque requête prévaut toujours. **La commande Envoyer un événement de test** envoie un événement signé `webhook.test` vers le point de terminaison enregistré.

**Vérifiez chaque livraison.** Votre clé de signature se trouve sur la même carte (montrez-la, copiez-la ou faites-la tourner). La signature est un HMAC-SHA256 de `<timestamp>.<raw body>` :

```js
import crypto from "node:crypto"

export function verifyTryOnCloud(rawBody, headers, secret) {
  const ts = headers["x-tryoncloud-timestamp"]
  const sig = (headers["x-tryoncloud-signature-v2"] || "").replace("sha256=", "")
  if (!ts || Math.abs(Date.now() / 1000 - Number(ts)) > 300) return false // reject old deliveries
  const expected = crypto.createHmac("sha256", secret).update(`${ts}.${rawBody}`).digest("hex")
  return sig.length === expected.length && crypto.timingSafeEqual(Buffer.from(sig), Buffer.from(expected))
}
```

Répondez avec n'importe quel code `2xx` dans les 8 secondes. Les autres réponses et les délais d'expiration font l'objet de nouvelles tentatives avec un délai d'attente (1 minute, 5 minutes, 30 minutes, 2 heures, 6 heures, 24 heures). Les URL de webhook doivent être publiques (`https`) et utiliser le port standard ; les adresses privées et internes sont refusées, tant lors de l'enregistrement de l'URL que lors de l'envoi, et les redirections ne sont pas suivies.

## Supprimer les données d'un client

`DELETE https://www.tryoncloud.com/api/v1/customers/:customer_id`

Supprime tous les résultats enregistrés pour cet `customer_id` sur votre compte et efface cet identifiant de vos enregistrements. À utiliser lorsqu'un utilisateur final demande à être « oublié » (GDPR, DPDP).

```json
{ "object": "customer_deletion", "customer_id": "shopper_123", "results_deleted": 3, "records_cleared": 4 }
```

## Limites

|  |  |
|---|---|
| Création de tâches et de lots | Est pris en compte dans la limite de 300 requêtes par minute et par clé |
| Tâches asynchrones s'exécutant simultanément | 50 par compte (`429 TOO_MANY_JOBS`) ; les lots sont distincts |
| Taille du lot | 500 articles |
| Résultats | Conservé pendant 7 jours |
| Métadonnées | Objet JSON, 2 Ko |
