API заказов2026-11Предпросмотр

Заказы

Ваша продажа, которую мы выкупаем у продавца, проверяем и фотографируем на складе, упаковываем в вашу коробку и отправляем вашему покупателю.

Отслеживайте заказ через вебхуки, а не опросом: события заказа срабатывают на каждом этапе. Сама посылка — это заказ на выполнение, затем отправление.

Эндпоинты

POST/v1/ordersСоздание заказа
GET/v1/ordersСписок заказов
GET/v1/orders/{id}Получение заказа
POST/v1/orders/{id}/cancelОтмена заказа

Объект Order

idstring: Начинается с ord_.
external_idstring: Номер заказа вашего магазина. Уникален в вашем аккаунте.
sourcestring: api или shopify для заказов, присланных вашим магазином Shopify.
statusstring: Статус наименее продвинувшейся позиции; см. «Статусы» ниже.
payment_statusstring: awaiting_payment, paid, partially_refunded или refunded.
lanestring: saver или fast.
lines[]array: Вариант, количество, единиц на товар, статус, фото со склада после проверки и reason при отказе.
ship_toobject: Имя, адрес, телефон и почта покупателя.
packagingstring|null: Ваша брендированная коробка или пакет; при null — упаковка по умолчанию.
chargesobject: Сколько это стоит в CN¥: закупка (товары, сбор за приёмку, налог) и посылка (доставка, сбор за обработку, налог). Посылка — оценка по вашим весам, пока мы её не взвесим.
amount_duemoney|null: Что ещё должен покрыть баланс, пока статус awaiting_payment.
fulfillment_orders[]array: Посылки, в которых он уходит.

order

{
  "id": "ord_3n7q",
  "external_id": "1012",
  "source": "shopify",
  "status": "checked",
  "payment_status": "paid",
  "lane": "saver",
  "lines": [
    {
      "id": "lin_9a2c",
      "variant": "var_41hz",
      "sku": "5187209554",
      "title": "Heavyweight Washed Hoodie, Black / M",
      "quantity": 1,
      "units": 1,
      "status": "checked",
      "photos": [
        "https://media.ninjabuy.com/qc/ord_3n7q/1.webp",
        "https://media.ninjabuy.com/qc/ord_3n7q/2.webp"
      ],
      "reason": null
    }
  ],
  "ship_to": {
    "name": "Sam Rivera",
    "line1": "500 Congress Ave",
    "line2": null,
    "city": "Austin",
    "region": "TX",
    "postal_code": "78701",
    "country": "US",
    "phone": "+15125550142",
    "email": "sam@example.com"
  },
  "packaging": "pkg_acme_mailer",
  "charges": {
    "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" }
    },
    "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" },
      "estimate": true
    },
    "total": { "amount": "191.52", "currency": "CNY" }
  },
  "amount_due": null,
  "fulfillment_orders": ["fo_7k2m"],
  "created_at": "2026-11-01T09:14:02Z",
  "updated_at": "2026-11-02T03:20:11Z"
}

Отправьте нам один из заказов вашего магазина. Каждая позиция — это сохранённый вами вариант или ссылка на карточку и SKU, которые мы покупаем как есть. Заказ сразу оплачивается с баланса; заказ, который баланс не покрывает, всё равно создаётся — в статусе awaiting_payment с amount_due — и продолжается сам после пополнения.

Заказы из вашего магазина Shopify доходят до нас без этого вызова. Используйте его для WooCommerce, Wix, вашего собственного сайта или чего угодно ещё, что продаёт.

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

Тело

external_idstringобязательно: Номер вашего заказа. Второй заказ с ним отклоняется.
lines[]arrayобязательно: variant и quantity или url, sku и quantity. units (необязательно) покупает столько единиц на товар — для наборов.
ship_toobjectобязательно: name, line1, line2, city, region, postal_code, country (две буквы), phone, email.
lanestring: saver или fast. По умолчанию saver.
packagingstring: Необязательно. ID упаковки; если не указан — упаковка по умолчанию.
notestring: Необязательно. Для команды склада, до 500 символов.

Ошибки

Статус	Тип	Когда
400	bad-body	Поле отсутствует или заполнено неверно; errors[] указывает на него.
409	duplicate-order	external_id уже используется заказом; order указывает на него.
422	unprocessable	Вариант позиции распродан или её ссылку не удаётся прочитать.
422	not-shippable	Ни один опубликованный тариф не доставляет в ship_to.country по этой линии.

curl -X POST "https://www.ninjabuy.com/api/v1/orders" \
  -H "Authorization: Bearer $NINJABUY_API_KEY" \
  -H "NinjaBuy-Version: 2026-11" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
    "external_id": "1012",
    "lines": [{ "variant": "var_41hz", "quantity": 1 }],
    "ship_to": {
      "name": "Sam Rivera",
      "line1": "500 Congress Ave",
      "city": "Austin",
      "region": "TX",
      "postal_code": "78701",
      "country": "US",
      "phone": "+15125550142",
      "email": "sam@example.com"
    },
    "lane": "saver"
  }'

Response 201

HTTP/2 201 Created

