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

Импорт

Вставьте ссылку на карточку и получите её варианты и стоимость продажи каждого: товары, наш сбор за приёмку 12,00 CN¥ за посылку продавца до нас, фиксированный налог 14%, затем линия доставки, сбор за обработку 50,00 CN¥ за посылку и налог на них, комиссию маркетплейса и цену, сохраняющую вашу маржу.

Импорт бесплатный и без лимита товаров. Вы платите только за то, что заказываете.
Каждая цифра — это одна единица, купленная в отдельном заказе и отправленная в отдельной посылке: одна продажа по дропшиппингу. Несколько единиц в одном заказе или посылке стоят меньше.
Комиссии маркетплейса по умолчанию — публичная базовая ставка каждого маркетплейса. Укажите свою, если у вашей категории или тарифа она другая.

Эндпоинты

POST/v1/importsИмпорт по ссылке
POST/v1/imports/{id}/analysisПересчитать цену
GET/v1/imports/{id}Получение импорта
GET/v1/importsСписок импортов
POST/v1/imports/{id}/saveСохранение как товар

Объект Import

Карточка товара в нашем прочтении и стоимость одной продажи с доставкой до двери покупателя: товары, наш сбор за приёмку 12,00 CN¥ за посылку продавца до нас, фиксированный налог 14%, затем линия доставки, сбор за обработку 50,00 CN¥ за посылку и налог на них. В US$ — это сумма, которую спишут с карты в US$, с учётом конвертации валюты.

idstring: Начинается с imp_.
statusstring: running (таблица находок ещё читается), ready или failed.
urlstring: Отправленная вами ссылка.
marketplacestring: taobao, tmall, weidian или 1688.
title, seller, images[]string: Как их написал продавец, чаще всего по-китайски.
read_atstring: Когда мы последний раз читали карточку с маркетплейса.
analysis.ship_to, lane, weight_g: Входные данные, для которых рассчитана цена.
analysis.coveredboolean: False, если ни один опубликованный тариф не доставляет в эту страну по этой линии; тогда ни у одного варианта нет полной себестоимости.
analysis.marketplace_feeobject: percent и fixed: что маркетплейс оставляет себе с продажи. default равно true, если вы ничего не отправили и мы использовали его публичную базовую ставку, — это оценка, а не ваш реальный счёт.
analysis.margin_reachableboolean: False, если комиссия и маржа вместе забирают всю цену: никакая цена не может этого достичь.
analysis.brand_hintobject|null: Брендовые слова или слова о репликах в названии, на английском или китайском. Подсказка, а не вердикт: логотип на фото она не видит, а чистый результат ничего не доказывает.
analysis.variants[].procurementobject: goods, intake_fee, tax и total заказа на покупку одной единицы.
analysis.variants[].seller_shippingobject|null: Доставка продавца до нашего склада. Ни в одной карточке её нет, поэтому значение null: неизвестно, а не бесплатно.
analysis.variants[].parcelobject|null: lane, shipping, handling_fee, tax и total посылки, в которой он отправляется.
analysis.variants[].landedobject: Товар и посылка вместе: в CN¥, в US$ и с комиссией за конвертацию в сумме в US$.
analysis.variants[].minimum_priceobject|null: Минимальная цена, сохраняющая вашу маржу после комиссии маркетплейса.
analysis.variants[].suggestedobject|null: Минимальная цена вида x.99 не ниже минимума, с комиссией, прибылью и маржой, которые она даёт.
productstring|null: Товар, которым он стал после сохранения.

import

