Products API

Todos los endpoints están bajo /api/v1/{platform}/, donde platform es shopify, bigcommerce o woocommerce. Autentícate con una API key o con una sesión del dashboard; mira Autenticación.

Listar productos

GET /api/v1/shopify/products?limit=50&offset=0&storeId=...
Authorization: Bearer sk_live_...

limit vale 20 por defecto (máximo 5000). storeId limita la lista a una tienda.

Respuesta:

{
  "products": [
    {
      "id": "...",
      "title": "...",
      "vendor": "...",
      "price": 29.99,
      "currency": "EUR",
      "identity": "...",
      "enrichment_status": "enriched",
      "manually_edited": false,
      "last_enriched_at": "2026-04-14T...",
      "url": "/api/v1/shopify/products/...",
      "llm_url": "/api/v1/shopify/products/....llm"
    }
  ],
  "total": 281,
  "pagination": { "limit": 50, "offset": 0, "count": 50, "total": 281, "has_more": true }
}

En BigCommerce, cada fila trae además jsonld_url y meta_url.

Obtener un producto (payload semántico completo)

GET /api/v1/shopify/products/:id

Devuelve el SemanticProduct completo con core_identity, reasoning, synthetic_properties, technical_details, metadata. Envía Accept: text/markdown para recibir la versión en Markdown.

Variante optimizada para LLM

GET /api/v1/shopify/products/:id.llm

Devuelve un JSON condensado para consumo por LLM: identity, reasoning, quality_scores, pricing, market_context, más una cadena pre-calculada summary_for_ai.

JSON-LD

GET /api/v1/shopify/products/:id.jsonld

Devuelve application/ld+json: el @graph de schema.org del producto, el mismo grafo que Clione publica en el storefront. La cabecera de respuesta X-Schema-Nodes lista el @type de cada nodo.

Markdown (text/markdown)

GET /api/v1/shopify/products/:id.md

Devuelve text/markdown; charset=utf-8 con un documento Markdown estructurado: título, core identity, detalles del producto, quality scores, guía de compra, contexto de mercado, keywords de búsqueda e imágenes.

Señales meta SEO

GET /api/v1/shopify/products/:id.meta

Devuelve meta_title, meta_description en tres longitudes (seo ≤160 caracteres, extended ≤300, full sin límite), canonical, keywords, og (campos Open Graph y Twitter Card) y un objeto links que apunta a los demás formatos (jsonld, llm, md, self). La URL canónica se envía también como cabecera Link.

---

Endpoints de señales para todos los tipos de entidad

Todos los tipos de entidad exponen los mismos cuatro formatos de señal con los mismos sufijos. Solo cambia la ruta base, y los campos de cada formato varían según el tipo de entidad.

Rutas base

Plataforma	Entidad	Ruta base
Shopify	Products	/api/v1/shopify/products
Shopify	Collections	/api/v1/shopify/collections
Shopify	Pages	/api/v1/shopify/pages
BigCommerce	Products	/api/v1/bigcommerce/products
BigCommerce	Categories	/api/v1/bigcommerce/categories
BigCommerce	Pages	/api/v1/bigcommerce/pages
WooCommerce	Products	/api/v1/woocommerce/products
WooCommerce	Categories	/api/v1/woocommerce/categories
WooCommerce	Pages	/api/v1/woocommerce/pages

Formatos de señal

Sufijo	Content-Type	Descripción
/:id.jsonld	application/ld+json	@graph JSON-LD de schema.org para la entidad.
/:id.llm	application/json	Representación optimizada para LLM: identidad, contexto, keywords, datos de enrichment.
/:id.md	text/markdown; charset=utf-8	Markdown estructurado para crawlers de LLM.
/:id.meta	application/json	Meta title, descripción, keywords, Open Graph, más links a los demás formatos.

:id es el id de Clione de la entidad, tal como lo devuelven los endpoints de listado.

Ejemplos

# Collection JSON-LD (Shopify)
GET /api/v1/shopify/collections/:id.jsonld

# Category Markdown (BigCommerce)
GET /api/v1/bigcommerce/categories/:id.md

# Page meta signals
GET /api/v1/shopify/pages/:id.meta
GET /api/v1/woocommerce/pages/:id.meta

Forma de la respuesta de .meta (categorías, colecciones, páginas)

