# Operazioni asincrone, elaborazioni in batch e webhook

`POST /generate` è il modo più semplice per eseguire una prova: basta una richiesta e l'immagine viene restituita. Utilizza i processi asincroni quando non vuoi mantenere aperta una connessione e i batch per il lavoro sul catalogo. Entrambi utilizzano lo stesso motore, hanno lo stesso costo e rimborsano ogni prova che non va a buon fine.

|  | `POST /generate` (sincrono) | `POST /generations` (asincrono) | `POST /batches` |
|---|---|---|---|
| Risposta | Il PNG, nella stessa richiesta | `202` con un ID lavoro | `202` con un ID batch |
| Dati in ingresso | File, base64 o `garment_url` | File, codici base64 o URL | `garment_url` e `person_url` per ogni articolo |
| Risultato | Corpo della risposta | `GET /results/:id`, conservato per 7 giorni | Idem, per articolo |
| Notifica | Non necessario | Polling o webhook | Webhook per ogni elemento, oltre a `batch.completed` |
| Crediti | Quota gratuita o crediti acquistati | Crediti acquistati | Crediti acquistati, addebitati per tutti gli elementi alla creazione del batch |
| Modalità di prova | `?mock=true` | `?mock=true` | `?mock=true` |

## Avvia un processo asincrono

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

Stesse intestazioni e stessi campi immagine presenti in [Genera](/docs/generate), oltre a:

| Campo | Descrizione |
|---|---|
| `person_url` | URL pubblico `https` della foto dell'acquirente (in alternativa a un file o a un codice base64) |
| `customer_id` | Il tuo ID per l'utente finale, fino a 128 caratteri. Utilizzato per [l'eliminazione del cliente](#delete-a-customers-data) |
| `metadata` | Un oggetto JSON di dimensioni massime pari a 2 KB, restituito senza modifiche sia nel processo che nei webhook |
| `webhook_url` | URL pubblico `https` per ricevere `generation.completed` o `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 Accettato**

```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
}
```

L'elaborazione ha inizio non appena viene inviata la risposta. Le immagini vengono elaborate in memoria e non vengono mai salvate; viene conservato solo il risultato finale, per 7 giorni.

## Verifica un'offerta di lavoro

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

Lo `status` passa da `queued` a `processing`, per poi diventare `completed` o `failed`. Un lavoro completato ha un `result_url`; scaricalo utilizzando la tua chiave:

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

Un'operazione non riuscita presenta uno dei seguenti codici di errore: `error.code`: `CONTENT_FILTERED`, `GENERATION_FAILED` o `INPUT_FETCH_FAILED`. In ogni caso, il credito viene rimborsato.

## Lotti

`POST https://www.tryoncloud.com/api/v1/batches` con un corpo JSON contenente fino a 500 elementi:

```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"
}
```

- Al momento della creazione del lotto viene addebitato un credito per ogni articolo. Se il saldo è insufficiente, non viene creato nulla (codice `402 NO_CREDITS`).
- `GET /batches/:id` restituisce il numero di elementi e tutti gli elementi stessi.
- `DELETE /batches/:id` annulla le attività che non sono ancora state avviate e ne rimborsa il costo. Le attività in corso vengono portate a termine.
- Ogni elemento invia il proprio webhook, mentre il batch invia `batch.completed` una volta che tutti gli elementi hanno un esito.

## Webhook

Invieremo un request `POST` in formato JSON al tuo `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 }
}
```

Eventi: `generation.completed`, `generation.failed`, `batch.completed` e `webhook.test` dalla dashboard.

Intestazioni: `x-tryoncloud-event`, `x-tryoncloud-delivery-id` (effettuare la deduplicazione su questa), `x-tryoncloud-timestamp` e `x-tryoncloud-signature-v2`.

**Endpoint dell'account.** Anziché inviare l'`webhook_url` con ogni richiesta, salva un endpoint nella dashboard (**Chiavi API > Webhook**) e seleziona gli eventi che deve ricevere. L'`webhook_url` specificato nella richiesta ha sempre la precedenza. **Invia** un evento **di prova** firmato `webhook.test` all'endpoint salvato.

**Verifica ogni consegna.** Il tuo segreto di firma si trova sulla stessa scheda (mostralo, copialo o ruotalo). La firma è un HMAC-SHA256 di `<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))
}
```

Rispondere con qualsiasi codice `2xx` entro 8 secondi. Le altre risposte e i timeout vengono riprovati con un backoff (1 minuto, 5 minuti, 30 minuti, 2 ore, 6 ore, 24 ore). Gli URL dei webhook devono essere pubblici `https` sulla porta standard; gli indirizzi privati e interni vengono rifiutati, sia al momento del salvataggio dell'URL che al momento dell'invio, e i reindirizzamenti non vengono seguiti.

## Eliminare i dati di un cliente

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

Elimina tutti i risultati memorizzati relativi a quel `customer_id` dal tuo account e cancella l'ID dai tuoi registri. Utilizzalo quando un utente finale richiede il diritto all'oblio (GDPR, DPDP).

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

## Limiti

|  |  |
|---|---|
| Creazione di lavori e lotti | Viene conteggiato ai fini del limite di 300 richieste al minuto per chiave |
| Processi asincroni in esecuzione contemporaneamente | 50 per account (`429 TOO_MANY_JOBS`); i batch sono separati |
| Dimensione del lotto | 500 articoli |
| Risultati | Conservato per 7 giorni |
| Metadati | Oggetto JSON, 2 KB |
