Подключение по схеме FBO

Пошаговое руководство - создание локаций, полигонов, работа с заказами.

FBO (Fulfillment by Operator) – схема, при которой продавец размещает свои товары на складах маркетплейса, а маркетплейс полностью берёт на себя обработку заказов: комплектацию, упаковку, маркировку и доставку конечным покупателям.

Введение

Участники

Мерчант	Продавец — инициирует API-вызовы из своей системы или ЛК.
API	FBO Seller API — REST-интерфейс (POST JSON).
Витрина	Бэкенд маркетплейса — обрабатывает запросы API, хранит отгрузки, слоты, документы.

Константы примеров

Склад	`market_location_id: "koledino"` (Коледино)
Дата	`2026-06-12`
Товары	`FRIDGE-001` × 1, `PHONE-001` × 3
Отгрузка	`shipment_id: SHP-2026-042`

Сценарий 1: Полный happy path

Мерчант создаёт поставку на Коледино 12 июня: холодильник + 3 телефона, маркирует товары и грузоместа, заполняет пропуск, подтверждает отгрузку и получает документы.

Диаграмма последовательности

Пошаговое описание (1–12)

Склады. POST /v1/market/location/list — мерчант получает список активных складов, выбирает Коледино (koledino).
Создание черновика. POST /v1/shipment/create — 1 холодильник, дата 2026-06-12, статус DRAFT. Ответ: shipment_id: SHP-2026-042.
Таймслоты. POST /v1/shipment/timeslot-list — доступные интервалы сдачи на дату отгрузки.
Выбор слота. POST /v1/shipment/update с полем timeslot — сохранение интервала в черновике (например, 10:00–11:00).
Добавление телефонов. POST /v1/shipment/update с полем items — полная замена состава: холодильник (1) + телефоны (3).
Этикетки товаров. POST /v1/label/items/get — PDF стикеры для холодильника и телефонов. На складе: распечатать и наклеить на каждую единицу до упаковки.
Грузоместа. POST /v1/shipment/package/update — короб №1 (3 телефона, BOX), паллета №2 (холодильник, PALLET). Ответ: package_id (PKG-001, PKG-002).
Этикетки ГМ. POST /v1/label/packages/get — этикетки для короба и паллеты. На складе: наклеить на закрытое грузоместо после укладки.
Пропуск (водитель). POST /v1/shipment/update с объектом pass — ФИО, телефон, модель и госномер ТС. Поле pass передаётся только через update, не через confirm.
Подтверждение. POST /v1/shipment/confirm — резерв слота, статус CONFIRMED. Успех: results[].status: "CONFIRMED" без error.
Список документов. POST /v1/shipment/document/list — в happy path запрос выполняется после confirm; ответ содержит документы типов UPD, ACCEPTANCE_ACT, WAYBILL со статусом AVAILABLE (доступен) или PENDING (формируется).
Скачивание документа. POST /v1/shipment/document/get — по document_id запрашивается свежая ссылка на файл в формате PDF или Excel.

Порядок маркировки на складе

┌─────────────────────────────────────────────────────────────┐
│  1. Состав поставки финализирован (холодильник + 3 телефона)│
│  2. API: label/items/get → печать товарных стикеров         │
│  3. НАКЛЕИТЬ стикер на каждый товар (1 + 3 = 4 шт.)         │
│  4. Уложить в ГМ: короб №1 ← телефоны, паллета №2 ← холодил.│
│  5. API: package/update → получить package_id               │
│  6. API: label/packages/get → печать этикеток ГМ            │
│  7. НАКЛЕИТЬ стикер на каждое закрытое грузоместо (2 шт.)   │
│  8. Данные водителя (pass) → confirm → document/list/get    │
└─────────────────────────────────────────────────────────────┘

Правило: товар → стикер на товар → укладка → стикер на ГМ. Нельзя клеить этикетку ГМ до маркировки товаров внутри и до фактической упаковки.

Методы маркировки по спецификации: /v1/label/items/get и /v1/label/packages/get. Поддерживаемые форматы: PDF, PNG, SVG, ZPL; размеры: SIZE_58x40, SIZE_58x30, SIZE_100x150, SIZE_A4.

JSON-примеры

Шаг 1 — POST `/v1/market/location/list`

{
  "filter": { "is_active": true }
}

Шаг 2 — POST `/v1/shipment/create`

{
  "market_location_id": "koledino",
  "shipment_date": "2026-06-12",
  "items": [
    { "offer_id": "FRIDGE-001", "product_id": "PRD-FRIDGE-01", "quantity": 1 }
  ],
  "idempotency_key": "create-shp-2026-06-12-koledino-001"
}