{
  "id": "ord_3n7q",
  "external_id": "1012",
  "source": "api",
  "status": "buying",
  "payment_status": "paid",
  "lane": "saver",
  "lines": [
    {
      "id": "lin_9a2c",
      "variant": "var_41hz",
      "sku": "5187209554",
      "title": "Heavyweight Washed Hoodie, Black / M",
      "quantity": 1,
      "units": 1,
      "status": "buying",
      "photos": [],
      "reason": null
    }
  ],
  "ship_to": {
    "name": "Sam Rivera",
    "line1": "500 Congress Ave",
    "line2": null,
    "city": "Austin",
    "region": "TX",
    "postal_code": "78701",
    "country": "US",
    "phone": "+15125550142",
    "email": "sam@example.com"
  },
  "packaging": "pkg_acme_mailer",
  "charges": {
    "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" }
    },
    "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" },
      "estimate": true
    },
    "total": { "amount": "191.52", "currency": "CNY" }
  },
  "amount_due": null,
  "fulfillment_orders": [],
  "created_at": "2026-11-01T09:14:02Z",
  "updated_at": "2026-11-02T03:20:11Z"
}

Список заказов

GET/v1/orders

От новых к старым.

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

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

statusstring: Необязательно. Один из статусов ниже.
sourcestring: Необязательно. api или shopify.
external_idstring: Необязательно. Поиск по вашему собственному номеру заказа.
created_sincestring: Необязательно. Время.
limit, cursor: Pagination

curl "https://www.ninjabuy.com/api/v1/orders?status=checked" \
  -H "Authorization: Bearer $NINJABUY_API_KEY" \
  -H "NinjaBuy-Version: 2026-11"

Response 200

HTTP/2 200 OK

{
  "data": [
    {
      "id": "ord_3n7q",
      "external_id": "1012",
      "status": "checked",
      "payment_status": "paid"
    }
  ],
  "has_more": false,
  "cursor": null
}

Получение заказа

GET/v1/orders/{id}

Статус каждой позиции, её фото со склада после проверки, стоимость и посылки.

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

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

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

Ошибки

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

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

Response 200

HTTP/2 200 OK

{
  "id": "ord_3n7q",
  "external_id": "1012",
  "source": "shopify",
  "status": "checked",
  "payment_status": "paid",
  "lane": "saver",
  "lines": [
    {
      "id": "lin_9a2c",
      "variant": "var_41hz",
      "sku": "5187209554",
      "title": "Heavyweight Washed Hoodie, Black / M",
      "quantity": 1,
      "units": 1,
      "status": "checked",
      "photos": [
        "https://media.ninjabuy.com/qc/ord_3n7q/1.webp",
        "https://media.ninjabuy.com/qc/ord_3n7q/2.webp"
      ],
      "reason": null
    }
  ],
  "ship_to": {
    "name": "Sam Rivera",
    "line1": "500 Congress Ave",
    "line2": null,
    "city": "Austin",
    "region": "TX",
    "postal_code": "78701",
    "country": "US",
    "phone": "+15125550142",
    "email": "sam@example.com"
  },
  "packaging": "pkg_acme_mailer",
  "charges": {
    "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" }
    },
    "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" },
      "estimate": true
    },
    "total": { "amount": "191.52", "currency": "CNY" }
  },
  "amount_due": null,
  "fulfillment_orders": ["fo_7k2m"],
  "created_at": "2026-11-01T09:14:02Z",
  "updated_at": "2026-11-02T03:20:11Z"
}

Отмена заказа

POST/v1/orders/{id}/cancel

До выкупа весь заказ возвращается на баланс. После выкупа возмещаются позиции, которые продавец принял обратно, а остальное остаётся на вашей полке как складской запас. Отправленный заказ отменить нельзя.

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

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

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

Тело

reasonstring: Необязательно. Хранится в заказе.

Ошибки

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

curl -X POST "https://www.ninjabuy.com/api/v1/orders/ord_3n7q/cancel" \
  -H "Authorization: Bearer $NINJABUY_API_KEY" \
  -H "NinjaBuy-Version: 2026-11" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{ "reason": "Customer changed their mind" }'

Response 200

HTTP/2 200 OK

{
  "id": "ord_3n7q",
  "status": "cancelled",
  "payment_status": "refunded",
  "refunded": { "amount": "191.52", "currency": "CNY" }
}

Статусы

У каждой позиции свой статус; статус заказа — статус наименее продвинувшейся позиции. По порядку:

Статус	Значение
awaiting_payment	Баланса не хватило. Пополните, и заказ продолжится сам.
buying	Оплачено; мы выкупаем товар у продавца.
with_seller	Выкуплено; продавец ещё не отправил товар на наш склад.
checked	На нашем складе, проверено и сфотографировано, ждёт упаковки.
shipped	В пути, с трекингом.
delivered	Перевозчик сообщает о доставке.
rejected	Мы не смогли выкупить (распродано, ссылка недоступна); reason объясняет причину, деньги возвращаются.
cancelled	Вы его отменили.

Деньги

В примерах покупка одной единицы стоит 57,00 CN¥, а её доставка 134,52 CN¥, со списанием с баланса. Что означает каждая строка: Сборы.

Объект Order

Создание заказа

Тело

Ошибки

Список заказов

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

Получение заказа

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

Ошибки

Отмена заказа

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

Тело

Ошибки

Статусы

Деньги