{
  "id": "imp_2c9d",
  "status": "ready",
  "url": "https://weidian.com/item.html?itemID=7750970856",
  "marketplace": "weidian",
  "title": "Heavyweight washed hoodie",
  "seller": "Ruoyi Studio",
  "images": [
    "https://media.ninjabuy.com/listings/weidian-7750970856/1.webp"
  ],
  "read_at": "2026-11-04T09:12:40Z",
  "analysis": {
    "ship_to": "US",
    "lane": "saver",
    "weight_g": 180,
    "covered": true,
    "marketplace": "ebay",
    "marketplace_fee": {
      "percent": "13.6",
      "fixed": { "amount": "0.40", "currency": "USD" },
      "default": true
    },
    "margin_percent": "30",
    "margin_reachable": true,
    "brand_hint": null,
    "variants": [
      {
        "sku": "5187209554",
        "label": "Black / M",
        "in_stock": true,
        "procurement": {
          "goods": { "amount": "38.00", "currency": "CNY" },
          "intake_fee": { "amount": "12.00", "currency": "CNY" },
          "tax": { "amount": "7.00", "currency": "CNY" },
          "total": { "amount": "57.00", "currency": "CNY" }
        },
        "seller_shipping": null,
        "parcel": {
          "lane": "saver",
          "shipping": { "amount": "68.00", "currency": "CNY" },
          "handling_fee": { "amount": "50.00", "currency": "CNY" },
          "tax": { "amount": "16.52", "currency": "CNY" },
          "total": { "amount": "134.52", "currency": "CNY" }
        },
        "landed": {
          "cny": { "amount": "191.52", "currency": "CNY" },
          "usd": { "amount": "27.71", "currency": "USD" },
          "fx_fee": { "amount": "5.75", "currency": "CNY" }
        },
        "minimum_price": { "amount": "49.84", "currency": "USD" },
        "suggested": {
          "price": { "amount": "49.99", "currency": "USD" },
          "marketplace_fee": { "amount": "7.20", "currency": "USD" },
          "profit": { "amount": "15.08", "currency": "USD" },
          "margin_percent": "30.16"
        }
      },
      {
        "sku": "5187209555",
        "label": "Black / L",
        "in_stock": false,
        "procurement": {
          "goods": { "amount": "38.00", "currency": "CNY" },
          "intake_fee": { "amount": "12.00", "currency": "CNY" },
          "tax": { "amount": "7.00", "currency": "CNY" },
          "total": { "amount": "57.00", "currency": "CNY" }
        },
        "seller_shipping": null,
        "parcel": {
          "lane": "saver",
          "shipping": { "amount": "68.00", "currency": "CNY" },
          "handling_fee": { "amount": "50.00", "currency": "CNY" },
          "tax": { "amount": "16.52", "currency": "CNY" },
          "total": { "amount": "134.52", "currency": "CNY" }
        },
        "landed": {
          "cny": { "amount": "191.52", "currency": "CNY" },
          "usd": { "amount": "27.71", "currency": "USD" },
          "fx_fee": { "amount": "5.75", "currency": "CNY" }
        },
        "minimum_price": { "amount": "49.84", "currency": "USD" },
        "suggested": {
          "price": { "amount": "49.99", "currency": "USD" },
          "marketplace_fee": { "amount": "7.20", "currency": "USD" },
          "profit": { "amount": "15.08", "currency": "USD" },
          "margin_percent": "30.16"
        }
      }
    ]
  },
  "product": null,
  "created_at": "2026-11-04T09:12:41Z"
}

Импорт по ссылке

POST/v1/imports

Читает карточку Taobao, Tmall, Weidian или 1688 (подойдёт и короткая ссылка или ссылка на неё другого агента по покупкам) и в том же вызове возвращает её с анализом. Карточку, прочитанную за последние пять минут, повторно не загружаем.

