Tiendas

Cómo consumir la API pública del storefront, configurar visibilidad y gestionar tokens

TunoCommerce soporta múltiples storefronts por empresa. Cada storefront tiene su propio catálogo visible, branding y tokens de acceso. Esta guía cubre la API pública del storefront — los endpoints de solo lectura diseñados para frontends de cliente.

¿Qué es la API del storefront?

La API pública del storefront expone 5 endpoints de solo lectura para construir frontends de catálogo:

Endpoint	Descripción
`GET /api/v1/storefront/config`	Configuración y branding de la tienda
`GET /api/v1/storefront/catalog/products`	Listado paginado de productos
`GET /api/v1/storefront/catalog/products/:slug`	Detalle de producto
`GET /api/v1/storefront/catalog/categories`	Árbol de categorías
`GET /api/v1/storefront/catalog/brands`	Listado de marcas

Características:

Solo lectura — no permite crear, editar ni eliminar
Respeta la visibilidad de catálogo configurada por empresa
Respuestas cacheadas (Cache-Control: 60-300 segundos)
No requiere autenticación de usuario final

Autenticación

Todos los endpoints requieren dos headers:

-H "X-Storefront-Slug: acme-b2c"
-H "Authorization: Bearer sf_dev_seed_acme_b2c_token"

El token debe ser sf_* y estar asociado al storefront identificado por el slug. Si no coinciden, la API retorna 401 STOREFRONT_UNAUTHORIZED.

Tokens de desarrollo (disponibles tras pnpm db:seed):

Tienda	Slug	Token
Acme Tienda Online	`acme-b2c`	`sf_dev_seed_acme_b2c_token`
Acme Mayoreo	`acme-wholesale`	`sf_dev_seed_acme_wholesale_token`

Obtener configuración del storefront

curl "https://tu-instancia.com/api/v1/storefront/config" \
  -H "X-Storefront-Slug: acme-b2c" \
  -H "Authorization: Bearer sf_dev_seed_acme_b2c_token"

Respuesta:

{
  "data": {
    "id": "clx...",
    "name": "Acme Tienda Online",
    "slug": "acme-b2c",
    "status": "active",
    "description": "Tienda B2C de Acme Corp",
    "primaryColor": "#1976d2",
    "logoUrl": null,
    "currency": "MXN",
    "taxRate": 0.16,
    "taxIncluded": false,
    "company": {
      "id": "clx...",
      "name": "Acme Corp"
    }
  }
}

Usa esta respuesta para inicializar el tema de tu frontend (colores, nombre, moneda).

Listar productos

curl "https://tu-instancia.com/api/v1/storefront/catalog/products" \
  -H "X-Storefront-Slug: acme-b2c" \
  -H "Authorization: Bearer sf_dev_seed_acme_b2c_token"

Parámetros de filtro:

Parámetro	Tipo	Descripción
`search`	string	Busca en nombre, SKU
`categorySlug`	string	Filtra por categoría (slug)
`brandSlug`	string	Filtra por marca (slug)
`page`	number	Página (default: 1)
`pageSize`	number	Por página (default: 20, max: 100)

Ejemplo:

curl "https://tu-instancia.com/api/v1/storefront/catalog/products?categorySlug=ropa&pageSize=24" \
  -H "X-Storefront-Slug: acme-b2c" \
  -H "Authorization: Bearer sf_dev_seed_acme_b2c_token"

Respuesta (tarjeta de producto, datos optimizados para listado):

{
  "data": [
    {
      "id": "clx...",
      "name": "Playera Básica",
      "slug": "playera-basica",
      "sku": "PLY-001",
      "primaryCategorySlug": "ropa",
      "price": 350.00,
      "salePrice": 299.00,
      "currency": "MXN",
      "featured": false,
      "thumbnail": "https://...",
      "brand": { "name": "Marca Propia", "slug": "marca-propia" }
    }
  ],
  "pagination": {
    "page": 1,
    "pageSize": 24,
    "total": 47,
    "totalPages": 2,
    "hasNextPage": true,
    "hasPreviousPage": false
  }
}

Detalle de producto

curl "https://tu-instancia.com/api/v1/storefront/catalog/products/playera-basica" \
  -H "X-Storefront-Slug: acme-b2c" \
  -H "Authorization: Bearer sf_dev_seed_acme_b2c_token"

También puedes buscar por SKU con el parámetro ?by=sku:

