Справочник API / Заказы и события

Заказы и события

Заказ создаёт витрина, а живёт он у вас: вы переводите статусы, мы пересчитываем резервы и сообщаем витринам. Обо всём, что произошло, приходят события.

Объект заказа

idстрокаНомер заказа, тот же, что видит покупатель.
statusстрокаОдин из статусов: new, confirmed, assembling, assembled, shipped, delivered, canceled, returned.
totalцелоеСумма в копейках с учётом скидок.
itemsмассивПозиции: sku, количество и цена на момент заказа.
deliveryобъектСпособ доставки и город. Адреса и телефоны покупателя в API не отдаются.
created_atстрокаВремя создания, UTC.

Объект

{
  "id": "ORD-25161",
  "status": "confirmed",
  "total": 477000,
  "currency": "RUB",
  "items": [
    { "sku": "TRM-1579", "qty": 2, "price": 129000 },
    { "sku": "TRM-2210", "qty": 1, "price": 219000 }
  ],
  "delivery": { "method": "courier", "city": "Рязань" },
  "created_at": "2026-08-22T08:15:00Z",
  "updated_at": "2026-08-22T08:16:41Z"
}

Получить заказ

Заказ целиком: позиции, оплата, доставка и история статусов.

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

idстрокаобязательныйНомер заказа.

GET/v1/orders/{id}

curl

curl "$API/v1/orders/ORD-25161" \
  -H "Authorization: Bearer $NIMBUS_KEY"

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

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

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

statusстрокаТолько заказы в этом статусе.
created_fromстрокаНачало периода, ISO 8601.
created_toстрокаКонец периода.
limitцелоеОт 1 до 200, по умолчанию 50.
cursorстрокаКурсор из предыдущего ответа.

GET/v1/orders

curl

curl "$API/v1/orders?status=confirmed&created_from=2026-08-18" \
  -H "Authorization: Bearer $NIMBUS_KEY"

Перевести статус

Переход разрешён только по таблице из руководства Заказы. Заголовок Idempotency-Key обязателен.

Параметры

statusстрокаобязательныйНовый статус.
commentстрокаКомментарий для журнала заказа, до 500 символов.
track_numberстрокаТрек-номер перевозчика. Обязателен для shipped.

Возвращает

Объект заказа с новым статусом или 409 с кодом state_transition и текущим статусом.

POST/v1/orders/{id}/status

curlNode.jsPython

curl "$API/v1/orders/ORD-25161/status" \
  -H "Authorization: Bearer $NIMBUS_KEY" \
  -H "Idempotency-Key: assemble-ORD-25161" \
  -d '{ "status": "assembled" }'

await api.orders.setStatus('ORD-25161', {
  status: 'assembled',
  idempotencyKey: 'assemble-ORD-25161',
});

api.orders.set_status(
    "ORD-25161",
    status="assembled",
    idempotency_key="assemble-ORD-25161",
)

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

Целиком или по позициям. Когда отменены все позиции, заказ сам переходит в canceled, а резервы возвращаются в доступный остаток.

Параметры

itemsмассивПозиции к отмене: sku и qty. Без него отменяется весь заказ.
reasonстрокаПричина: out_of_stock, customer, other.

POST/v1/orders/{id}/cancel

Запрос

{
  "items": [ { "sku": "TRM-2210", "qty": 1 } ],
  "reason": "out_of_stock"
}

События

Каждое событие приходит вебхуком с подписью и хранится в журнале доставок 30 дней. Порядок доставки не гарантирован: сверяйте время в X-Event-Time.

Тип	Объект в теле
`order.created`	заказ
`order.paid`	заказ
`order.assembled`	заказ
`order.shipped`	заказ с трек-номером
`order.canceled`	заказ и отменённые позиции
`stock.low`	товар и порог
`price.rejected`	товар и причина

Событие stock.low

{
  "id": "9a20e7c1-3d4b-4c55-8e61-50f2a9d3b7e2",
  "type": "stock.low",
  "product": { "sku": "TRM-1583", "available": 2 },
  "threshold": 3
}

Подписки на вебхуки

Подписка - это адрес приёмника и список событий. Секрет подписи выдаётся при создании один раз.

Метод	Что делает
`GET /v1/hooks`	Подписки контура и их состояние
`POST /v1/hooks`	Создать подписку
`GET /v1/hooks/deliveries`	Журнал доставок за 30 дней
`POST /v1/hooks/deliveries/{id}/retry`	Повторить доставку

POST/v1/hooks

Запрос

{
  "url": "/hooks/nimbus",
  "events": ["order.paid", "order.canceled", "stock.low"]
}