Ссылка на таблицу находок (https://www.ninjabuy.com/spreadsheets/d/…) импортирует все товары из неё: 202 со status: running, затем опрашивайте импорт.

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

Тело

urlstringобязательно: Ссылка на товар или таблица находок.
ship_tostring: Двухбуквенный код страны для расчёта посылки. По умолчанию US.
lanestring: saver или fast. По умолчанию saver.
weight_gintegerобязательно: Вес одной единицы в упаковке, в граммах. В карточках нет веса, поэтому посылка рассчитывается по вашему.
marketplacestring: Где вы его продаёте: ebay, shopify, amazon или tiktok. По умолчанию shopify.
marketplace_feeobject: Необязательно. percent и fixed (US$) вместо базовой ставки маркетплейса, для вашей категории или тарифа.
margin_percentstring: Целевая маржа от цены продажи. По умолчанию 30.

Ошибки

Статус	Тип	Когда
400	bad-body	weight_g отсутствует, или поле вне допустимого диапазона.
422	unprocessable	Ссылку не удаётся прочитать, или карточки больше нет.
429	rate-limited	Лимит запросов к маркетплейсу исчерпан; см. «Лимиты запросов».

curl -X POST "https://www.ninjabuy.com/api/v1/imports" \
  -H "Authorization: Bearer $NINJABUY_API_KEY" \
  -H "NinjaBuy-Version: 2026-11" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://weidian.com/item.html?itemID=7750970856",
    "ship_to": "US",
    "weight_g": 180,
    "marketplace": "ebay",
    "margin_percent": "30"
  }'

Response 201

HTTP/2 201 Created

{
  "id": "imp_2c9d",
  "status": "ready",
  "url": "https://weidian.com/item.html?itemID=7750970856",
  "marketplace": "weidian",
  "title": "Heavyweight washed hoodie",
  "seller": "Ruoyi Studio",
  "images": [
    "https://media.ninjabuy.com/listings/weidian-7750970856/1.webp"
  ],
  "read_at": "2026-11-04T09:12:40Z",
  "analysis": {
    "ship_to": "US",
    "lane": "saver",
    "weight_g": 180,
    "covered": true,
    "marketplace": "ebay",
    "marketplace_fee": {
      "percent": "13.6",
      "fixed": { "amount": "0.40", "currency": "USD" },
      "default": true
    },
    "margin_percent": "30",
    "margin_reachable": true,
    "brand_hint": null,
    "variants": [
      {
        "sku": "5187209554",
        "label": "Black / M",
        "in_stock": true,
        "procurement": {
          "goods": { "amount": "38.00", "currency": "CNY" },
          "intake_fee": { "amount": "12.00", "currency": "CNY" },
          "tax": { "amount": "7.00", "currency": "CNY" },
          "total": { "amount": "57.00", "currency": "CNY" }
        },
        "seller_shipping": null,
        "parcel": {
          "lane": "saver",
          "shipping": { "amount": "68.00", "currency": "CNY" },
          "handling_fee": { "amount": "50.00", "currency": "CNY" },
          "tax": { "amount": "16.52", "currency": "CNY" },
          "total": { "amount": "134.52", "currency": "CNY" }
        },
        "landed": {
          "cny": { "amount": "191.52", "currency": "CNY" },
          "usd": { "amount": "27.71", "currency": "USD" },
          "fx_fee": { "amount": "5.75", "currency": "CNY" }
        },
        "minimum_price": { "amount": "49.84", "currency": "USD" },
        "suggested": {
          "price": { "amount": "49.99", "currency": "USD" },
          "marketplace_fee": { "amount": "7.20", "currency": "USD" },
          "profit": { "amount": "15.08", "currency": "USD" },
          "margin_percent": "30.16"
        }
      },
      {
        "sku": "5187209555",
        "label": "Black / L",
        "in_stock": false,
        "procurement": {
          "goods": { "amount": "38.00", "currency": "CNY" },
          "intake_fee": { "amount": "12.00", "currency": "CNY" },
          "tax": { "amount": "7.00", "currency": "CNY" },
          "total": { "amount": "57.00", "currency": "CNY" }
        },
        "seller_shipping": null,
        "parcel": {
          "lane": "saver",
          "shipping": { "amount": "68.00", "currency": "CNY" },
          "handling_fee": { "amount": "50.00", "currency": "CNY" },
          "tax": { "amount": "16.52", "currency": "CNY" },
          "total": { "amount": "134.52", "currency": "CNY" }
        },
        "landed": {
          "cny": { "amount": "191.52", "currency": "CNY" },
          "usd": { "amount": "27.71", "currency": "USD" },
          "fx_fee": { "amount": "5.75", "currency": "CNY" }
        },
        "minimum_price": { "amount": "49.84", "currency": "USD" },
        "suggested": {
          "price": { "amount": "49.99", "currency": "USD" },
          "marketplace_fee": { "amount": "7.20", "currency": "USD" },
          "profit": { "amount": "15.08", "currency": "USD" },
          "margin_percent": "30.16"
        }
      }
    ]
  },
  "product": null,
  "created_at": "2026-11-04T09:12:41Z"
}

