API de catálogo2026-11Vista previa

Productos

Una publicación que guardaste de una importación, con tu título, tus precios y las tiendas donde se vende.

Shopify es adonde se envían los productos. Los pedidos de los marketplaces en los que vende tu tienda de Shopify también nos llegan a través de Shopify: Conecta una tienda.
Una tienda de WooCommerce o Wix mantiene sus propios productos y envía sus pedidos con Crear un pedido.

Endpoints

GET/v1/productsListar productos
GET/v1/products/{id}Obtener un producto
PATCH/v1/products/{id}Actualizar un producto
POST/v1/products/{id}/pushEnviar a Shopify
DELETE/v1/products/{id}Eliminar un producto

El objeto Product

idstring: Empieza por prd_.
titlestring: Tu título. El del vendedor se queda en la importación.
statusstring: active, o paused (por ti, o por una regla de sincronización cuando un costo subió demasiado o el vendedor se quedó sin stock).
sourceobject: Marketplace, enlace de la publicación y vendedor en China.
options[]array: Nombres de opciones, como máximo tres, tal como los muestra tu tienda.
price_range, cost_rangeobject: Tus precios y los del vendedor, en todas las variantes.
channels[]array: Dónde está publicado: la tienda, su propio id de producto y su estado ahí.
syncobject: La regla de sincronización que sigue y cuándo leímos la publicación por última vez.
importstring: La importación de la que se guardó.

product

{
  "id": "prd_8f2k",
  "title": "Heavyweight Washed Hoodie",
  "status": "active",
  "source": {
    "marketplace": "weidian",
    "url": "https://weidian.com/item.html?itemID=7750970856",
    "seller": "Ruoyi Studio"
  },
  "options": ["Color", "Size"],
  "variants_count": 6,
  "price_range": {
    "min": { "amount": "49.99", "currency": "USD" },
    "max": { "amount": "54.99", "currency": "USD" }
  },
  "cost_range": {
    "min": { "amount": "38.00", "currency": "CNY" },
    "max": { "amount": "42.00", "currency": "CNY" }
  },
  "channels": [
    {
      "channel": "shopify",
      "shop": "acme-goods.myshopify.com",
      "external_id": "gid://shopify/Product/8812042",
      "status": "draft",
      "pushed_at": "2026-11-04T09:20:03Z"
    }
  ],
  "sync": {
    "rule": "rule_default",
    "last_checked_at": "2026-11-04T09:12:40Z"
  },
  "import": "imp_2c9d",
  "created_at": "2026-11-04T09:20:01Z",
  "updated_at": "2026-11-04T09:20:03Z"
}

Listar productos

GET/v1/products

Tus productos, del más reciente al más antiguo.

Alcanceproducts:read

Parámetros de consulta

statusstring: Opcional. active o paused.
channelstring: Opcional. shopify, para los publicados ahí.
changed_sincestring: Opcional. Una hora: solo los productos cuyo costo o stock cambió desde entonces.
limit, cursor: Pagination

curl "https://www.ninjabuy.com/api/v1/products?status=active&limit=2" \
  -H "Authorization: Bearer $NINJABUY_API_KEY" \
  -H "NinjaBuy-Version: 2026-11"

Response 200

HTTP/2 200 OK

{
  "data": [
    {
      "id": "prd_8f2k",
      "title": "Heavyweight Washed Hoodie",
      "status": "active",
      "variants_count": 6
    },
    {
      "id": "prd_1x0a",
      "title": "Canvas Tote",
      "status": "active",
      "variants_count": 3
    }
  ],
  "has_more": true,
  "cursor": "c_1x0a"
}

Obtener un producto

GET/v1/products/{id}

Un producto con su fuente, canales y estado de sincronización. Sus variantes tienen su propia ruta.

Alcanceproducts:read

Parámetros de ruta

idstringobligatorio: El id del producto.

Errores

Estado	Tipo	Cuándo
404	not-found	No existe ese producto en esta cuenta.

curl "https://www.ninjabuy.com/api/v1/products/prd_8f2k" \
  -H "Authorization: Bearer $NINJABUY_API_KEY" \
  -H "NinjaBuy-Version: 2026-11"

Response 200

HTTP/2 200 OK

{
  "id": "prd_8f2k",
  "title": "Heavyweight Washed Hoodie",
  "status": "active",
  "source": {
    "marketplace": "weidian",
    "url": "https://weidian.com/item.html?itemID=7750970856",
    "seller": "Ruoyi Studio"
  },
  "options": ["Color", "Size"],
  "variants_count": 6,
  "price_range": {
    "min": { "amount": "49.99", "currency": "USD" },
    "max": { "amount": "54.99", "currency": "USD" }
  },
  "cost_range": {
    "min": { "amount": "38.00", "currency": "CNY" },
    "max": { "amount": "42.00", "currency": "CNY" }
  },
  "channels": [
    {
      "channel": "shopify",
      "shop": "acme-goods.myshopify.com",
      "external_id": "gid://shopify/Product/8812042",
      "status": "draft",
      "pushed_at": "2026-11-04T09:20:03Z"
    }
  ],
  "sync": {
    "rule": "rule_default",
    "last_checked_at": "2026-11-04T09:12:40Z"
  },
  "import": "imp_2c9d",
  "created_at": "2026-11-04T09:20:01Z",
  "updated_at": "2026-11-04T09:20:03Z"
}

Cambia el título o la descripción, o pausa y reanuda el producto. Envía solo lo que cambia. Los precios son por variante (Variantes); un producto enviado lleva el cambio a tu tienda en su siguiente envío.

Alcanceproducts:write

Parámetros de ruta

