Saltar al contenido

Merchandiser API: colecciones ordenadas y métricas de producto

Dos API conectan tus propios sistemas con Merchandiser: una devuelve los productos ordenados de una colección y la otra recibe las ventas de tus productos.

Descripción general

Las tiendas que usan una plataforma con una integración ya preparada no necesitan la API: Merchandiser escribe por ellas el orden de los productos en la plataforma. La API es para todo lo demás.

API de colecciones
Acceso de lectura a tus colecciones y a los productos ordenados de cada una. Para plataformas a medida y tiendas headless. Sin token; las solicitudes se identifican con el UID de tu cuenta.
API de métricas de producto
Acceso de escritura a las métricas de ventas de tus productos. Para enviar las ventas online y en tienda física desde un ERP o un almacén de datos. Requiere un token.

Todas las direcciones siguientes empiezan por la URL base. El UID de tu cuenta y la dirección de cada colección, lista para copiar, se muestran en la página Integración API del panel.

URL base

https://api.merchandiser.com.tr/v1

API de colecciones

Listar las colecciones de un tipo

GET https://api.merchandiser.com.tr/v1/accounts/{account_uid}/collections/{type}

{type} es uno de estos valores: category, brand, list, page, widget u other. La respuesta lista las colecciones activas de ese tipo:

Ejemplo de respuesta (abreviado)

{
  "type": "category",
  "total_records": 2,
  "collections": [
    {
      "id": 1042,
      "name": "Women > Jackets",
      "type": "category",
      "code": "women-jackets",
      "path": "/women-jackets",
      "smart": false,
      "sort_type": {"id": 7, "uid": "0b0c…", "name": "Merchandiser AI"},
      "updated": 1760000000.0
    }
  ]
}

code es el identificador que tu tienda usa para la colección. updated es el momento de la última ordenación como marca de tiempo Unix; compáralo con el último valor que viste para saber si hay que volver a obtener una colección.

Obtener los productos ordenados de una colección

GET https://api.merchandiser.com.tr/v1/accounts/{account_uid}/collections/{type}/{code}?page=1&size=50

También se puede acceder a una colección por su propio UID: 

GET https://api.merchandiser.com.tr/v1/collections/{collection_uid}
page
La página que se devuelve, empezando por 1.
size
El número de productos por página. 50 si se omite.
expand
true devuelve cada producto con su nombre, marca, precios, valoración, dirección e imagen. Sin él, un producto es su SKU y su posición.
ws_code
true devuelve el código ERP de cada producto en el campo sku en lugar de su SKU.
color, gender
Devuelve solo los productos de esos colores o géneros. Ambos se pueden repetir.
sort_by
El UID de un tipo de ordenación. Devuelve la colección ordenada según ese tipo de ordenación en lugar de su orden guardado.

Ejemplo de respuesta

{
  "collection": "Women > Jackets",
  "code": "women-jackets",
  "type": "category",
  "id": 1042,
  "page": 1,
  "size": 50,
  "total_pages": 3,
  "total_records": 128,
  "has_next": true,
  "has_prev": false,
  "products": [
    {"sku": "AB-123", "position": 1},
    {"sku": "AB-124", "position": 2}
  ]
}

Los productos se devuelven en su orden, pines incluidos. Solo se devuelven los productos que están en stock. Solicita la página siguiente mientras has_next sea true.

Con expand=true, cada producto incluye además estos campos: name, brand, sale_price, list_price, discount_rate, currency, rating, reviews, url e image_url.

Límites y errores

Las solicitudes tienen un límite de frecuencia por dirección IP. Cada respuesta incluye una cabecera X-Api-Call-Limit con el número de solicitudes que te quedan en la ventana actual. Indícanos las direcciones de tus servidores y las eximiremos del límite.

400
Un parámetro no es válido; por ejemplo, un page o un size que no es un número.
404
La cuenta o la colección no existe o no está activa.
429
Demasiadas solicitudes. Inténtalo de nuevo más tarde.

API de métricas de producto

Esta solicitud actualiza de forma masiva las métricas de ventas de tus productos. Se autentica con un token de métricas de producto, que se emite para tu cuenta si lo solicitas. 