Пересчитать цену

POST/v1/imports/{id}/analysis

Та же карточка для другой страны, линии, веса, маркетплейса или маржи. Рассчитывается по уже прочитанным данным, поэтому не расходует запрос к маркетплейсу. Возвращает новый анализ и сохраняет его в импорте.

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

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

idstringобязательно: ID импорта.

Тело

ship_tostring: Двухбуквенный код страны для расчёта посылки. По умолчанию US.
lanestring: saver или fast. По умолчанию saver.
weight_gintegerобязательно: Вес одной единицы в упаковке, в граммах. В карточках нет веса, поэтому посылка рассчитывается по вашему.
marketplacestring: Где вы его продаёте: ebay, shopify, amazon или tiktok. По умолчанию shopify.
marketplace_feeobject: Необязательно. percent и fixed (US$) вместо базовой ставки маркетплейса, для вашей категории или тарифа.
margin_percentstring: Целевая маржа от цены продажи. По умолчанию 30.

Ошибки

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

curl -X POST "https://www.ninjabuy.com/api/v1/imports/imp_2c9d/analysis" \
  -H "Authorization: Bearer $NINJABUY_API_KEY" \
  -H "NinjaBuy-Version: 2026-11" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
    "ship_to": "GB",
    "lane": "fast",
    "weight_g": 180,
    "marketplace": "tiktok",
    "margin_percent": "35"
  }'

Response 200

HTTP/2 200 OK

{
  "ship_to": "GB",
  "lane": "fast",
  "weight_g": 180,
  "covered": true,
  "marketplace": "tiktok",
  "marketplace_fee": {
    "percent": "6",
    "fixed": { "amount": "0.00", "currency": "USD" },
    "default": true
  },
  "margin_percent": "35",
  "margin_reachable": true,
  "brand_hint": null,
  "variants": [
    {
      "sku": "5187209554",
      "label": "Black / M",
      "in_stock": true,
      "procurement": {
        "goods": { "amount": "38.00", "currency": "CNY" },
        "intake_fee": { "amount": "12.00", "currency": "CNY" },
        "tax": { "amount": "7.00", "currency": "CNY" },
        "total": { "amount": "57.00", "currency": "CNY" }
      },
      "seller_shipping": null,
      "parcel": {
        "lane": "saver",
        "shipping": { "amount": "68.00", "currency": "CNY" },
        "handling_fee": { "amount": "50.00", "currency": "CNY" },
        "tax": { "amount": "16.52", "currency": "CNY" },
        "total": { "amount": "134.52", "currency": "CNY" }
      },
      "landed": {
        "cny": { "amount": "191.52", "currency": "CNY" },
        "usd": { "amount": "27.71", "currency": "USD" },
        "fx_fee": { "amount": "5.75", "currency": "CNY" }
      },
      "minimum_price": { "amount": "49.84", "currency": "USD" },
      "suggested": {
        "price": { "amount": "49.99", "currency": "USD" },
        "marketplace_fee": { "amount": "7.20", "currency": "USD" },
        "profit": { "amount": "15.08", "currency": "USD" },
        "margin_percent": "30.16"
      }
    },
    {
      "sku": "5187209555",
      "label": "Black / L",
      "in_stock": false,
      "procurement": {
        "goods": { "amount": "38.00", "currency": "CNY" },
        "intake_fee": { "amount": "12.00", "currency": "CNY" },
        "tax": { "amount": "7.00", "currency": "CNY" },
        "total": { "amount": "57.00", "currency": "CNY" }
      },
      "seller_shipping": null,
      "parcel": {
        "lane": "saver",
        "shipping": { "amount": "68.00", "currency": "CNY" },
        "handling_fee": { "amount": "50.00", "currency": "CNY" },
        "tax": { "amount": "16.52", "currency": "CNY" },
        "total": { "amount": "134.52", "currency": "CNY" }
      },
      "landed": {
        "cny": { "amount": "191.52", "currency": "CNY" },
        "usd": { "amount": "27.71", "currency": "USD" },
        "fx_fee": { "amount": "5.75", "currency": "CNY" }
      },
      "minimum_price": { "amount": "49.84", "currency": "USD" },
      "suggested": {
        "price": { "amount": "49.99", "currency": "USD" },
        "marketplace_fee": { "amount": "7.20", "currency": "USD" },
        "profit": { "amount": "15.08", "currency": "USD" },
        "margin_percent": "30.16"
      }
    }
  ]
}