idstringobligatorio: El id del producto.

Cuerpo

titlestring: Opcional.
descriptionstring: Opcional. HTML que muestra tu tienda.
statusstring: Opcional. active o paused. Paused pone el stock a 0 en tus canales.
sync_rulestring: Opcional. Un id de regla de sincronización; la regla por defecto si es null.

Errores

Estado	Tipo	Cuándo
404	not-found	No existe ese producto en esta cuenta.

curl -X PATCH "https://www.ninjabuy.com/api/v1/products/prd_8f2k" \
  -H "Authorization: Bearer $NINJABUY_API_KEY" \
  -H "NinjaBuy-Version: 2026-11" \
  -H "Content-Type: application/json" \
  -d '{ "status": "paused" }'

Response 200

HTTP/2 200 OK

{
  "id": "prd_8f2k",
  "title": "Heavyweight Washed Hoodie",
  "status": "paused",
  "source": {
    "marketplace": "weidian",
    "url": "https://weidian.com/item.html?itemID=7750970856",
    "seller": "Ruoyi Studio"
  },
  "options": ["Color", "Size"],
  "variants_count": 6,
  "price_range": {
    "min": { "amount": "49.99", "currency": "USD" },
    "max": { "amount": "54.99", "currency": "USD" }
  },
  "cost_range": {
    "min": { "amount": "38.00", "currency": "CNY" },
    "max": { "amount": "42.00", "currency": "CNY" }
  },
  "channels": [
    {
      "channel": "shopify",
      "shop": "acme-goods.myshopify.com",
      "external_id": "gid://shopify/Product/8812042",
      "status": "draft",
      "pushed_at": "2026-11-04T09:20:03Z"
    }
  ],
  "sync": {
    "rule": "rule_default",
    "last_checked_at": "2026-11-04T09:12:40Z"
  },
  "import": "imp_2c9d",
  "created_at": "2026-11-04T09:20:01Z",
  "updated_at": "2026-11-04T09:20:03Z"
}

Enviar a Shopify

POST/v1/products/{id}/push

Publica el producto en tu tienda de Shopify vinculada: un producto de Shopify, una variante por cada SKU que conservaste, sus fotos y cada variante con stock en la ubicación Fulfilled by NinjaBuy, para que sus pedidos nos lleguen.

El primer envío lo crea como borrador: el título y las fotos vienen de un marketplace chino, así que léelos antes que tus compradores y luego publícalo en Shopify.
Volver a enviar actualiza el mismo producto de Shopify: los precios y el stock se fijan de nuevo y las variantes que descartaste se eliminan. El estado, el título, la descripción y las fotos se quedan como los dejaste en Shopify, salvo que envíes otros nuevos.
El stock es la cantidad del vendedor, con un tope de 100: compramos bajo demanda, así que es cuántos pedidos acepta Shopify antes de mostrarlo como agotado.
Tu tienda debe vender en US$, ya que los precios están en esa moneda. Las variantes agotadas se omiten y se indican en skipped[].

Alcanceproducts:write

Parámetros de ruta

idstringobligatorio: El id del producto.

Cuerpo

shopstring: Qué tienda vinculada, como acme-goods.myshopify.com. Solo es necesario si vinculaste varias.
title, descriptionstring: Opcional. Se envían a Shopify solo cuando los envías.

Errores

Estado	Tipo	Cuándo
409	no-linked-store	No hay ninguna tienda de Shopify vinculada a esta cuenta, o hay varias y falta `shop`.
409	store-not-ready	El acceso de la tienda caducó, o nuestra ubicación aún no está configurada: abre una vez la app de NinjaBuy en Shopify.
422	store-currency	La tienda no vende en US$.
422	too-many-options	La publicación tiene más de tres opciones; Shopify admite tres.
422	unprocessable	Todas las variantes están agotadas, o Shopify rechazó un campo; detail transmite sus palabras.

curl -X POST "https://www.ninjabuy.com/api/v1/products/prd_8f2k/push" \
  -H "Authorization: Bearer $NINJABUY_API_KEY" \
  -H "NinjaBuy-Version: 2026-11" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{ "shop": "acme-goods.myshopify.com" }'

Response 200

HTTP/2 200 OK

{
  "channel": "shopify",
  "shop": "acme-goods.myshopify.com",
  "external_id": "gid://shopify/Product/8812042",
  "status": "draft",
  "created": true,
  "variants": 5,
  "skipped": [{ "sku": "5187209555", "reason": "sold_out" }],
  "admin_url": "https://admin.shopify.com/store/acme-goods/products/8812042"
}

Eliminar un producto

DELETE/v1/products/{id}

Deja de sincronizarlo y pone su stock a 0 en tus canales; el producto de Shopify queda para que lo archives. Los pedidos ya hechos se envían igualmente.

Alcanceproducts:write

Parámetros de ruta

idstringobligatorio: El id del producto.

Errores

Estado	Tipo	Cuándo
404	not-found	No existe ese producto en esta cuenta.

curl -X DELETE "https://www.ninjabuy.com/api/v1/products/prd_8f2k" \
  -H "Authorization: Bearer $NINJABUY_API_KEY" \
  -H "NinjaBuy-Version: 2026-11"

Response 200

HTTP/2 200 OK

{ "id": "prd_8f2k", "deleted": true }

El objeto Product

Listar productos

Parámetros de consulta

Obtener un producto

Parámetros de ruta

Errores

Actualizar un producto

Parámetros de ruta

Cuerpo

Errores

Enviar a Shopify

Parámetros de ruta

Cuerpo

Errores

Eliminar un producto

Parámetros de ruta

Errores