Логотип NinjabuyBusiness
Связаться с отделом продаж
API заказов2026-11Предпросмотр

Заказы на выполнение

Позиции заказа, которые мы упаковываем в одну посылку, с коробкой и нашей проверкой каждого товара.
  • У большинства заказов он один. У заказа, товары которого приходят с большим разрывом или который вы разделили, их больше.
  • Заказ Shopify приходит как собственный запрос Shopify на выполнение. Мы принимаем его, когда каждая позиция сопоставлена с SKU (Варианты), и отклоняем с указанием несопоставленных позиций, чтобы Shopify оставил его у вас.
  • Товар, не прошедший проверку, вызывает qc.issue и ждёт вашего решения перед отправкой.
Эндпоинты

Объект Fulfillment order

idstring
Начинается с fo_.
orderstring
Заказ, к которому он относится.
statusstring
open (ждёт товары), in_progress (упаковывается), on_hold, closed (отправлен) или cancelled.
requestobject|null
Для заказа Shopify: заказ на выполнение от Shopify и наш ответ на него — принят или отклонён с вариантами магазина, не сопоставленными с SKU.
holdobject|null
reason и note, пока на удержании.
packagingstring|null
Коробка или пакет, в который он упаковывается.
lines[].qcobject
Наша проверка: pending, passed или issue, с фото и временем.
shipmentstring|null
Задаётся после отправки.
fulfillment_order
{
  "id": "fo_7k2m",
  "order": "ord_3n7q",
  "status": "in_progress",
  "request": {
    "channel": "shopify",
    "external_id": "gid://shopify/FulfillmentOrder/6650012",
    "status": "accepted",
    "unmapped": []
  },
  "hold": null,
  "packaging": "pkg_acme_mailer",
  "lines": [
    {
      "line": "lin_9a2c",
      "sku": "5187209554",
      "quantity": 1,
      "qc": {
        "status": "passed",
        "photos": [
          "https://media.ninjabuy.com/qc/ord_3n7q/1.webp",
          "https://media.ninjabuy.com/qc/ord_3n7q/2.webp"
        ],
        "checked_at": "2026-11-02T03:20:11Z"
      }
    }
  ],
  "shipment": null,
  "created_at": "2026-11-01T09:14:03Z"
}

Список заказов на выполнение

GET/v1/fulfillment_orders

От новых к старым. Фильтр по заказу или статусу.

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

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

orderstring
Необязательно. ID заказа.
statusstring
Необязательно.
limit, cursor
Pagination
curl "https://www.ninjabuy.com/api/v1/fulfillment_orders?status=on_hold" \
  -H "Authorization: Bearer $NINJABUY_API_KEY" \
  -H "NinjaBuy-Version: 2026-11"
Response 200
HTTP/2 200 OK

{
  "data": [
    {
      "id": "fo_7k1x",
      "order": "ord_3n6z",
      "status": "on_hold",
      "hold": { "reason": "combine" }
    }
  ],
  "has_more": false,
  "cursor": null
}

Получение заказа на выполнение

GET/v1/fulfillment_orders/{id}

Его позиции, наша проверка каждой, упаковка и отправление.

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

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

idstringобязательно
ID заказа на выполнение.

Ошибки

СтатусТипКогда
404not-foundВ этом аккаунте нет такого заказа на выполнение.
curl "https://www.ninjabuy.com/api/v1/fulfillment_orders/fo_7k2m" \
  -H "Authorization: Bearer $NINJABUY_API_KEY" \
  -H "NinjaBuy-Version: 2026-11"
Response 200
HTTP/2 200 OK

{
  "id": "fo_7k2m",
  "order": "ord_3n7q",
  "status": "in_progress",
  "request": {
    "channel": "shopify",
    "external_id": "gid://shopify/FulfillmentOrder/6650012",
    "status": "accepted",
    "unmapped": []
  },
  "hold": null,
  "packaging": "pkg_acme_mailer",
  "lines": [
    {
      "line": "lin_9a2c",
      "sku": "5187209554",
      "quantity": 1,
      "qc": {
        "status": "passed",
        "photos": [
          "https://media.ninjabuy.com/qc/ord_3n7q/1.webp",
          "https://media.ninjabuy.com/qc/ord_3n7q/2.webp"
        ],
        "checked_at": "2026-11-02T03:20:11Z"
      }
    }
  ],
  "shipment": null,
  "created_at": "2026-11-01T09:14:03Z"
}

Удержание

POST/v1/fulfillment_orders/{id}/hold

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

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

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

idstringобязательно
ID заказа на выполнение.

Тело

