# Shopify Hydrogen (sin interfaz)

Añade la función de prueba virtual a una **tienda Shopify headless** creada con Hydrogen y alojada en Oxygen. Solo se necesita una ruta de servidor y un componente de página de producto, y la clave API nunca llega al navegador.

## Qué significa «sin cabeza»

Una tienda normal de Shopify muestra sus páginas mediante un **tema**. Nuestra [aplicación](/docs/shopify) de [Shopify](/docs/shopify) añade el botón «Probar» a ese tema sin necesidad de código.

Una tienda **headless** utiliza Shopify para los productos, el carrito, el proceso de pago y las transacciones, pero la interfaz que ven los compradores es una **aplicación** independiente de **React** creada por tus desarrolladores. Hydrogen es el marco de trabajo de Shopify para esa aplicación y Oxygen es el servicio de alojamiento de Shopify para la misma. Al no haber tema, no aparecen los bloques de la aplicación de temas, por lo que una tienda «headless» incorpora la función de «prueba virtual» a través de la **API para desarrolladores**.

|  | Tienda de temas | Tienda «Headless» (de Hydrogen) |
|---|---|---|
| Escaparate | Tema de Shopify | Tu aplicación de React en Oxygen |
| Cómo se añade la función de prueba de ropa | Instala la aplicación de Shopify, añade el bloque | Una ruta de servidor y un componente |
| Facturación | Plan de Shopify, en tu factura de Shopify | Créditos de la API para desarrolladores, prepagados |
| Guía | [Shopify](/docs/shopify) | Esta página |

## Cómo funciona

```flow
Shopper browser -> Your Hydrogen route: POST /api/try-on (photo + product image URL)
Your Hydrogen route -> TryOnCloud API: POST /api/v1/generate (X-API-KEY)
TryOnCloud API --> Your Hydrogen route: 200 image/png
Your Hydrogen route --> Shopper browser: 200 image/png
```

1. El comprador pulsa **en Pruébatelo** en la página de un producto y hace o sube una foto.
2. El navegador envía la foto y la URL de la imagen del producto a **tu** ruta de Hydrogen.
3. Tu ruta llama a TryOnCloud con tu clave secreta y recibe la imagen finalizada, normalmente en unos 20 segundos.
4. El comprador se imagina a sí mismo llevando puesto el producto. TryOnCloud no almacena nada a menos que actives el almacenamiento de resultados.

## 1. Obtener una clave API

Regístrate, abre **el Panel de control > Claves API** y crea una clave. Empieza por `tk_dev_v1_` y solo se muestra completa una vez. Tu cuenta incluye pruebas gratuitas desde el principio, y el modo de prueba (`?mock=true`) siempre es gratuito.

## 2. Guarda la clave en Oxygen

En el panel de administración de Shopify, abre **Hydrogen > tu tienda > Configuración de la tienda > Entornos y variables** y añade una variable **secreta**:

```bash
TRYONCLOUD_API_KEY=tk_dev_v1_your_key_here
```

Para el desarrollo local, descárgalo en `.env` con `npx shopify hydrogen env pull` o añádelo manualmente a `.env`. A continuación, añádelo al tipo `Env` en `env.d.ts` para que `context.env` tenga un tipo definido:

```ts
interface Env extends HydrogenEnv {
  TRYONCLOUD_API_KEY: string
}
```

## 3. Añadir la ruta del servidor

Crea el archivo `app/routes/api.try-on.tsx`. Hydrogen lo sirve en `/api/try-on`. La ruta solo acepta imágenes de productos procedentes de tu propio CDN de Shopify, por lo que nadie puede utilizar tu clave para probarse imágenes aleatorias.

```ts
import type { Route } from "./+types/api.try-on"

const MAX_PHOTO_BYTES = 15 * 1024 * 1024

export async function action({ request, context }: Route.ActionArgs) {
  if (request.method !== "POST") return new Response("Method not allowed", { status: 405 })

  const incoming = await request.formData()
  const person = incoming.get("person")
  const garmentUrl = incoming.get("garmentUrl")
  // One id per try-on, made in the browser. A retry with the same id is never charged twice.
  const tryOnId = incoming.get("tryOnId")

  if (!(person instanceof Blob) || person.size === 0 || person.size > MAX_PHOTO_BYTES) {
    return Response.json({ error: "Please add a photo under 15MB." }, { status: 400 })
  }
  // Only your own product images: blocks anyone using this route as a free try-on service.
  if (typeof garmentUrl !== "string" || !garmentUrl.startsWith("https://cdn.shopify.com/")) {
    return Response.json({ error: "Invalid product image." }, { status: 400 })
  }

  const form = new FormData()
  form.append("person_image", person, "person.jpg")
  form.append("garment_url", garmentUrl)
  // Optional: your own shopper id (for example a hash of the Customer Account id),
  // so you can find this shopper's try-ons and erase them on request.
  // form.append("customer_id", shopperId)

  const headers: Record<string, string> = { "X-API-KEY": context.env.TRYONCLOUD_API_KEY }
  if (typeof tryOnId === "string" && /^[\w-]{8,64}$/.test(tryOnId)) headers["Idempotency-Key"] = tryOnId

  const res = await fetch("https://www.tryoncloud.com/api/v1/generate", {
    method: "POST",
    headers,
    body: form,
    signal: AbortSignal.timeout(120_000),
  })
  const requestId = res.headers.get("X-Request-Id") ?? ""

  if (!res.ok) {
    const { error, code } = await res.json()
    console.error("try-on failed", code, requestId) // quote requestId to TryOnCloud support
    return Response.json({ error, code }, { status: res.status })
  }
  return new Response(res.body, {
    headers: { "Content-Type": "image/png", "Cache-Control": "no-store", "X-Request-Id": requestId },
  })
}
```

