# Tarefas assíncronas, lotes e webhooks

`POST /generate` é a forma mais simples de executar uma simulação: basta uma solicitação e a imagem é devolvida. Utilize tarefas assíncronas quando não quiser manter uma ligação aberta e processamento em lote para trabalhos relacionados com o catálogo. Ambas utilizam o mesmo motor, têm o mesmo custo e reembolsam todas as simulações que falhem.

|  | `POST /generate` (síncrono) | `POST /generations` (assíncrono) | `POST /batches` |
|---|---|---|---|
| Resposta | O ficheiro PNG, no mesmo pedido | `202` com um ID de trabalho | `202` com um ID de lote |
| Entradas | Ficheiros, base64 ou `garment_url` | Ficheiros, base64 ou URLs | `garment_url` e `person_url` por artigo |
| Resultado | Corpo da resposta | `GET /results/:id`, mantido durante 7 dias | O mesmo, por artigo |
| Notificação | Não é necessário | Poll ou webhook | Webhook por item, além de `batch.completed` |
| Créditos | Quota gratuita ou créditos comprados | Créditos comprados | Créditos comprados, cobrados para todos os itens ao criar o lote |
| Modo de teste | `?mock=true` | `?mock=true` | `?mock=true` |

## Iniciar uma tarefa assíncrona

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

Os mesmos cabeçalhos e campos de imagem que [a opção Gerar](/docs/generate), além de:

| Campo | Descrição |
|---|---|
| `person_url` | URL pública `https` da fotografia do comprador (alternativa a um ficheiro ou a um código base64) |
| `customer_id` | O seu ID de utilizador final, com um máximo de 128 caracteres. Utilizado na [eliminação de clientes](#delete-a-customers-data) |
| `metadata` | Um objeto JSON com um tamanho máximo de 2 KB, devolvido sem alterações na tarefa e nos webhooks |
| `webhook_url` | URL pública `https` para receber `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 Aceito**

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

O processo tem início assim que a resposta é enviada. As suas imagens são processadas na memória e nunca são guardadas; apenas o resultado final é mantido, durante 7 dias.

## Verificar uma oferta de emprego

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

O `status` passa de `queued` → `processing` → `completed` ou `failed`. Uma tarefa concluída tem um `result_url`; descarregue-o com a sua chave:

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

Uma tarefa com falha apresenta o código de erro `error.code`: `CONTENT_FILTERED`, `GENERATION_FAILED` ou `INPUT_FETCH_FAILED`. O crédito é reembolsado em todos os casos.

## Lotes

`POST https://www.tryoncloud.com/api/v1/batches`, com um corpo JSON de até 500 itens:

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

- É deduzido um crédito por item quando o lote é criado. Se o seu saldo for demasiado baixo, nada é criado (código de erro `402 NO_CREDITS`).
- `GET /batches/:id` devolve o número de itens e cada um deles.
- `DELETE /batches/:id` cancela os itens que ainda não foram iniciados e reembolsa-os. Os itens em execução são concluídos.
- Cada item envia o seu próprio webhook, e o lote envia o `batch.completed` assim que todos os itens tiverem um resultado.

## Webhooks

Enviamos um JSON via `POST` para o seu `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` e `webhook.test` no painel de controlo.

Cabeçalhos: `x-tryoncloud-event`, `x-tryoncloud-delivery-id` (eliminar duplicados neste), `x-tryoncloud-timestamp` e `x-tryoncloud-signature-v2`.

**Endpoint da conta.** Em vez de enviar o `webhook_url` em cada pedido, guarde um endpoint no painel de controlo (**Chaves API > Webhooks**) e selecione os eventos que este irá receber. O `webhook_url` próprio de cada pedido tem sempre prioridade. **Envie** um evento **de teste** assinado `webhook.test` para o endpoint guardado.

**Verifique todas as entregas.** O seu segredo de assinatura encontra-se no mesmo cartão (revele-o, copie-o ou rode-o). A assinatura é um 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))
}
```

Responda com qualquer código `2xx` no prazo de 8 segundos. Outras respostas e casos de tempo de espera esgotado são repetidos com intervalos de espera (1 minuto, 5 minutos, 30 minutos, 2 horas, 6 horas, 24 horas). Os URLs de webhook têm de ser públicos `https` na porta padrão; os endereços privados e internos são recusados, tanto quando guarda o URL como quando enviamos, e os redirecionamentos não são seguidos.

## Eliminar os dados de um cliente

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

Elimina todos os resultados armazenados para esse `customer_id` na sua conta e remove o ID dos seus registos. Utilize esta função quando um utilizador final solicitar o direito ao esquecimento (GDPR, DPDP).

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

## Limites

|  |  |
|---|---|
| Criação de tarefas e lotes | Conta para o limite de 300 pedidos por minuto por chave |
| Tarefas assíncronas a serem executadas simultaneamente | 50 por conta (`429 TOO_MANY_JOBS`); os lotes são separados |
| Tamanho do lote | 500 artigos |
| Resultados | Guardado durante 7 dias |
| Metadados | Objeto JSON, 2 KB |
