Inicio rápido de la API de servidor

Para tu equipo de desarrollo

Qué hace: Conecta nuestro backend con TryYourSize: sincroniza productos y datos de prendas, envía pedidos y devoluciones para el informe de devoluciones por talla, y lee tallas desde el servidor. Nunca se envían ni se reciben medidas.

Tiempo necesario: Unas horas para una primera llamada; uno o dos días para sincronizar todo el catálogo.

Qué enviarle: Una clave secreta de prueba (sk_test_…) de Studio → Desarrolladores → Claves de API, enviada con un gestor de contraseñas, nunca por email ni por chat. Para un partner, una clave restringida (rk_test_…) solo con los permisos que necesite.

Convenciones

URL base	https://api.tryyoursize.com
Autenticación	Authorization: Bearer sk_test_… (o una clave restringida rk_…)
Versión	TYS-Version: 2026-10-25 (consulta Versiones)
Errores	{ error, status, code, doc_url, request_id } más la cabecera X-Request-ID (consulta Errores)
Reintentos	Idempotency-Key en los POST (consulta Idempotencia)
Listas	limit + cursor → { data, has_more, next_cursor } (consulta Paginación)

Las rutas del catálogo aceptan un ID de producto de TryYourSize o tu SKU. El catálogo es el mismo en modo de prueba y en modo real: el modo de prueba responde con borradores y el modo real con versiones publicadas.

Instalación

Node.jsPythoncURL

npm install @tryyoursize/node

import TryYourSize from "@tryyoursize/node";

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

pip install tryyoursize

import os
import tryyoursize

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

export TYS_SECRET_KEY=sk_test_…
curl https://api.tryyoursize.com/v1/products?limit=5 \
  -H "Authorization: Bearer $TYS_SECRET_KEY" \
  -H "TYS-Version: 2026-10-25"

Nota

Las bibliotecas de Node (@tryyoursize/node) y Python (tryyoursize) son nuestros SDK de servidor oficiales. Fijan TYS-Version por ti, reintentan de forma segura con claves de idempotencia y siguen la referencia de la API una a una; en caso de duda, la referencia de la API es la fuente de verdad.

Sincronizar un producto

Node.jsPython

const product = await tys.products.create(
  { external_id: "CREW-TSHIRT", name: "Crew T-shirt", category: "tshirt" },
  { idempotencyKey: crypto.randomUUID() },
);

// Las etiquetas de tu tienda para cada talla de Studio: las recomendaciones vuelven con estas etiquetas.
await tys.products.sizeMap.save("CREW-TSHIRT", {
  entries: [
    { studio_size: "S", shop_value: "Small" },
    { studio_size: "M", shop_value: "Medium" },
    { studio_size: "L", shop_value: "Large" },
  ],
});

for await (const p of tys.products.list({ limit: 50 })) {
  console.log(p.id, p.external_id);
}

import uuid

product = tys.products.create(
    external_id="CREW-TSHIRT",
    name="Crew T-shirt",
    category="tshirt",
    idempotency_key=str(uuid.uuid4()),
)

tys.products.size_map.save("CREW-TSHIRT", entries=[
    {"studio_size": "S", "shop_value": "Small"},
    {"studio_size": "M", "shop_value": "Medium"},
    {"studio_size": "L", "shop_value": "Large"},
])

for p in tys.products.list(limit=50).auto_paging_iter():
    print(p["id"], p["external_id"])

Los nombres de los campos y los cuerpos están en la referencia de la API.

Recursos

Node	Python	Endpoint
tys.recommendations.create({ handle, products })	tys.recommendations.create(...)	POST /v1/recommendations
tys.products.list / create / retrieve / update	igual	/v1/products, /v1/products/{product}
tys.products.sizeMap.retrieve / save	tys.products.size_map.retrieve / save	/v1/products/{product}/size_map
tys.products.garments.list / createDraft	tys.products.garments.list / create_draft	/v1/products/{product}/garments
tys.garments.retrieve / updateDraft / publish	tys.garments.retrieve / update_draft / publish	/v1/garments/{garment_id}
tys.fitGroups.list / create / retrieve / linkProducts	tys.fit_groups.list / create / retrieve / link_products	/v1/fit_groups
tys.orders.create	tys.orders.create	POST /v1/orders
tys.returns.create	tys.returns.create	POST /v1/returns
tys.auditEvents.list	tys.audit_events.list	GET /v1/audit_events
tys.webhooks.constructEvent(rawBody, header, secret)	tryyoursize.Webhook.construct_event(payload, sig_header, secret)	Webhooks

Errores

Node.jsPython

import TryYourSize, { TryYourSizeError } from "@tryyoursize/node";

try {
  await tys.products.retrieve("NO-SUCH-SKU");
} catch (err) {
  if (err instanceof TryYourSizeError) {
    console.error(err.code, err.docUrl, err.requestId);   // "not_found", https://docs…/api/errors/#not_found, …
  }
}

try:
    tys.products.retrieve("NO-SUCH-SKU")
except tryyoursize.APIError as e:
    print(e.code, e.doc_url, e.request_id)

Siguientes pasos

• Recomendaciones en el servidor: la talla de quien compra en tu servidor.
• Pedidos y devoluciones: mide las devoluciones por talla.
• Webhooks: fit.recommended, garment.published y más.