reasonstringобязательно
combine, wait_for_stock или other.
notestring
Необязательно. Заметка для вас, сохраняется вместе с удержанием.

Ошибки

СтатусТипКогда
404not-foundВ этом аккаунте нет такого заказа на выполнение.
409invalid-stateЗакрыт или отменён.
curl -X POST "https://www.ninjabuy.com/api/v1/fulfillment_orders/fo_7k2m/hold" \
  -H "Authorization: Bearer $NINJABUY_API_KEY" \
  -H "NinjaBuy-Version: 2026-11" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{ "reason": "combine" }'
Response 200
HTTP/2 200 OK

{
  "id": "fo_7k2m",
  "order": "ord_3n7q",
  "status": "on_hold",
  "request": {
    "channel": "shopify",
    "external_id": "gid://shopify/FulfillmentOrder/6650012",
    "status": "accepted",
    "unmapped": []
  },
  "hold": {
    "reason": "combine",
    "note": null,
    "since": "2026-11-02T04:00:00Z"
  },
  "packaging": "pkg_acme_mailer",
  "lines": [
    {
      "line": "lin_9a2c",
      "sku": "5187209554",
      "quantity": 1,
      "qc": {
        "status": "passed",
        "photos": [
          "https://media.ninjabuy.com/qc/ord_3n7q/1.webp",
          "https://media.ninjabuy.com/qc/ord_3n7q/2.webp"
        ],
        "checked_at": "2026-11-02T03:20:11Z"
      }
    }
  ],
  "shipment": null,
  "created_at": "2026-11-01T09:14:03Z"
}

Снять резерв

POST/v1/fulfillment_orders/{id}/release

Позволяет удерживаемому заказу на выполнение продолжиться.

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

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

idstringобязательно
ID заказа на выполнение.

Ошибки

СтатусТипКогда
404not-foundВ этом аккаунте нет такого заказа на выполнение.
409invalid-stateНе на удержании.
curl -X POST "https://www.ninjabuy.com/api/v1/fulfillment_orders/fo_7k2m/release" \
  -H "Authorization: Bearer $NINJABUY_API_KEY" \
  -H "NinjaBuy-Version: 2026-11" \
  -H "Idempotency-Key: $(uuidgen)"
Response 200
HTTP/2 200 OK

{
  "id": "fo_7k2m",
  "order": "ord_3n7q",
  "status": "in_progress",
  "request": {
    "channel": "shopify",
    "external_id": "gid://shopify/FulfillmentOrder/6650012",
    "status": "accepted",
    "unmapped": []
  },
  "hold": null,
  "packaging": "pkg_acme_mailer",
  "lines": [
    {
      "line": "lin_9a2c",
      "sku": "5187209554",
      "quantity": 1,
      "qc": {
        "status": "passed",
        "photos": [
          "https://media.ninjabuy.com/qc/ord_3n7q/1.webp",
          "https://media.ninjabuy.com/qc/ord_3n7q/2.webp"
        ],
        "checked_at": "2026-11-02T03:20:11Z"
      }
    }
  ],
  "shipment": null,
  "created_at": "2026-11-01T09:14:03Z"
}

Отмена

POST/v1/fulfillment_orders/{id}/cancel

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

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

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

idstringобязательно
ID заказа на выполнение.

Ошибки

СтатусТипКогда
404not-foundВ этом аккаунте нет такого заказа на выполнение.
409invalid-stateУпакован или отправлен.
curl -X POST "https://www.ninjabuy.com/api/v1/fulfillment_orders/fo_7k2m/cancel" \
  -H "Authorization: Bearer $NINJABUY_API_KEY" \
  -H "NinjaBuy-Version: 2026-11" \
  -H "Idempotency-Key: $(uuidgen)"
Response 200
HTTP/2 200 OK

{
  "id": "fo_7k2m",
  "order": "ord_3n7q",
  "status": "cancelled",
  "request": {
    "channel": "shopify",
    "external_id": "gid://shopify/FulfillmentOrder/6650012",
    "status": "accepted",
    "unmapped": []
  },
  "hold": null,
  "packaging": "pkg_acme_mailer",
  "lines": [
    {
      "line": "lin_9a2c",
      "sku": "5187209554",
      "quantity": 1,
      "qc": {
        "status": "passed",
        "photos": [
          "https://media.ninjabuy.com/qc/ord_3n7q/1.webp",
          "https://media.ninjabuy.com/qc/ord_3n7q/2.webp"
        ],
        "checked_at": "2026-11-02T03:20:11Z"
      }
    }
  ],
  "shipment": null,
  "created_at": "2026-11-01T09:14:03Z"
}