# Inicio rápido de la API de servidor

> Llama a la API de servidor de TryYourSize desde Node o Python. Sincronización del catálogo, pedidos y devoluciones, recomendaciones en el servidor.

Source: https://docs.tryyoursize.com/es/quickstarts/server/

> **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](https://docs.tryyoursize.com/es/get-started/keys-and-modes.md#permisos-de-las-claves) `rk_…`) |
| Versión | `TYS-Version: 2026-10-25` (consulta [Versiones](https://docs.tryyoursize.com/guides/versioning.md)) |
| Errores | `{ error, status, code, doc_url, request_id }` más la cabecera `X-Request-ID` (consulta [Errores](https://docs.tryyoursize.com/api/errors.md)) |
| Reintentos | `Idempotency-Key` en los POST (consulta [Idempotencia](https://docs.tryyoursize.com/guides/idempotency.md)) |
| Listas | `limit` + `cursor` → `{ data, has_more, next_cursor }` (consulta [Paginación](https://docs.tryyoursize.com/guides/pagination.md)) |

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.js**

```bash
npm install @tryyoursize/node
```

```ts

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

**Python**

```bash
pip install tryyoursize
```

```python

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

**cURL**

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

> **Note**
>
> 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](https://docs.tryyoursize.com/api/reference.md) es la fuente de verdad.

## Sincronizar un producto

**Node.js**

```ts
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);
}
```

**Python**

```python

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](https://docs.tryyoursize.com/api/reference.md).

## 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](https://docs.tryyoursize.com/es/guides/webhooks.md) |

## Errores

**Node.js**

```ts

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

**Python**

```python
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](https://docs.tryyoursize.com/es/guides/server-side-recommendations.md): la talla de quien compra en tu servidor.
- [Pedidos y devoluciones](https://docs.tryyoursize.com/es/guides/outcomes.md): mide las devoluciones por talla.
- [Webhooks](https://docs.tryyoursize.com/es/guides/webhooks.md): `fit.recommended`, `garment.published` y más.