POST https://api.merchandiser.com.tr/v1/products/metrics
Content-Type: application/json
Authorization: Bearer <YOUR-PRODUCT-METRICS-TOKEN>

El cuerpo es una lista de hasta 1.000 objetos. Cada objeto necesita un sku y al menos una métrica. Las métricas se pueden enviar como números o como cadenas numéricas y no deben ser negativas. Una métrica que no envías queda intacta. Los SKU que no existen en tu cuenta se notifican en la respuesta y nunca se crean.

sku
El SKU del producto que se actualiza. Obligatorio.
daily_purchase, weekly_purchase, monthly_purchase
Ventas online del último día, la última semana y el último mes.
daily_offline_purchase, weekly_offline_purchase, monthly_offline_purchase
Ventas offline (en tienda física) del último día, la última semana y el último mes.
total_daily_purchase, total_weekly_purchase, total_monthly_purchase
Ventas online y offline juntas.

Cómo se mantienen sincronizados los totales

  • Enviar una métrica online la sobrescribe y recalcula el total de ese periodo como online más offline, con el valor offline ya almacenado (o 0 si no hay ninguno).
  • Enviar una métrica offline funciona igual, con el valor online almacenado.
  • Enviar un total sobrescribe ese total. Si envías un total junto con la métrica online u offline del mismo periodo, prevalece el total que enviaste.

Ejemplo de solicitud

[
  {"sku": "AB-123", "daily_purchase": 4, "daily_offline_purchase": 6},
  {"sku": "AB-124", "weekly_purchase": 18, "monthly_purchase": 63},
  {"sku": "AB-125", "total_weekly_purchase": 42}
]

La misma solicitud con cURL

curl -X POST https://api.merchandiser.com.tr/v1/products/metrics \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <YOUR-PRODUCT-METRICS-TOKEN>" \
  -d '[{"sku": "AB-123", "daily_purchase": 4, "daily_offline_purchase": 6}]'

Ejemplo de respuesta

{
  "status": 200,
  "elapsed": 0.14,
  "message": "Given product metrics processed successfully",
  "errors": ["1 SKU(s) were not found for this account: AB-999"],
  "data": {
    "received": 4,
    "updated": 3,
    "skipped": 1,
    "unknown_skus": ["AB-999"]
  }
}
data.received
El número de elementos de la solicitud.
data.updated
El número de productos cuyas métricas se actualizaron.
data.skipped
El número de elementos que no se aplicaron: elementos no válidos y SKU desconocidos.
data.unknown_skus
Los SKU que no existen en tu cuenta (los 50 primeros).
errors
El motivo de cada elemento omitido o parcialmente no válido. Una respuesta con errores sigue siendo un 200: los elementos válidos se aplican.

Errores

400
Falta el token o el cuerpo no es una lista de objetos.
403
La cuenta está suspendida.
404
El token no es válido.
413
Se enviaron más de 1.000 elementos en una sola solicitud.
415
La cabecera Content-Type no es application/json.

Para qué se usan las ventas

Las métricas que envías se convierten en señales de ranking. Una regla puede clasificar solo por las ventas online o por los totales, de modo que los productos que se venden bien en tus tiendas físicas también puedan subir en tu sitio web. Merchandiser AI aprende de los totales cuando están disponibles.

Preguntas frecuentes

¿Necesito la API para usar Merchandiser?

No en una plataforma con integración, donde el orden se escribe en la tienda por ti. La API es para tiendas a medida y headless, y para enviar ventas desde tus propios sistemas.

¿La API de colecciones requiere autenticación?

No hace falta ningún token para leer una colección. Las solicitudes se identifican con el UID de tu cuenta y tienen un límite de frecuencia. La API de métricas de producto requiere un token.

¿Puedo enviar las ventas en tienda física a Merchandiser?

Sí. La API de métricas de producto acepta las ventas online, las ventas offline (en tienda física) y sus totales del último día, la última semana y el último mes de cada producto.

¿Quieres verlo en tus propias colecciones?

Solicita una demo y te mostraremos cómo funciona con tu catálogo y la plataforma de tu tienda.

Solicita una demo Ver los planes