Получение импорта

GET/v1/imports/{id}

Перечитайте импорт или опрашивайте таблицу находок, пока она обрабатывается.

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

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

idstringобязательно: ID импорта.

Ошибки

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

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

Response 200

HTTP/2 200 OK

{
  "id": "imp_6t1b",
  "status": "running",
  "url": "https://www.ninjabuy.com/spreadsheets/d/1aBcD3fGh",
  "progress": { "done": 41, "total": 120 },
  "poll_after_seconds": 10
}

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

GET/v1/imports

От новых к старым. Несохранённые импорты остаются здесь, чтобы вы могли к ним вернуться.

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

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

statusstring: Необязательно. running, ready или failed.
savedboolean: Необязательно. true — для тех, что стали товарами.
limit, cursor: Pagination

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

Response 200

HTTP/2 200 OK

{
  "data": [
    {
      "id": "imp_2c9d",
      "status": "ready",
      "title": "Heavyweight washed hoodie",
      "product": null
    },
    {
      "id": "imp_2c7a",
      "status": "ready",
      "title": "Canvas tote, 3 colours",
      "product": null
    }
  ],
  "has_more": true,
  "cursor": "c_2c7a"
}

Сохранение как товар

POST/v1/imports/{id}/save

Сохраняет выбранные варианты как товар по заданным вами или рекомендуемым ценам. Добавьте push_to: shopify, чтобы выставить его в магазин тем же вызовом (Отправить в Shopify).

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

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

idstringобязательно: ID импорта.

Тело

variants[]array: Необязательно. sku и price каждого сохраняемого варианта. Если не указано — все варианты в наличии по рекомендуемой цене.
titlestring: Необязательно. Ваше собственное название; у продавца оно чаще всего на китайском.
push_tostring: Необязательно. shopify.

Ошибки

Статус	Тип	Когда
409	invalid-state	Уже сохранено; product указывает на него.
422	unprocessable	Все оставленные вами варианты распроданы.

curl -X POST "https://www.ninjabuy.com/api/v1/imports/imp_2c9d/save" \
  -H "Authorization: Bearer $NINJABUY_API_KEY" \
  -H "NinjaBuy-Version: 2026-11" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Heavyweight Washed Hoodie",
    "variants": [
      {
        "sku": "5187209554",
        "price": { "amount": "49.99", "currency": "USD" }
      }
    ],
    "push_to": "shopify"
  }'

Response 201

HTTP/2 201 Created

{
  "import": "imp_2c9d",
  "product": "prd_8f2k",
  "status": "draft",
  "channels": [{ "channel": "shopify", "status": "draft" }]
}