En un proyecto Hydrogen más antiguo basado en Remix, importa los tipos desde `@shopify/remix-oxygen`: `import type { ActionFunctionArgs } from "@shopify/remix-oxygen"`, y define el tipo de la acción como `({ request, context }: ActionFunctionArgs)`.

> **Nota:** Una prueba tarda unos 20 segundos. Mantén la solicitud abierta y no añadas un tiempo de espera más corto al principio de esta ruta. Las pruebas fallidas se reembolsan automáticamente.

## 4. Añade el botón a la página del producto

Crea el archivo `app/components/TryOnButton.tsx`:

```tsx
import { useState } from "react"

export function TryOnButton({ productImageUrl }: { productImageUrl: string }) {
  const [result, setResult] = useState<string | null>(null)
  const [busy, setBusy] = useState(false)
  const [error, setError] = useState<string | null>(null)

  async function onFile(file: File) {
    setBusy(true)
    setError(null)
    const form = new FormData()
    form.append("person", file)
    form.append("garmentUrl", productImageUrl)
    form.append("tryOnId", crypto.randomUUID()) // reuse the same id if you add a "Retry" button
    try {
      const res = await fetch("/api/try-on", { method: "POST", body: form })
      if (!res.ok) throw new Error((await res.json()).error ?? "Try-on failed")
      setResult(URL.createObjectURL(await res.blob()))
    } catch (e) {
      setError(e instanceof Error ? e.message : "Try-on failed")
    } finally {
      setBusy(false)
    }
  }

  return (
    <div>
      <label>
        {busy ? "Creating your look..." : "Try it on"}
        <input
          type="file"
          accept="image/*"
          capture="user"
          hidden
          disabled={busy}
          onChange={(e) => e.target.files?.[0] && onFile(e.target.files[0])}
        />
      </label>
      <p>Your photo is used only to create this image and is not stored.</p>
      {error && <p role="alert">{error}</p>}
      {result && <img src={result} alt="You wearing this product" />}
    </div>
  )
}
```

A continuación, muéstrala en la ruta del producto, `app/routes/products.$handle.tsx`, con la imagen de la variante seleccionada; si no está disponible, utiliza la imagen principal del producto:

```tsx
const garmentUrl =
  product.selectedOrFirstAvailableVariant?.image?.url ?? product.featuredImage?.url

{garmentUrl && <TryOnButton productImageUrl={garmentUrl} />}
```

Asegúrate de que tu consulta sobre el producto solicite `image { url }` en la variante y `featuredImage { url }` en el producto.

## 5. Permite la imagen del resultado en tu CSP

Hydrogen envía una política de seguridad de contenido (CSP) estricta. El resultado se muestra a partir de una URL `blob:`, así que añade `blob:` a `imgSrc` en `app/entry.server.tsx`:

```ts
const { nonce, header, NonceProvider } = createContentSecurityPolicy({
  shop: { checkoutDomain: context.env.PUBLIC_CHECKOUT_DOMAIN, storeDomain: context.env.PUBLIC_STORE_DOMAIN },
  imgSrc: ["'self'", "https://cdn.shopify.com", "data:", "blob:"],
})
```

No es necesario modificar `connectSrc`: el navegador solo se comunica con tu propia ruta `/api/try-on`.

## 6. Realiza pruebas antes de ponerlo en marcha

1. Configura la ruta en modo de prueba mientras la creas: utiliza `https://www.tryoncloud.com/api/v1/generate?mock=true`. Se ejecutan todas las comprobaciones y se devuelve la foto sin modificaciones, sin que se consuma ningún crédito.
2. Prueba varios productos: camisetas, vestidos, saris, conjuntos de kurta y pantalones.
3. Prueba con una foto demasiado grande y con un archivo que no sea de imagen, y comprueba los mensajes de error.
4. Elimina `?mock=true` y realiza pruebas reales.