Ответ: { "shipment_id": "SHP-2026-042" }

Шаг 3 — POST `/v1/shipment/timeslot-list`

{
  "shipments": [{ "shipment_id": "SHP-2026-042" }]
}

{
  "results": [{
    "shipment_id": "SHP-2026-042",
    "timeslots": [{
      "id": "ts-2026-06-12-10",
      "start_time": "2026-06-12T10:00:00+03:00",
      "end_time": "2026-06-12T11:00:00+03:00"
    }]
  }]
}

Шаг 4 — POST `/v1/shipment/update` (таймслот)

{
  "shipment_id": "SHP-2026-042",
  "timeslot": { "id": "ts-2026-06-12-10" }
}

Шаг 5 — POST `/v1/shipment/update` (полная замена items)

{
  "shipment_id": "SHP-2026-042",
  "items": [
    { "offer_id": "FRIDGE-001", "product_id": "PRD-FRIDGE-01", "quantity": 1 },
    { "offer_id": "PHONE-001", "product_id": "PRD-PHONE-01", "quantity": 3 }
  ]
}

Шаг 6 — POST `/v1/label/items/get`

{
  "shipment_id": "SHP-2026-042",
  "items": [
    { "offer_id": "FRIDGE-001", "product_id": "PRD-FRIDGE-01", "quantity": 1 },
    { "offer_id": "PHONE-001", "product_id": "PRD-PHONE-01", "quantity": 3 }
  ],
  "format": "PDF",
  "size": "SIZE_58x40"
}

{
  "label": {
    "format": "PDF",
    "size": "SIZE_58x40",
    "content_type": "application/pdf",
    "content_base64": "JVBERi0xLjQK...",
    "page_count": 4
  }
}

Шаг 7 — POST `/v1/shipment/package/update`

{
  "shipment_id": "SHP-2026-042",
  "packages": [
    {
      "package_number": 1,
      "type": "BOX",
      "items": [{ "offer_id": "PHONE-001", "product_id": "PRD-PHONE-01", "quantity": 3 }]
    },
    {
      "package_number": 2,
      "type": "PALLET",
      "items": [{ "offer_id": "FRIDGE-001", "product_id": "PRD-FRIDGE-01", "quantity": 1 }]
    }
  ]
}

{
  "packages": [
    { "package_id": "PKG-001", "package_number": 1, "type": "BOX" },
    { "package_id": "PKG-002", "package_number": 2, "type": "PALLET" }
  ]
}

Шаг 8 — POST `/v1/label/packages/get`

{
  "shipment_id": "SHP-2026-042",
  "package_id": ["PKG-001", "PKG-002"],
  "format": "PDF",
  "size": "SIZE_100x150"
}

Шаг 9 — POST `/v1/shipment/update` (пропуск)

{
  "shipment_id": "SHP-2026-042",
  "pass": {
    "driver_name": "Иванов Иван Иванович",
    "driver_phone": "+79001234567",
    "vehicle_model": "ГАЗель NEXT",
    "vehicle_plate": "А123ВС777"
  }
}

Шаг 10 — POST `/v1/shipment/confirm`

{
  "shipments": [{
    "shipment_id": "SHP-2026-042",
    "timeslot": { "id": "ts-2026-06-12-10" }
  }]
}

{
  "results": [{
    "shipment_id": "SHP-2026-042",
    "status": "CONFIRMED"
  }]
}

Шаг 11 — POST `/v1/shipment/document/list`

{
  "shipment_id": "SHP-2026-042",
  "type": ["UPD", "ACCEPTANCE_ACT"],
  "format": "PDF"
}

{
  "documents": [
    {
      "document_id": "DOC-001",
      "type": "ACCEPTANCE_ACT",
      "status": "AVAILABLE",
      "created_at": "2026-06-12T11:05:00+03:00",
      "file": {
        "file_id": "FILE-001",
        "name": "acceptance_act.pdf",
        "url": "https://storage.example/acceptance_act.pdf?token=...",
        "expires_at": "2026-06-12T18:00:00+03:00"
      }
    },
    {
      "document_id": "DOC-002",
      "type": "UPD",
      "status": "PENDING",
      "file": {}
    }
  ]
}

Шаг 12 — POST `/v1/shipment/document/get`

{
  "document_id": "DOC-001",
  "format": "PDF"
}

{
  "document": {
    "document_id": "DOC-001",
    "type": "ACCEPTANCE_ACT",
    "status": "AVAILABLE",
    "created_at": "2026-06-12T11:05:00+03:00",
    "file": {
      "file_id": "FILE-001",
      "name": "acceptance_act.pdf",
      "url": "https://storage.example/acceptance_act.pdf?token=fresh...",
      "expires_at": "2026-06-12T20:00:00+03:00"
    }
  }
}

