# Tareas asíncronas, lotes y webhooks

`POST /generate` es la forma más sencilla de realizar una prueba de ajuste: una sola solicitud y se obtiene la imagen. Utiliza tareas asíncronas cuando no quieras mantener abierta una conexión, y procesamientos por lotes para el trabajo con catálogos. Ambos utilizan el mismo motor, tienen el mismo coste y reembolsan cada prueba de ajuste que falle.

|  | `POST /generate` (síncrono) | `POST /generations` (asíncrono) | `POST /batches` |
|---|---|---|---|
| Respuesta | El archivo PNG, en la misma solicitud | `202` con un ID de trabajo | `202` con un identificador de lote |
| Datos de entrada | Archivos, base64 o `garment_url` | Archivos, código base64 o URL | `garment_url` y `person_url` por artículo |
| Resultado | Cuerpo de la respuesta | `GET /results/:id`, se conserva durante 7 días | Lo mismo, por unidad |
| Notificación | No es necesario | Poll o webhook | Webhook por elemento, además de `batch.completed` |
| Créditos | Asignación gratuita o créditos comprados | Créditos comprados | Créditos comprados, se cobran todos los elementos al crear el lote |
| Modo de prueba | `?mock=true` | `?mock=true` | `?mock=true` |

## Iniciar una tarea asíncrona

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

Los mismos encabezados y campos de imagen que en [Generar](/docs/generate), además de:

| Campo | Descripción |
|---|---|
| `person_url` | URL pública `https` de la foto del comprador (alternativa a un archivo o a un código base64) |
| `customer_id` | Tu identificador de usuario final, de hasta 128 caracteres. Se utiliza para [eliminar clientes.](#delete-a-customers-data) |
| `metadata` | Un objeto JSON de hasta 2 KB, que se devuelve sin modificaciones tanto en la tarea como en los webhooks. |
| `webhook_url` | URL pública `https` para recibir `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 Aceptadas**

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

El proceso comienza en cuanto se envía la respuesta. Tus imágenes se procesan en memoria y nunca se almacenan; solo se conserva el resultado final, durante 7 días.

## Consultar una oferta de empleo

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

`status` pasa de `queued` a `processing` y, a continuación, a `completed` o `failed`. Un trabajo completado tiene `result_url`; descárgalo con tu clave:

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

Una tarea fallida tiene el código de error `error.code`: `CONTENT_FILTERED`, `GENERATION_FAILED` o `INPUT_FETCH_FAILED`. En todos los casos se reembolsa el crédito.

## Lotes

`POST https://www.tryoncloud.com/api/v1/batches` con un cuerpo JSON de hasta 500 elementos:

```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 crear el lote, se deduce un crédito por cada artículo. Si tu saldo es demasiado bajo, no se crea nada (código de error `402 NO_CREDITS`).
- `GET /batches/:id` devuelve el recuento y todos los elementos.
- `DELETE /batches/:id` cancela los trabajos que aún no han comenzado y devuelve el importe correspondiente. Los trabajos en ejecución se completan.
- Cada elemento envía su propio webhook, y el lote envía `batch.completed` una vez que todos los elementos tienen un resultado.

## Webhooks

Enviamos un `POST` JSON a tu `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 }
}
```

Eventos: `generation.completed`, `generation.failed`, `batch.completed` y `webhook.test` desde el panel de control.

Encabezados: `x-tryoncloud-event`, `x-tryoncloud-delivery-id` (eliminar duplicados en este), `x-tryoncloud-timestamp` y `x-tryoncloud-signature-v2`.

**Punto final de la cuenta.** En lugar de enviar `webhook_url` con cada solicitud, guarda un punto final en el panel de control (**Claves API > Webhooks**) y selecciona los eventos que debe recibir. La `webhook_url` de la propia solicitud siempre tiene prioridad. **La** función **Enviar eventos de prueba** envía un evento firmado `webhook.test` al punto final guardado.

**Comprueba cada entrega.** Tu secreto de firma se encuentra en la misma tarjeta (muéstralo, cópialo o gíralo). La firma es 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))
}
```

Responde con cualquier código `2xx` en un plazo de 8 segundos. Las demás respuestas y los tiempos de espera se reintentan con un intervalo de espera (1 minuto, 5 minutos, 30 minutos, 2 horas, 6 horas, 24 horas). Las URL de los webhooks deben ser públicas `https` en el puerto estándar; se rechazan las direcciones privadas e internas, tanto al guardar la URL como al enviarla, y no se siguen las redirecciones.

## Eliminar los datos de un cliente

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

Elimina todos los resultados almacenados correspondientes a ese `customer_id` en tu cuenta y borra el identificador de tus registros. Úsalo cuando un usuario final solicite el derecho al olvido (GDPR, DPDP).

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

## Límites

|  |  |
|---|---|
| Creación de trabajos y lotes | Se contabiliza en el límite de 300 solicitudes por minuto por clave |
| Tareas asíncronas que se ejecutan al mismo tiempo | 50 por cuenta (`429 TOO_MANY_JOBS`); los lotes son independientes |
| Tamaño del lote | 500 artículos |
| Resultados | Se conserva durante 7 días |
| Metadatos | Objeto JSON, 2 KB |