{
  "collection_id": "...",
  "meta_title": "Summer 2026 | Store Name",
  "meta_description": "AI-enriched description...",
  "keywords": ["summer", "collection", "2026"],
  "og": {
    "og_title": "...",
    "og_description": "...",
    "og_type": "website",
    "og_image": { "url": "...", "alt": "..." },
    "og_url": "...",
    "og_site_name": "...",
    "twitter_card": "...",
    "twitter_title": "...",
    "twitter_description": "...",
    "twitter_image": "..."
  },
  "links": {
    "jsonld": "/api/v1/shopify/collections/<id>.jsonld",
    "llm": "/api/v1/shopify/collections/<id>.llm",
    "md": "/api/v1/shopify/collections/<id>.md",
    "self": "/api/v1/shopify/collections/<id>"
  }
}

La clave del id depende del tipo de entidad: category_id, collection_id o page_id.

---

Re-enriquecer un producto

POST /api/v1/shopify/enrich/:id
Authorization: Bearer <JWT>
Content-Type: application/json

{
  "hints": {
    "target_audience": "...",
    "material_composition": "..."
  }
}

Los hints son opcionales; son los mismos campos que recoge el Enrichment Wizard. Si el enrichment tarda más que el plazo de la petición, la API responde 202 con un jobId; consulta GET /api/v1/shopify/enrich/jobs/:jobId para obtener el resultado.

Re-enrichment masivo

POST /api/v1/shopify/enrich/all?pending=true&storeId=<storeId>

pending=true solo re-enriquece los productos marcados como pendientes; failed=true, solo aquellos cuyo último enrichment falló. Sin ninguno de los dos, re-enriquece todos los productos de la tienda; el dashboard pide una confirmación, con el coste en créditos, antes de hacerlo.

Versiones + rollback

GET  /api/v1/shopify/enrich/:id/versions                 → list past versions
POST /api/v1/shopify/enrich/:id/rollback?version=N       → restore version N

El propio rollback crea una nueva instantánea de versión, así que es reversible.

Editar a mano el enrichment de un producto

PATCH /api/v1/shopify/products/:id        # also on /bigcommerce/ and /woocommerce/
{
  "core_identity": "...",
  "reasoning": { ... },
  "synthetic_properties": {
    "durability_score": 8,
    "competitors_owner_provided": [
      { "brand": "Nike", "model": "Air Max 90", "ref_price": "€120", "notes": "direct competitor" }
    ]
  }
}

Campos de primer nivel permitidos: core_identity, reasoning, synthetic_properties, seo_overrides. Marca el producto con:

• metadata.manually_edited = true: los re-enrichments posteriores muestran en el dashboard una confirmación de sobrescritura en dos pasos
• metadata.competitors_source = 'owner': solo cuando synthetic_properties.competitors_owner_provided es un array no vacío, para que el re-enrichment no regenere la lista de competidores.

Editar metadatos de categoría / colección

PATCH /api/v1/shopify/collections/:id      # Shopify → "collections"
PATCH /api/v1/bigcommerce/categories/:id   # BigCommerce → "categories"

Campos permitidos:

{
  "name": "...",
  "description": "...",
  "slug": "...",
  "imageUrl": "https://...",
  "metaTitle": "...",
  "metaDescription": "...",
  "seo_overrides": { ... },
  "buyerIntents": [ ... ]
}

Con scope de tenant: el tenant de la petición tiene que ser dueño de la entidad o el endpoint devuelve 404. Los strings vacíos se convierten en null. La respuesta es { "data": <fila actualizada> }.

Verificar el storefront — diff por producto

GET /api/v1/shopify/diff/:id?store_url=https://yourstore.com

Va a tu storefront en vivo y compara cada señal que Clione propagó (por ejemplo meta_description, meta_title, jsonld, faq_jsonld, og_tags, canonical, meta_keywords) con lo que contiene el HTML ahora mismo.

Estados por señal: identical | different | missing_in_storefront | never_propagated | propagation_failed | parse_error | unverifiable (no se pudo descargar el storefront).

La respuesta incluye un resumen (match_rate excluye never_propagated), un diff por señal y, para el JSON-LD, un desglose estructural de las claves añadidas, eliminadas y cambiadas.

Verificar el storefront — en lote

GET /api/v1/shopify/diff?store_url=https://yourstore.com&product_ids=id1,id2,id3

Mismo contrato que /diff/:id, sobre varios productos. Agrega los totales y devuelve los resultados por producto en results[]. Un producto lento no tumba el lote: los fallos vuelven como { entity_id, error, summary: null }.