API для фулфилмента: заявки клиента
Обновлено: 2026-10-12
Capability requests с версии 1.2. С версии 1.3 в строке заявки приходит карточка товара. Селлер планирует приёмку или отгрузку на основной склад фулфилмента, Нитроселлер отправляет её в WMS. Менеджер сверяет товары и принимает заявку — тогда появляется настоящий документ.
POST /requests
{
"ns_request_id": "01JXXXXXXXXXXXXXXXXXXXXXXX",
"kind": "reception",
"wms_type": "receiving",
"document_ref": "IN-18",
"planned_at": "2026-10-12T00:00:00+03:00",
"comment": null,
"destination_title": null,
"lines": [
{
"variant_id": "01JYYYYYYYYYYYYYYYYYYYYYYY",
"qty": 10,
"article": "ABC-1",
"title": "Футболка M",
"brand": "Нитро",
"barcodes": [{ "code": "4600000000001", "marketplace": "wb" }],
"width": 200,
"height": 30,
"length": 280,
"weight": 180,
"photos": ["https://nitroseller.ru/api/fulfillment/v1/files/01J...?expires=1&signature=abc"],
"is_kiz": false,
"wms_product_id": "77"
}
]
}
Ответ: {id, status}. id — id заявки в WMS. Повтор с тем же ns_request_id обновляет заявку, если она ещё new или была rejected: статус снова становится new, причина отказа сбрасывается.
| Поле | Смысл |
|---|---|
kind |
reception или shipment |
wms_type |
Для приёмки только receiving. Для отгрузки return (вывоз клиентом) или shipment (на маркетплейс) |
document_ref |
Номер документа у селлера, чтобы менеджер узнал, о чём речь |
destination_title |
Куда везут отгрузку. У приёмки обычно null |
lines[].variant_id |
ULID варианта в Нитроселлере |
lines[].barcodes |
Все штрихкоды варианта: code и marketplace (wb или ozon) |
lines[].width, height, length |
Габариты в миллиметрах |
lines[].weight |
Вес в граммах |
lines[].is_kiz |
Товар с кодом маркировки |
lines[].wms_product_id |
Id товара в WMS, если он уже сопоставлен, иначе null |
Изменение, отмена и список
PUT /requests/{id} — то же тело, что у создания. id из ответа POST, а ns_request_id должен совпасть. DELETE /requests/{id} ставит статус cancelled. GET /requests?changed_since= отвечает {data, next_cursor}. Строка: id, ns_request_id, status, reject_reason, updated_at.
Статусы: new, accepted, rejected, cancelled. При отказе заполните reject_reason понятной фразой: селлер увидит её и сможет исправить документ.
| Ответ | Когда |
|---|---|
422 invalid_request |
Пустые строки, неверный тип или нет номера заявки |
409 request_locked |
Заявку уже приняли, менять и отменять нельзя |
404 request_locked |
Заявки с таким id нет |
Карточки товаров
Карточка приходит в строке вместе с количеством. Описания в заявке нет. Пока заявка new или rejected, сохранение документа у селлера отправляет строку заново — вместе с актуальной карточкой.
Фото из файлов Нитроселлера — временные ссылки на сутки. Сохраните файлы, когда принимаете заявку: потом по этим ссылкам не ходят. Суток хватает, если отправка повторится. Ссылку открывают обычным GET без ключа. Расширения в адресе нет: тип файла смотрите по заголовку Content-Type. После импорта сохраните variant_id у своего товара и отдавайте его в /items как nitroseller_variant_id. Принятый документ отдайте в /documents с request_ref, равным ns_request_id.
Протокол 1.2 по-прежнему отвечает на POST /api/fulfillment/v1/products с телом {variant_ids} — до 100 ULID. Ответ {products, denied}. В той карточке есть description, фото подписаны на 6 часов. Товар попадает в products, только если он из пространства этого ключа и уже был в заявке этому фулфилменту или уже сопоставлен. В 1.3 этот вызов не нужен.