Consultar un producto

Este endpoint devuelve el producto completo, con soporte para proyecciones extendidas vía ?extend=. Esta página también cubre dos endpoints relacionados sobre un producto puntual: productos similares por embeddings y el resumen de variantes/opciones.

Úsalo cuando necesites:

  • Mostrar la ficha completa de un producto en tu aplicación.
  • Traer inventario por variante y ubicación sin una llamada adicional (extend=inventory).
  • Sugerir productos relacionados en una página de detalle.
  • Obtener solo la estructura de variantes/opciones de un producto sin traer el resto de sus campos.

Endpoint

Obtiene un producto por su ID o por su SKU

idstringrequired

ObjectId (_id) o SKU del producto. El endpoint detecta automáticamente cuál de los dos le enviaste.

extendstring

Lista separada por comas: variants, options, description, bindings, metadata, inventory, dimensions, seo, all.

200
{
  "id": "65f3a1b2c4d5e6f7a8b9c0e1",
  "sku": "CAM-ROJO-M",
  "status": "active",
  "productType": "physical",
  "title": { "value": "Camisa Roja Talla M", "translations": [] },
  "description": { "value": "Camisa de algodón 100%, corte regular.", "translations": [] },
  "price": 499.00,
  "compareAtPrice": 599.00,
  "currency": "MXN",
  "taxable": true,
  "brand": "Fenicia Basics",
  "category": { "id": "cat-1", "name": "Playeras", "path": "ropa/playeras", "selectable": true },
  "tags": ["playeras", "temporada-verano"],
  "media": [
    {
      "id": "m1",
      "src": "https://cdn.fenicia.io/img/cam-rojo-m.jpg",
      "type": "image",
      "position": 0,
      "alt": { "value": "Camisa roja talla M", "translations": [] }
    }
  ],
  "variants": [
    {
      "id": "65f3a1b2c4d5e6f7a8b9c0f1",
      "sku": "CAM-ROJO-M-CH",
      "parentSku": "CAM-ROJO-M",
      "title": { "value": "Camisa Roja - Chica" },
      "price": 499.00,
      "position": 0,
      "taxable": true,
      "options": [{ "id": "opt-talla", "name": "Talla", "value": "CH" }],
      "bindings": []
    }
  ],
  "options": [],
  "attributes": [],
  "bindings": [],
  "seo": { "metaTitle": "Camisa Roja Talla M", "metaDescription": "Camisa de algodón para hombre.", "slug": "camisa-roja-talla-m" },
  "minAlertStock": 5,
  "sellIfOutOfStock": false
}
404
{ "code": "not-found", "message": "Product not found" }

Permiso requerido: products:read

Parámetros de ruta

ParámetroTipoDescripción
idstring_id de MongoDB (24 caracteres hex) o SKU del producto. Se detecta automáticamente cuál de los dos formatos enviaste.

El parámetro extend

extend acepta una lista separada por comas de campos adicionales, de un conjunto cerrado: variants, options, description, bindings, metadata, inventory, dimensions, seo, all.

extend=inventory y extend=all adjuntan stock real

Cuando incluyes inventory (o all) en extend, la respuesta adjunta el inventario disponible por variante y por ubicación — el stock de una variante no vive en el documento del producto (se resuelve por join contra la colección de inventario separada), así que sin este extend el campo de stock simplemente no aparece.

curl "https://api.fenicia.io/products/CAM-ROJO-M?extend=inventory,seo" \
  -H "Authorization: Bearer fkapi_tu_api_key"

Tip

Para el modelo de datos completo del producto (todos los campos, sub-shapes de precio/costo/media/binding, y las divergencias conocidas entre el schema real y el tipo TS público), consulta el modelo de datos del producto.

Ejemplos

curl https://api.fenicia.io/products/CAM-ROJO-M \
  -H "Authorization: Bearer fkapi_tu_api_key"

Respuesta plana, sin envelope data

A diferencia de otros dominios de la API de Fenicia, este endpoint responde el objeto Product directamente en la raíz del JSON — no envuelto en {data: ...}.

Productos relacionados

Sugiere productos similares por embeddings semánticos

skustringrequired

SKU del producto de referencia.

limitnumber

Cantidad de resultados. Default: 10. Máximo: 50.

inStockboolean

Limita los resultados a productos con existencia disponible.

200
{
  "products": [
    { "id": "65f3a1b2c4d5e6f7a8b9c0e2", "sku": "CAM-AZUL-M", "score": 0.87 }
  ],
  "count": 1,
  "sourceSku": "CAM-ROJO-M"
}
404
{ "code": "not-found", "message": "Product not found: CAM-ROJO-M" }

Permiso requerido: products:read

Los resultados usan búsqueda por embeddings con un umbral mínimo de similitud (minScore: 0.3) — productos por debajo de ese umbral no aparecen, aunque pertenezcan a la misma categoría. El 404 se dispara cuando el mensaje de error interno contiene el texto "not found" (por ejemplo, cuando el sourceSku no existe).

Resumen de variantes y opciones

Devuelve solo la estructura de variantes y opciones de un producto, sin el resto de sus campos

skustringrequired

SKU del producto padre.

200
{
  "sku": "CAM-ROJO-M",
  "variants": [
    {
      "id": "65f3a1b2c4d5e6f7a8b9c0f1",
      "sku": "CAM-ROJO-M-CH",
      "title": { "value": "Camisa Roja - Chica" },
      "price": 499.00,
      "position": 0,
      "options": [{ "id": "opt-talla", "name": "Talla", "value": "CH" }]
    }
  ],
  "options": [{ "id": "opt-talla", "name": "Talla", "values": ["CH", "M", "G"] }],
  "hasVariants": true,
  "hasOptions": true
}
404
{ "code": "not-found", "message": "Product CAM-ROJO-M not found" }

Permiso requerido: products:read

Este mismo endpoint se documenta también en Variantes y media, junto con el único endpoint de escritura sobre variantes existentes.

Errores

CódigoStatusDescripción
not-found404No existe un producto que resuelva el id/SKU indicado en tu tenant.

Los códigos de autenticación (token inválido, permiso faltante) son los mismos en toda la plataforma — consulta el catálogo completo de errores.

Aislamiento por tenant

Solo puedes consultar productos de tu propio tenant. Intentar acceder a un producto de otro tenant devuelve 404, nunca información cruzada.

Siguientes pasos