Сценарий 2: Альтернативный — отмена поставки

Мерчант отменяет отгрузку через POST /v1/shipment/cancel. По спецификации отмена доступна из статусов DRAFT и CONFIRMED; после ACCEPTED_AT_GATE отмена недоступна (HTTP 400).

Когда можно отменить

Жизненный цикл	`DRAFT` → `CONFIRMED` → `ACCEPTED_AT_GATE` → `COMPLETED`
Отмена	Из DRAFT или CONFIRMED → CANCELLED
cancelled_by	`MERCHANT` — инициатор мерчант; `MARKET` — маркетплейс (опционально в запросе)
Обязательные поля	`shipment_id`, `reason` (непустая строка)
Ответ cancel	Пустой объект `{}` при успехе

Вариант A — отмена из DRAFT

Мерчант создал черновик, получил слоты, но перед confirm решил не везти поставку. Отмена без резервирования слота.

POST /v1/shipment/create → DRAFT
(опционально) POST /v1/shipment/update — слот, items
POST /v1/shipment/cancel → CANCELLED

Вариант B — отмена из CONFIRMED

Мерчант прошёл полный цикл до confirm, слот зарезервирован. Затем отменяет поставку — слот освобождается, статус CANCELLED.

Шаги 1–10 сценария 1 → CONFIRMED
POST /v1/shipment/cancel с cancelled_by: "MERCHANT"
POST /v1/shipment/get → status: "CANCELLED"

Диаграмма отмены

При статусе ACCEPTED_AT_GATE или COMPLETED вызов /v1/shipment/cancel вернёт 400 — отмена недоступна для текущего статуса.

JSON-примеры отмены

POST `/v1/shipment/cancel` (из DRAFT или CONFIRMED)

{
  "shipment_id": "SHP-2026-042",
  "reason": "Изменение планов — поставка переносится на другую дату",
  "cancelled_by": "MERCHANT",
  "idempotency_key": "cancel-shp-2026-042-001"
}

Ответ при успехе:

{}

POST `/v1/shipment/get` — проверка статуса после отмены

{
  "shipment_id": "SHP-2026-042"
}

{
  "shipment_id": "SHP-2026-042",
  "market_location_id": "koledino",
  "shipment_date": "2026-06-12",
  "status": "CANCELLED",
  "items": [
    { "offer_id": "FRIDGE-001", "quantity": 1 },
    { "offer_id": "PHONE-001", "quantity": 3 }
  ],
  "packages": []
}

Статусы отгрузки и ключевые правила

items при update	Полная замена, не дельта
packages при `package/update`	Полная замена всех грузомест; суммы quantity = shipment.items
pass	Только через `update`, не в `confirm`
confirm с ошибкой	При частичном сбое — текст в `results[].error` (опционально), без отдельного enum-кода в спецификации
Документы	Статусы документа: `PENDING` (формируется), `AVAILABLE` (доступен); файл — `file_id`, `name`, `url`, `expires_at`
Проверка товаров	POST `/v1/shipment/items/check` — опциональная проверка пригодности товаров к поставке по складам (до создания отгрузки)
Остатки и цены	`product/stock/info` (остатки на складах маркетплейса), `product/price/update` / `product/price/info`; штрихкод маркетплейса — `product/barcode/generate`
Заказы и возвраты	Мониторинг: `order/fbo/status/list`, `order/fbo/list`; возвраты: `return/fbo/list`, `return/fbo/get`
Отчёты	`report/create` → `report/info` / `report/list` — файловые отчёты
Финансы	`finance/transaction/list`, `finance/payout/list`
Типы документов	`UPD`, `ACCEPTANCE_ACT`, `WAYBILL`
Форматы документов	`PDF`, `EXCEL`

Полный справочник методов FBO

Все методы FBO с детальными параметрами и примерами ответов доступны в разделе API Reference FBO.

Подключение по схеме FBO

Шаг 4 — POST /v1/shipment/update (таймслот)

Шаг 5 — POST /v1/shipment/update (полная замена items)

Шаг 9 — POST /v1/shipment/update (пропуск)

POST /v1/shipment/cancel (из DRAFT или CONFIRMED)

POST /v1/shipment/get — проверка статуса после отмены

Шаг 4 — POST `/v1/shipment/update` (таймслот)

Шаг 5 — POST `/v1/shipment/update` (полная замена items)

Шаг 9 — POST `/v1/shipment/update` (пропуск)

POST `/v1/shipment/cancel` (из DRAFT или CONFIRMED)

POST `/v1/shipment/get` — проверка статуса после отмены