API каталога2026-11Предпросмотр

Товары

Товар, сохранённый из импорта, с вашим названием, ценами и магазинами, где он продаётся.

Товары отправляются в Shopify. Заказы с маркетплейсов, на которых продаёт ваш магазин Shopify, тоже доходят до нас через Shopify: Подключение магазина.
Магазин WooCommerce или Wix хранит свои товары и передаёт заказы через Создание заказа.

Эндпоинты

GET/v1/productsСписок товаров
GET/v1/products/{id}Получение товара
PATCH/v1/products/{id}Изменение товара
POST/v1/products/{id}/pushОтправить в Shopify
DELETE/v1/products/{id}Удаление товара

Объект Product

idstring: Начинается с prd_.
titlestring: Ваше название. Название продавца остаётся в импорте.
statusstring: active или paused (вами либо правилом синхронизации, когда себестоимость выросла слишком сильно или у продавца закончился товар).
sourceobject: Маркетплейс, ссылка на карточку и продавец в Китае.
options[]array: Названия опций, не больше трёх, как их показывает ваш магазин.
price_range, cost_rangeobject: Ваши цены и цены продавца по всем вариантам.
channels[]array: Где выставлен: магазин, его собственный ID товара и статус там.
syncobject: Правило синхронизации, которому он следует, и когда мы последний раз читали карточку.
importstring: Импорт, из которого он сохранён.

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"
}

Список товаров

GET/v1/products

Ваши товары, от новых к старым.

Область доступаproducts:read

Параметры запроса

statusstring: Необязательно. active или paused.
channelstring: Необязательно. shopify — для выставленных там.
changed_sincestring: Необязательно. Время: только товары, у которых с тех пор изменились себестоимость или остатки.
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"
}

Получение товара

GET/v1/products/{id}

Один товар с источником, каналами и состоянием синхронизации. Его варианты — на отдельном маршруте.

Область доступаproducts:read

Параметры пути

idstringобязательно: ID товара.

Ошибки

Статус	Тип	Когда
404	not-found	В этом аккаунте нет такого товара.

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"
}

Измените название или описание, поставьте на паузу или возобновите. Отправляйте только то, что меняется. Цены задаются по вариантам (Варианты); отправленный товар переносит изменение в магазин при следующей отправке.

Область доступаproducts:write

Параметры пути

idstringобязательно: ID товара.

Тело

titlestring: Необязательно.
descriptionstring: Необязательно. HTML, который показывает ваш магазин.
statusstring: Необязательно. active или paused. Paused обнуляет остаток на ваших каналах.
sync_rulestring: Необязательно. ID правила синхронизации; при null — правило по умолчанию.

Ошибки

Статус	Тип	Когда
404	not-found	В этом аккаунте нет такого товара.

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"
}

Отправить в Shopify

POST/v1/products/{id}/push

Выставляет товар в привязанном магазине Shopify: один товар Shopify, по варианту на каждый оставленный SKU, его фото, каждый вариант с запасом на локации Fulfilled by NinjaBuy, чтобы заказы на него приходили к нам.

Первая отправка создаёт его как черновик: название и фото пришли с китайского маркетплейса, поэтому прочитайте их раньше покупателей, затем опубликуйте в Shopify.
Повторная отправка обновляет тот же товар Shopify: цены и остатки задаются заново, убранные вами варианты удаляются. Статус, название, описание и фото остаются такими, какими вы их оставили в Shopify, если вы не пришлёте новые.
Остаток — это количество у продавца, не более 100: мы покупаем по требованию, так что это число заказов, которые Shopify примет, прежде чем покажет «распродано».
Ваш магазин должен продавать в US$, поскольку цены указаны в этой валюте. Распроданные варианты пропускаются и перечисляются в skipped[].

Область доступаproducts:write

Параметры пути

idstringобязательно: ID товара.

Тело

shopstring: Какой привязанный магазин, например acme-goods.myshopify.com. Нужно, только если вы привязали несколько.
title, descriptionstring: Необязательно. Передаются в Shopify, только если вы их отправляете.

Ошибки

Статус	Тип	Когда
409	no-linked-store	К этому аккаунту не привязан ни один магазин Shopify, или их несколько, а `shop` не указан.
409	store-not-ready	Доступ магазина истёк или наша локация ещё не настроена: один раз откройте приложение NinjaBuy в Shopify.
422	store-currency	Магазин не продаёт в US$.
422	too-many-options	У карточки больше трёх опций; Shopify принимает три.
422	unprocessable	Все варианты распроданы или Shopify отклонил поле; detail передаёт его формулировку.

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"
}

Удаление товара

DELETE/v1/products/{id}

Прекращает синхронизацию и обнуляет остаток на ваших каналах; товар в Shopify остаётся, чтобы вы его архивировали. Уже оформленные заказы всё равно будут отправлены.

Область доступаproducts:write

Параметры пути

idstringобязательно: ID товара.

Ошибки

Статус	Тип	Когда
404	not-found	В этом аккаунте нет такого товара.

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 }

Объект Product

Список товаров

Параметры запроса

Получение товара

Параметры пути

Ошибки

Изменение товара

Параметры пути

Тело

Ошибки

Отправить в Shopify

Параметры пути

Тело

Ошибки

Удаление товара

Параметры пути

Ошибки