Recomendaciones desde el servidor

Ú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.

   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. 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.jsPythoncURL

import TryYourSize from "@tryyoursize/node";
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"
}

import tryyoursize
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 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

{
  "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: pide uno nuevo al navegador.
• Se rechaza con 401 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.

Consejo

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.