## 7. Ponerlo en marcha a escala comercial

Los catálogos extensos y las tiendas numerosas necesitan algo más que un botón. Todo esto ya está integrado:

| Necesidad | ¿Cómo? |
|---|---|
| Separar la puesta en escena y la producción | Crea una clave por entorno en **Claves de API**. Asigna a la clave de entorno de pruebas un **límite de crédito mensual** y una **fecha de caducidad**, de modo que las pruebas nunca puedan gastar créditos de producción. |
| Reintentos seguros en redes móviles | Envía una `Idempotency-Key` (el `tryOnId` mencionado anteriormente). Un nuevo intento de la misma prueba tras una pérdida de conexión se cobra una sola vez, y el botón queda desactivado mientras se está realizando una prueba, por lo que un doble toque no puede iniciar una segunda prueba. |
| Asistencia y auditoría | Cada respuesta incluye el campo `X-Request-Id`. Anótalo junto con los errores y facilítanoslo. |
| Solicitudes de privacidad de los clientes | Envía `customer_id` y, a continuación, borra los datos de ese cliente con `DELETE /api/v1/customers/:id`. Las fotos de los clientes nunca se almacenan de forma predeterminada. |
| Productos más vendidos | El análisis de la prenda se almacena en caché durante 30 días, por lo que las pruebas repetidas de la misma foto del producto son unos 2 segundos más rápidas. |
| Imágenes del catálogo | Crea fotos con modelo para numerosas referencias (SKU) mediante `POST /api/v1/batches` (hasta 500 por lote) y un webhook firmado cuando cada una esté lista. Consulta la sección sobre [tareas asíncronas, lotes y webhooks](/docs/async). |
| Horas punta de tráfico | 300 solicitudes por minuto por clave y 600 por cuenta. Antes de una gran oferta o un lanzamiento festivo, [avísanos](/contact) para que podamos planificar la capacidad. |
| Seguimiento | Índice de éxito y velocidad en tiempo real en [/status](/status); uso por clave en **Generations** (búsqueda, exportación a CSV). |
| Generadores de clientes | Especificación de OpenAPI 3.1 en [/api/v1/openapi.json](/api/v1/openapi.json). |

## 8. Lista de comprobación para la puesta en marcha

- `TRYONCLOUD_API_KEY` es una variable **secreta** en el entorno **de producción** de Oxygen
- La clave no aparece en ninguna parte del código del navegador ni en el código fuente de la página.
- Se ha eliminado `?mock=true` de la ruta
- Se ha añadido `blob:` a `imgSrc`
- Las imágenes de los productos proceden de `cdn.shopify.com` y muestran la prenda con claridad
- La línea de privacidad que aparece junto al botón (la foto se utiliza únicamente para la prueba y no se guarda)
- Créditos recargados. Enviamos automáticamente un correo electrónico al titular de la cuenta cuando el saldo desciende al 10 % del importe de la última compra (un mínimo de 20 créditos).
- Una clave de producción independiente de la clave de prueba, cada una con el límite de crédito mensual que desees
- `Idempotency-Key`, enviado en cada intento de prueba, y `X-Request-Id`, registrado en caso de error

## Cronología

Un equipo de Hydrogen suele necesitar **entre** una** y dos semanas** para una prueba piloto: un día para añadir la clave y realizar pruebas en modo simulado, dos o tres días para la ruta y el botón de la página del producto, y el resto para el control de calidad con productos reales y un lanzamiento por fases.

## Las tiendas también

¿También tenéis tiendas físicas? El [quiosco de la tienda](/docs/kiosk) permite probarse la ropa en una pantalla o en un espejo inteligente, incluso cuando los clientes se acercan con una prenda a la cámara. Se utiliza la misma cuenta.

## Precios

Las tiendas «Headless» utilizan **créditos de la API para desarrolladores**: son de prepago, no caducan nunca y no se cobra por las pruebas fallidas. Consulta [las tarifas](/pricing#developer-api). Para grandes volúmenes o un proyecto piloto en varias tiendas, [ponte en contacto con nosotros](/contact) para conocer las tarifas para empresas.

## Relacionado

- [Generar una simulación de prueba](/docs/generate): todos los campos y respuestas
- [Errores](/docs/errors) y [limitaciones](/docs/limits)
- [Tareas asíncronas, lotes y webhooks](/docs/async)
- [Estado de la API](/status) y la [especificación OpenAPI](/api/v1/openapi.json)
- [Datos, privacidad](/docs/data-privacy) y el [acuerdo de tratamiento de datos](/dpa)
