Saltar al contenido principal

Products API

Todos los endpoints están bajo /api/v1/{platform}/products donde platform es shopify o bigcommerce.

Listar productos​

GET /api/v1/shopify/products?limit=50&offset=0&storeId=...
Authorization: Bearer sk_live_...
X-Tenant-Id: <tenant-id>

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/shopify/products/...",
      "llm_url": "/api/shopify/products/...llm"
    }
  ],
  "total": 281,
  "pagination": { "limit": 50, "offset": 0, "count": 50, "has_more": true }
}

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.

Variante optimizada para LLM​

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

Devuelve un JSON condensado para consumo por LLM — identidad, reasoning, quality_scores, pricing, market_context, más una cadena pre-computada summary_for_ai.

JSON-LD (schema.org/Product)​

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

Devuelve application/ld+json con @type: Product, offers, brand y los scores mapeados a additionalProperty[] como PropertyValue. Listo para crawler.

Señales SEO meta​

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

Devuelve señales SEO en 3 longitudes de descripción (≤160 chars, ≤300, sin límite) + URL canónica + keywords.

Re-enriquecer un solo producto​

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

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

Las hints son opcionales; son los mismos campos que recoge el Enrichment Wizard.

Re-enriquecimiento masivo​

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

pending=true solo re-enriquece los productos marcados enrichment_pending. Sin él, re-enriquece todos los productos del tenant (peligroso — usa la confirmación en dos pasos del dashboard).

Versiones + rollback​

GET  /api/v1/shopify/enrich/:id/versions                 → lista las versiones pasadas
POST /api/v1/shopify/enrich/:id/rollback?version=N       → restaura la versión N

El rollback en sí mismo crea un snapshot nuevo, así que es reversible.

Actualizar el enriquecimiento de un producto manualmente​

PATCH /api/v1/shopify/products/:id        # también disponible en /bigcommerce/
{
  "core_identity": "...",
  "reasoning": { ... },
  "synthetic_properties": {
    "durability_score": 8,
    "competitors_owner_provided": [
      { "brand": "Nike", "model": "Air Max 90", "ref_price": "120 €", "notes": "competidor directo" }
    ]
  }
}

Whitelist de campos top-level: core_identity, reasoning, synthetic_properties. Marca el producto con:

  • metadata.manually_edited = true — los re-enriquecimientos futuros muestran una confirmación OVERWRITE de dos pasos en el dashboard
  • metadata.competitors_source = 'owner' — solo cuando synthetic_properties.competitors_owner_provided es un array no vacío. Fija autoridad sobre la lista de competidores para que el re-enrichment no la regenere.

Actualizar metadata de categoría / colección​

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

Whitelist de campos para bulk-edit SEO:

{
  "name": "...",
  "description": "...",
  "slug": "...",
  "imageUrl": "https://...",
  "metaTitle": "...",
  "metaDescription": "..."
}

Tenant-scoped — el tenant del request debe ser propietario de la entidad o el endpoint devuelve 404. Strings vacíos se coaccionan a null. Devuelve la fila actualizada.

Verificar storefront — diff por producto​

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

Recupera tu storefront en vivo y compara cada signal que Clione propagó (meta_description, meta_title, jsonld, canonical, meta_keywords) contra lo que el HTML contiene realmente ahora mismo.

Estados per-signal: identical | different | missing_in_storefront | never_propagated | propagation_failed | parse_error.

La respuesta incluye un summary (match_rate excluye never_propagated), un diff per-signal, y — para JSON-LD — un breakdown estructural de added/removed/changed keys.

Side effect: refresca verifiedAt + verifiedPresent en los PropagationRecord subyacentes.

Verificar storefront — batch​

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

Mismo contrato que /diff/:id pero para un array de productos. Agrega totales cruzados + devuelve resultados per-producto bajo results[]. Un producto lento no mata el batch — los fallos vienen como { entity_id, error, summary: null }.

Usado por el botón Verify storefront del dashboard en la overview del store. Cap duro a ~50 productos por call en la UI para mantener tiempos de respuesta manejables.