curl "https://tu-instancia.com/api/v1/storefront/catalog/products/PLY-001?by=sku" \
  -H "X-Storefront-Slug: acme-b2c" \
  -H "Authorization: Bearer sf_dev_seed_acme_b2c_token"

La respuesta incluye variantes con opciones y disponibilidad, imágenes ordenadas, y campos personalizados públicos:

{
  "data": {
    "id": "clx...",
    "name": "Playera Básica",
    "slug": "playera-basica",
    "sku": "PLY-001",
    "description": "Playera de algodón 100%...",
    "price": 350.00,
    "salePrice": 299.00,
    "currency": "MXN",
    "brand": { "id": "...", "name": "Marca Propia", "slug": "marca-propia" },
    "primaryCategory": { "id": "...", "name": "Ropa", "slug": "ropa" },
    "variants": [
      {
        "id": "clx...",
        "sku": "PLY-001-S-BLK",
        "price": 350.00,
        "status": "active",
        "options": [
          { "optionName": "Talla", "valueName": "S" },
          { "optionName": "Color", "valueName": "Negro" }
        ]
      }
    ],
    "images": [
      { "url": "https://...", "altText": "Playera Básica negro talla S", "position": 1 }
    ]
  }
}

Árbol de categorías

curl "https://tu-instancia.com/api/v1/storefront/catalog/categories" \
  -H "X-Storefront-Slug: acme-b2c" \
  -H "Authorization: Bearer sf_dev_seed_acme_b2c_token"

Devuelve el árbol completo de categorías visibles para este storefront:

{
  "data": [
    {
      "id": "clx...",
      "name": "Textiles",
      "slug": "textiles",
      "description": null,
      "imageUrl": null,
      "children": [
        {
          "id": "clx...",
          "name": "Ropa",
          "slug": "ropa",
          "children": []
        }
      ]
    }
  ]
}

Usa esta respuesta para construir el menú de navegación del frontend.

Listado de marcas

curl "https://tu-instancia.com/api/v1/storefront/catalog/brands" \
  -H "X-Storefront-Slug: acme-b2c" \
  -H "Authorization: Bearer sf_dev_seed_acme_b2c_token"

{
  "data": [
    {
      "id": "clx...",
      "name": "Marca Propia",
      "slug": "marca-propia",
      "logoUrl": "https://...",
      "description": null
    }
  ]
}

Solo se incluyen marcas con al menos un producto activo visible para este storefront.

Gestión de storefronts (API admin)

Crear un storefront

curl -X POST "https://tu-instancia.com/api/v1/storefronts" \
  -H "Authorization: Bearer pk_..." \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Nueva Tienda B2B",
    "slug": "acme-b2b",
    "status": "coming_soon",
    "currency": "MXN",
    "taxRate": 0.16,
    "taxIncluded": false,
    "primaryColor": "#2e7d32"
  }'

Estados disponibles: active, maintenance, coming_soon, disabled.

Crear un token para el storefront

curl -X POST "https://tu-instancia.com/api/v1/storefronts/{storefrontId}/tokens" \
  -H "Authorization: Bearer pk_..." \
  -H "Content-Type: application/json" \
  -d '{"name": "Token producción"}'

El token se muestra una sola vez. Guárdalo de inmediato.

Revocar un token

curl -X DELETE "https://tu-instancia.com/api/v1/storefronts/{storefrontId}/tokens/{tokenId}" \
  -H "Authorization: Bearer pk_..."

Visibilidad de catálogo

Controla qué marcas y productos son visibles en cada storefront o empresa subsidiaria.

Otorgar visibilidad de marca

curl -X POST "https://tu-instancia.com/api/v1/brands/{brandId}/visibility" \
  -H "Authorization: Bearer pk_..." \
  -H "Content-Type: application/json" \
  -d '{"targetCompanyId": "clx_empresa_subsidiaria"}'

Establecer visibilidad de producto

curl -X PUT "https://tu-instancia.com/api/v1/products/{productId}/visibility" \
  -H "Authorization: Bearer pk_..." \
  -H "Content-Type: application/json" \
  -d '{
    "companyIds": ["clx_empresa_1", "clx_empresa_2"],
    "storefrontIds": ["clx_storefront_1"]
  }'

Los productos y marcas no visibles para la empresa del storefront no aparecen en los endpoints públicos de catálogo.

Tiendas

On this page