# Recomendaciones desde el servidor

> Obtén la talla de quien compra en tu servidor con un handle sellado desde el navegador. Solo tallas; las medidas nunca salen de TryYourSize.

Source: https://docs.tryyoursize.com/es/guides/server-side-recommendations/

Úsalo cuando tu servidor necesite la talla de quien compra: una tienda headless, páginas de producto renderizadas en el servidor, una talla mostrada en un email de carrito o tu propia lógica de recomendación.

## Cómo funciona

1. **En el navegador**, TryYourSize.js pide a nuestro origen un **handle de recomendación** para la persona compradora con sesión iniciada.

   ```ts
   const tys = TryYourSize("pk_live_…");
   const h = await tys.recommendationHandle();   // { handle, expiresAt } | null
   ```

   `null` significa que quien compra no ha iniciado sesión en TryYourSize en este sitio, aún no tiene cuerpo o está en tu [grupo de control A/B](https://docs.tryyoursize.com/es/guides/ab-holdout.md). `expiresAt` es una fecha y hora ISO una hora por delante. En React, llámalo en el cliente desde `useTryYourSize()`.

2. **Tu página envía `h.handle` a tu propio servidor**, como cualquier otro valor (un campo de formulario, un fetch a tu API).

3. **Tu servidor** llama a `POST /v1/recommendations` con una clave secreta (o una clave restringida con `fit_checks:read`) y hasta 25 productos.

4. **La respuesta** es una entrada por producto, en el orden solicitado: tallas con tus etiquetas, nunca medidas.

**Node.js**

```ts
const tys = new TryYourSize(process.env.TYS_SECRET_KEY!);

const { mode, data } = await tys.recommendations.create({
  handle: req.body.tysHandle,
  products: ["CREW-TSHIRT", "STRAIGHT-JEANS"],
});
for (const r of data) {
  if (r.status === "ready") console.log(r.product, r.size);   // "CREW-TSHIRT", "Medium"
}
```

**Python**

```python
tys = tryyoursize.TryYourSize(os.environ["TYS_SECRET_KEY"])

res = tys.recommendations.create(
    handle=request.form["tys_handle"],
    products=["CREW-TSHIRT", "STRAIGHT-JEANS"],
)
for r in res["data"]:
    if r["status"] == "ready":
        print(r["product"], r["size"])
```

**cURL**

```bash
curl https://api.tryyoursize.com/v1/recommendations \
  -H "Authorization: Bearer $TYS_SECRET_KEY" \
  -H "TYS-Version: 2026-10-25" \
  -H "Content-Type: application/json" \
  -d '{"handle":"tys_rh_…","products":["CREW-TSHIRT","STRAIGHT-JEANS"]}'
```

## La respuesta

```json
{
  "mode": "live",
  "data": [
    {
      "product": "CREW-TSHIRT",
      "status": "ready",
      "size": "Medium",
      "studio_size": "M",
      "wearable_sizes": ["Medium", "Large"]
    },
    {
      "product": "STRAIGHT-JEANS",
      "status": "unavailable",
      "size": null,
      "studio_size": null,
      "wearable_sizes": []
    }
  ]
}
```

| Campo | |
|---|---|
| `status` | `ready` (hay talla), `computing` (se está ejecutando una simulación que inició quien compra: vuelve a preguntar más tarde), `none` (simulado, ninguna talla se puede llevar), `unavailable` (no hay prenda publicada, aún no se ha simulado en este cuerpo o al plan no le quedan pruebas de tallaje). No existe `signed_out`: un handle siempre pertenece a una persona compradora con sesión iniciada. |
| `size` | La talla recomendada con tu etiqueta (el mapa de tallas del producto), o `null`. |
| `studio_size` | La misma talla tal como se introdujo en Studio, o `null`. |
| `wearable_sizes` | Tallas que se pueden llevar en este cuerpo, con tus etiquetas. |
| `method` | Una etiqueta orientativa y genérica de cómo se obtuvo la talla. No bases ninguna lógica en sus valores. |
| `tryon_id` | La prueba virtual que produjo la talla, cuando la hay. Devuélvelo con los pedidos para la atribución. |

## Reglas

- **Nunca inicia una simulación.** Igual que al ver una página, solo responde con una talla que ya está disponible (muchas prendas responden en menos de un segundo) y, si no, el estado es `unavailable` hasta que quien compra pida la prueba virtual en nuestra ventana.
- **Una talla entregada cuenta como una prueba de tallaje**, exactamente igual que en el navegador (una vez por persona compradora y producto cada 30 días, solo en modo real).
- **La API de servidor nunca acepta ni devuelve medidas en bruto.**

## El handle

- Empieza por `tys_rh_` y ocupa hasta 4 KB. Trátalo como opaco.
- Está **cifrado y sellado** para una tienda, un modo y una persona compradora. Ni tu página ni tu servidor pueden leer nada de él; nunca contiene el email de quien compra.
- **Caduca al cabo de 1 hora.** A partir de entonces la API responde `401` con el código [`handle_expired`](https://docs.tryyoursize.com/api/errors.md#handle_expired): pide uno nuevo al navegador.
- Se rechaza con `401` [`handle_invalid`](https://docs.tryyoursize.com/api/errors.md#handle_invalid) cuando quien compra elimina su cuenta o desconecta tu tienda, y cuando se emitió para otra tienda.
- Su **modo debe coincidir con el de tu clave**: un handle de prueba con una clave real (o al revés) devuelve `403` [`handle_mode_mismatch`](https://docs.tryyoursize.com/api/errors.md#handle_mode_mismatch).

> **Tip**
>
> Pide un handle nuevo en cada carga de página en lugar de guardarlo: es barato, y un handle reciente refleja el consentimiento actual de quien compra.