Любимый город · API для бизнеса

Каталог, категории и обработка заказов

Скачать коллекцию PostmanСкачать пустое окружение

Бизнес-API каталога v1: руководство интегратора

Версия API: v1.

Документация на сайте: руководство интегратора. Файлы Postman: коллекция всех методов, шаблон окружения без секрета.

1. Назначение и адрес

API позволяет внешней системе компании читать, создавать, редактировать и удалять товары и категории, включать товары в категории, получать заказы, принимать их, менять этап обработки, завершать и отменять. Запросы выполняет сервер интеграции, например учётная система бизнеса.

Базовый адрес:

https://lyubimiigorod.ru/api/business/v1/companies/{companyId}

companyId — числовой ID компании. ID товара, категории и заказа — разные идентификаторы. Токен даёт доступ к данным одной компании. Токен филиала не даёт прав на товары головного магазина.

Для авторизации нужен токен бизнес-API. Cookie кабинета и токены других сервисов не подходят.

Метод и путь от базового адреса Действие Право токена
GET /products Список товаров products:read
GET /products/{id} Карточка товара с версией products:read
POST /products Создать товар products:write
PUT /products/{id} Сохранить основные поля карточки products:write
PATCH /products/{id} Изменить только указанные поля products:write
DELETE /products/{id} Удалить товар products:write
POST /products/{id}/photos Загрузить фотографию товара products:write
GET /properties Существующие свойства и значения для вариантов products:read
GET /categories Список категорий categories:read
GET /categories/{id} Категория и ID её товаров categories:read
POST /categories Создать категорию categories:write
PUT /categories/{id} Изменить категорию categories:write
DELETE /categories/{id} Удалить пустую категорию categories:write
PUT /categories/{id}/products/{productId} Включить товар в категорию categories:write
DELETE /categories/{id}/products/{productId} Исключить товар из категории categories:write
GET /orders Список заказов orders:read
GET /orders/{id} Заказ с составом и доступными действиями orders:read
POST /orders/{id}/open Отметить просмотренным orders:write
POST /orders/{id}/accept Явно принять заказ orders:write
POST /orders/{id}/stage Изменить этап orders:write
POST /orders/{id}/complete Завершить заказ orders:write
POST /orders/{id}/cancel Отменить заказ orders:write

Заказы через API не создаются и не удаляются; состав, покупатель и оплата не редактируются. Выполнение не подтверждает оплату, отмена не возвращает деньги через платёжного провайдера. Создание справочника свойств, сортировка и модерация маркетплейса в v1 остаются в кабинете. Фотографии API загружает отдельным методом, читает, позволяет выбрать главное и убрать из карточки. Загрузка по внешнему URL не поддерживается.

2. Авторизация и лимиты

Каждый запрос передаёт:

Authorization: Bearer bc1_<секретная_часть_токена>

Токен состоит из префикса bc1_ и 64 шестнадцатеричных символов. Передавайте его только в заголовке Authorization. Используйте HTTPS: запрос по HTTP отклоняется без перенаправления. Храните токен на сервере интеграции, не в публичном JavaScript или мобильном приложении.

Как получить и отозвать токен

  1. Войдите в кабинет под аккаунтом подтверждённого владельца нужной компании. Одного доступа сотрудника к каталогу недостаточно.
  2. В меню «Магазин» → «API и обмен данными» нажмите «Создать подключение». Адрес раздела: /{город}/my/biz/{адрес-компании}/shop-api. Для создания нужна действующая услуга «Интернет-магазин» или «Витрина».
  3. Укажите название интеграции и выберите права чтения и изменения товаров, категорий и заказов. Нажмите «Создать и получить токен».
  4. Скопируйте секрет сразу: после закрытия окна он повторно не показывается. Передайте его интегратору по защищённому каналу. В блоке «Для разработчика» указан базовый адрес с числовым companyId; там же доступны файлы Postman.
  5. Для отключения нажмите «Отозвать доступ» у нужного подключения. Восстановить отозванный токен нельзя. Отзыв доступен и после окончания услуги каталога.

Кабинет выпускает бессрочные токены. Новое подключение не отключает прежнее: для замены создайте новое, настройте интеграцию и затем отзовите старое. Если ответ при создании потерялся, обновите список; появившееся подключение с неизвестным секретом отзовите и создайте заново. Внешний Business API v1 не содержит метода выпуска токенов: это действие владельца в кабинете.

Каждое право назначается отдельно. write не заменяет read при чтении; обычной интеграции нужны оба права соответствующей группы. Операция записи возвращает изменённую сущность, поэтому право записи позволяет видеть её результат. Без orders:write перечни доступных действий и этапов в ответе пусты.

Проверяются токен, срок действия, отзыв, компания из URL, право на метод, действующая услуга internet_shop или vitrina, принадлежность всех сущностей. Чужая компания в URL — 403. Чужой товар, категория или заказ — 404.

Лимит: 120 запросов за минуту на токен, включая повторы. Минута — фиксированное окно серверного времени. При превышении — 429 и Retry-After с числом секунд ожидания. Недействительный токен — 401.

Ответы имеют Cache-Control: no-store и X-Request-Id — идентификатор запроса для обращения в поддержку. Междоменный браузерный доступ (CORS) не поддерживается: отправляйте запросы с сервера интеграции.

3. JSON, версии и безопасные повторы

Запись принимает UTF-8 JSON до 1 МиБ, кроме отдельной загрузки фото: она использует multipart/form-data, описанный ниже. Даже DELETE и действие без параметров принимают {}. GET не принимает тело. Query-параметры допустимы только у списков. Неизвестные поля отклоняются.

Content-Type: application/json
Idempotency-Key: 38db7ae4-00c3-4d1a-869c-7027402a8fd8

Успех: {"ok":true,"data":{...}}. Создание товара/категории — 201 и Location, остальные успешные операции, включая добавление фото, — 200. Удаление: {"ok":true,"data":{"id":123,"deleted":true}}.

Ошибка:

{"ok":false,"error":{"code":"revision_conflict","message":"Объект уже изменён. Получите его заново и сравните данные."}}

Клиент ориентируется на HTTP-статус и error.code; message предназначен человеку.

Версия защищает от одновременного редактирования

GET карточки возвращает data.revision (непрозрачная строка из 64 символов) и ETag с этой строкой в двойных кавычках. При сжатии ответа веб-сервер может добавить к ETag префикс W/. Для изменения или удаления существующего объекта нужен:

If-Match: "<revision из последнего ответа>"

Для включения/исключения товара используйте data.membership_revision категории, относящуюся к составу и порядку её товаров. Обычная revision категории нужна для названия, родителя, видимости и удаления. Версия товара не включает членство в категориях: оно защищается отдельно.

API v1 принимает If-Match в формах "<revision>" и W/"<revision>". Обе формы проверяют одну и ту же версию объекта; устаревшая версия отклоняется. При записи обычных полей карточки можно передать её ETag целиком. Поддержка формы W/ — расширение v1 относительно стандартной семантики If-Match.

Без версии — 428, неверный формат — 400, устаревшая версия — 409 revision_conflict. *, несколько версий и произвольные значения не поддерживаются. После 409 прочитайте сущность заново, сравните данные и отправьте новое решение с новой версией и новым ключом.

Ключ защищает от повторного выполнения

Для каждой записи обязателен Idempotency-Key: 16–128 символов A–Z, a–z, 0–9, ., _, :, -. Удобно использовать UUID. Новое действие — новый ключ. Сохраните ключ, метод, URL, If-Match и JSON до отправки. Формы "revision" и W/"revision" эквивалентны и при повторе запроса.

Если соединение оборвалось или пришёл 503, повторите тот же запрос с тем же токеном, ключом, версией и телом. JSON должен совпадать побайтово, включая форматирование. Успешный повтор вернёт первоначальный ответ и Idempotency-Replayed: true. Второй товар, повторный возврат остатка или проведение бонусов не возникнут. Сохранённый ответ описывает исходную операцию; актуальное состояние после последующих изменений читайте новым GET.

Другой запрос с занятым ключом — 409 idempotency_conflict. Ключи изолированы по токену: перед сменой токена сверяйте незавершённые запросы. После 400/403/404/409/422/428 исправляйте причину; новое решение отправляйте с новым ключом. После 429 подождите Retry-After и повторите исходный запрос.

Ключи не истекают автоматически. Если результат операции неизвестен, сохраняйте прежний ключ: запрос с новым ключом считается отдельной операцией.

4. Быстрый старт

Примеры — Bash и curl; ID условные. В Windows можно использовать curl.exe, а JSON сохранять в UTF-8 файл и передавать --data-binary @request.json. Переменная BUSINESS_API_TOKEN содержит выданный секрет.

BASE='https://lyubimiigorod.ru/api/business/v1/companies/12345'
TOKEN="$BUSINESS_API_TOKEN"

# Проверить подключение.
curl --fail-with-body -sS "$BASE/products" \
  -H "Authorization: Bearer $TOKEN"

# Создать товар. Для нового действия сгенерируйте собственный новый ключ.
curl --fail-with-body -sS -X POST "$BASE/products" \
  -H "Authorization: Bearer $TOKEN" \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: 38db7ae4-00c3-4d1a-869c-7027402a8fd8' \
  --data-binary '{"name":"Зелёный чай","description":"Упаковка 100 г","cost":"250.00","vendor":"TEA-100","track_balance":true,"balance":20}'

Из ответа возьмите data.id и data.revision. Задайте PRODUCT_ID и REV этими значениями:

# Обновить только цену.
curl --fail-with-body -sS -X PATCH "$BASE/products/$PRODUCT_ID" \
  -H "Authorization: Bearer $TOKEN" \
  -H 'Content-Type: application/json' \
  -H "If-Match: \"$REV\"" \
  -H 'Idempotency-Key: b94b1a2a-1342-4e6a-8247-df8e7566177c' \
  --data-binary '{"cost":"275.50"}'

Не включайте токен в логи, скриншоты или обращения в поддержку. Для диагностики передавайте X-Request-Id.

Быстрый старт в Postman

  1. Скачайте два JSON-файла по ссылкам в начале руководства. В Postman нажмите Import и выберите оба файла. Коллекция содержит все 22 метода в папках «Товары», «Категории», «Заказы», «Фотографии товара».
  2. Выберите импортированное окружение в правом верхнем углу. В его переменных укажите company_id и business_api_token. base_url задан как https://lyubimiigorod.ru, без завершающего /. Секрет храните в локальном значении переменной, не публикуйте окружение и не включайте его в общий репозиторий.
  3. Отправьте «01. Список товаров». Успешный ответ — HTTP 200 и ok: true. Во вкладке Params можно включить фильтры; изначально они выключены.
  4. Для работы с существующим объектом задайте product_id, category_id или order_id в переменных коллекции и выполните соответствующий GET карточки. Скрипт сохранит её ID и версии. После создания товара/категории ID также сохранится автоматически. Не создавайте одноимённые переменные ID/версий в окружении: они перекроют значения коллекции.
  5. Откройте нужную операцию, проверьте URL и JSON во вкладке Body, нажмите Send. Авторизация, Idempotency-Key и нужный If-Match подставляются автоматически. Отправляйте операции по одной: запись действует на рабочие товары и заказы. Запуск всей коллекции через Runner последовательно выполнит в том числе удаление и закрытие заказов.

В коллекции обычная category_revision используется для изменения/удаления категории, membership_revision — для её состава. Версии товара и заказа независимы. Скрипт не назначает ID из списков: объект выбирает человек. Перед записью после смены ID или компании обязательно заново получите карточку.

Пример каталога: создать категорию → создать товар → включить товар в категорию. После создания ID и версии уже доступны. Для существующей категории перед включением сначала получите её карточку. Исключение из категории сохраняет товар; удаление категории требует пустого состава и отсутствия дочерних категорий.

Пример заказа: список → задать order_id → карточка → принять → изменить этап. В переменных коллекции processing_stage изначально равен preparing. Далее установите ready, для доставки — delivering, затем завершите. Сверяйте available_actions и available_stages в ответе; просмотр не заменяет принятие, а завершение не подтверждает оплату.

Как повторять запись в Postman

Коллекция сохраняет ключ и исходную версию отдельно для каждого запроса. Повторный Send с теми же URL и JSON повторяет исходную операцию, включая уже успешную. Поэтому двойное нажатие не создаст второй товар. При изменении URL или JSON после известного ответа формируется новое действие и новый ключ.

Для отдельного нового действия с теми же URL и JSON установите new_operation=true в переменных коллекции. Скрипт создаст новый ключ и сбросит флаг. Например, так можно осознанно создать второй одинаковый товар. Если нужно повторно применить прежнюю цену после чужого изменения, сначала получите свежую карточку и также задайте new_operation=true.

При тайм-ауте, сетевом сбое, HTTP 5xx или 429 сохраняется прежняя операция. После паузы отправьте исходный запрос снова. Изменение URL/JSON при неизвестном результате блокируется скриптом до восстановления исходных данных или явного выбора новой операции. Не используйте new_operation для обхода этой проверки до выяснения результата: первая запись могла сохраниться.

После ошибки 409 revision_conflict получите свежую карточку, сравните данные и отправьте изменение с актуальной версией. После ответа с Idempotency-Replayed: true также выполните свежий GET: повтор возвращает исторический результат, поэтому коллекция не перезаписывает им текущие ID/версии. Служебные переменные __business_request_* хранят ключ, хеш запроса и исходную версию; секрет и тело запроса в них не сохраняются. Динамические переменные Postman вроде {{$guid}} внутри JSON записи не поддерживаются: их новое значение нарушило бы точный повтор.

Для загрузки откройте «22. Загрузить фотографию товара», в Body → form-data у поля photo типа File выберите один снимок. Content-Type вручную не добавляйте: Postman сам укажет правильную границу частей формы. Остальные заголовки заполняются скриптом. После успеха product_revision обновится.

Скрипт видит путь выбранного файла, но не читает его байты. После тайм-аута не редактируйте и не заменяйте файл по тому же пути. Сервер проверяет содержимое: другой файл с прежним ключом вызовет 409 idempotency_conflict. При этой ошибке коллекция сохраняет исходный ключ. Для отдельной новой загрузки сначала выясните результат через GET, затем установите new_operation=true. Повтор того же файла с тем же ключом остаётся безопасным, даже если multipart-граница или имя файла изменились.

Если Postman пропустил запрос, откройте Postman Console: сообщение укажет недостающую переменную или версию. Формат коллекции — Postman Collection v2.1.

5. Товары

Чтение

GET /products?q=чай&category=10&page=1. q — часть названия до 200 символов; category — ID своей категории или none для товаров без категории. Без категории в фильтре возвращаются все собственные товары, включая скрытые. Фильтры сочетаются. По 30 товаров на странице, page 1–100000; значение за последней страницей приводится к последней.

Ответ списка: data.items, total, page, pages. Строка содержит ID, название, цену, остаток, фото, признаки публикации/продажи, категории и сводку вариантов. Полная карточка GET /products/{id} дополнительно содержит revision, описание, дополнительные поля, category_ids, photos, offers, product_options. Перед изменением получите карточку. Постраничное чтение не фиксирует снимок всего каталога: параллельные изменения могут сдвигать страницы.

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

POST требует name и cost для обычного товара. Начальные значения: описание пустое, existence=true, sell=true, без учёта остатка (balance=-1), без категории и фото. Для вариантов цена задаётся в каждом варианте.

PUT требует name, description, existence, sell, track_balance, для обычного товара также cost, при включённом учёте — balance. Необязательные поля, фото, варианты и опции при отсутствии в запросе сохраняются. PATCH принимает непустой набор изменяемых полей.

Поле Тип и правило
name Непустая строка до 255 символов, без HTML и управляющих символов
description Обычный текст с переносами строк; до 65535 байт после HTML-экранирования
cost Цена строкой, например "125.50"; 0–99999999.99, до двух знаков после точки
existence, sell true/false или 0/1: наличие и разрешение продажи
track_balance true/false или 0/1; false отключает общий учёт остатка
balance Целое 0–2147483647; -1 отключает учёт. В PATCH без track_balance само задаёт режим учёта
product_type Целое: 0 товар, 1 услуга, 2 онлайн-запись, 3 цифровой товар
vendor, barcode, packing Строки до 100 символов: артикул, штрихкод, фасовка
brand, search Строки до 255 символов: бренд, поисковые слова
costold, bonus Суммы строками по правилу cost: старая цена и комиссия
price_prefix, price_info Строки до 50 символов перед/после цены
button_title Строка до 24 символов
link Полный http/https URL до 1024 байт без логина; обязателен для цифрового товара
in_card true/false или 0/1, хит продаж; до 12 хитов компании
main_photo Ключ существующего фото из photos, например "image:17" или "legacy"
remove_photos Массив ключей фото карточки, например ["image:18"]
variant_configuration Полная конфигурация вариантов, см. ниже
product_options Полный список дополнительных опций, см. ниже

null не принимается. Пустой текст — "". Флаги нельзя передавать строками "true"/"false". Денежные значения в карточке товара возвращаются строками без фиксированного количества десятичных знаков ("250", "250.5"). Общий остаток задаётся абсолютным значением, не прибавлением. В ответе может быть ранее сохранённый дробный остаток; запись нового остатка принимает только целое число.

id, company_id, visible, revision, category_ids, photos, offers и внутренние поля витрины только читаются. visible — системная публикация, не подменяйте им existence. Не отправляйте весь ответ GET обратно в PUT/PATCH: выберите разрешённые поля.

Для удаления нужна актуальная версия товара. Названия товаров в заказах и история покупок сохраняются. Исключение товара из категории не удаляет товар.

Загрузка фотографий

POST /products/{id}/photos добавляет одну фотографию к существующему товару. Сначала создайте товар или получите его карточку. Нужны products:write, обычная revision товара в If-Match и отдельный Idempotency-Key.

Тело — multipart/form-data с единственным файловым полем photo. JSON, photo[], дополнительные поля формы и query-параметры не принимаются. Ссылку на изображение передавать нельзя: интеграция отправляет сам файл.

Форматы и ограничения:

# REV берётся из GET /products/$PRODUCT_ID.
curl --fail-with-body -sS -X POST "$BASE/products/$PRODUCT_ID/photos" \
  -H "Authorization: Bearer $TOKEN" \
  -H "If-Match: \"$REV\"" \
  -H 'Idempotency-Key: 7a621bb0-4df8-48a2-8e5f-e1918c9eb20a' \
  -F 'photo=@/path/to/product.jpg'

Успешный ответ — 200, ETag и полная карточка товара в data, включая новые photos, main_photo и revision. Ключ нового фото имеет вид image:123; чтобы сделать его главным, отправьте отдельный PATCH {"main_photo":"image:123"} с новой версией и новым ключом. Для следующего снимка также используйте новую версию и новый ключ.

При повторе загрузки сохраняйте метод, URL, токен, If-Match, Idempotency-Key и те же байты файла. Сервер вычисляет SHA-256 содержимого; случайная multipart-граница, исходное имя и MIME-заголовок файла в отпечаток не входят. Повтор возвращает сохранённую карточку с Idempotency-Replayed: true и не создаёт новую строку галереи или пару файлов. Новый ключ означает отдельное добавление, даже если изображение совпадает.

При сетевом сбое или 503 повторите исходную загрузку с тем же ключом, версией и файлом. При превышении серверного лимита возможен ответ без JSON. Такой ответ не подтверждает сохранение фотографии.

Варианты

Сначала прочитайте GET /properties: data.properties содержит свойства компании и их значения. В карточке offers содержит properties, available, rows, editable. Справочник создаётся в кабинете.

Пример конфигурации нового набора вариантов (ID 1, 11, 12 условные, должны существовать у вашей компании):

{
  "variant_configuration": {
    "properties": [1],
    "offers": [
      {"id":0,"values":{"1":11},"price":"600.00","balance":"5"},
      {"id":0,"values":{"1":12},"price":"700.00","balance":"-1"}
    ],
    "removed": []
  }
}

Здесь balance варианта — строка по контракту существующего редактора. id=0 создаёт вариант; существующие передаются с ID из offers.rows. Полная конфигурация перечисляет все сохранённые варианты либо явно включает удаляемые ID в removed. До трёх свойств, без повторных сочетаний. Чужие свойства и варианты отклоняются.

Для правки цены повторите полную актуальную конфигурацию, сохранив ID и значения. Верхнеуровневый cost для вариативного товара без конфигурации отклоняется. При изменении сочетания свойств создаётся новый ID варианта, чтобы не подменить товар в существующей корзине. Для перехода к обычному товару передайте пустые properties/offers, прежние ID в removed и cost.

Остатки вариантов остаются ручными. Корзина и отмена заказа используют общий остаток товара: автоматического складского учёта по вариантам API не добавляет.

Дополнительные опции

{"product_options":[{"id":0,"name":"Подарочная упаковка","price":"50.00"}]}

Массив заменяет весь список. Существующие опции передавайте с их ID, новые с id=0; отсутствующие удаляются. [] убирает все опции. До 1000 опций, название до 150 символов без HTML, цена строкой. Отсутствующее поле сохраняет прежние опции.

6. Категории и товары в них

GET /categories возвращает data.items: id, name, pid, view, chpu, sort, product_count, revision. Карточка категории также содержит product_ids, membership_revision, но не product_count. Список категорий в v1 возвращается целиком.

POST: {"name":"Напитки","pid":0,"view":1}. pid=0 — верхний уровень, view=1 — показывать, 0 — скрыть. У POST pid и view необязательны; PUT требует все три поля и обычную revision в If-Match. Название до 255 символов, адрес chpu формирует сервер.

Поддерживаются два уровня. Родитель принадлежит той же компании и находится на верхнем уровне. Категорию с дочерними нельзя сделать дочерней. Удаление допустимо только без товаров и дочерних категорий.

# После GET категории MEMBERSHIP_REV = data.membership_revision.
curl --fail-with-body -sS -X PUT "$BASE/categories/$CATEGORY_ID/products/$PRODUCT_ID" \
  -H "Authorization: Bearer $TOKEN" -H 'Content-Type: application/json' \
  -H "If-Match: \"$MEMBERSHIP_REV\"" \
  -H 'Idempotency-Key: 6e99e2cc-80c8-461d-9b67-fd7cf1766b90' \
  --data-binary '{}'

Исключение: DELETE по тому же адресу со свежей membership_revision и новым ключом. Товар может входить в несколько категорий. Повтор включения с актуальной версией не создаёт дубликат. Состав обновляет поисковые данные товара по правилам кабинета.

7. Заказы

Состояние и этап обработки

state — целое число: 0 — незавершённый, 1 — «Забрали», 2 — выполнен, 3 — отменён. Заказы с state=1 доступны только для чтения.

processing_stage — строка или null: new, accepted, preparing, ready, delivering. Промежуточные этапы сохраняют state=0. При state=2/3 итоговое название всегда «Выполнен»/«Отменён», независимо от processing_stage. Поле этапа возвращается в ответе, но для закрытого заказа не учитывается.

null означает, что этап не задан. При state=0, processing_stage=null и opened=0 подпись — «Ожидает обработки», при opened=1 — «В обработке». Чтобы назначить new, отправьте соответствующую команду /stage.

GET никогда не принимает и не открывает заказ. /open меняет только opened и время просмотра. /accept явно устанавливает accepted и не подменяет просмотр. payment_status и payment_type независимы от обработки.

Чтение и фильтры

GET /orders?state=0&processing_stage=preparing&page=1. По 30 строк, сначала новые по дате, затем ID. Ответ: data.items, total, page, pages, применённые state, processing_stage.

state: all/отсутствие, 0, 1, 2, 3. processing_stage: all/отсутствие, none для NULL, new, accepted, preparing, ready, delivering. Фильтр этапа выбирает только state=0; с state=1/2/3 результат пустой. none не выбирает new. Неизвестный фильтр — 400, не молчаливое чтение всех заказов.

Список и карточка возвращают state, processing_stage, opened, payment_status, status_label, revision, available_actions, available_stages. Также есть контакты, комментарий, даты, способ оплаты, суммы товаров, доставки и бонусов. В карточке items содержит сохранённые позиции: название, количество cnt, цену price, sum, выбранные options. Суммы заказа — JSON-числа; total = items_sum + sum_ship - bonus_apply. Это суммы заказа, не отчёт о поступлении денег.

Для отображения используйте status_label. state_label не показывает подробный этап. Поля дат data, dataget, datadone возвращаются строками без часового пояса. date_label содержит время города в формате для отображения, не ISO 8601.

Фрагмент карточки:

{"state":0,"processing_stage":"accepted","opened":1,"payment_status":0,"status_label":"Принят","available_actions":["stage","complete","cancel"],"available_stages":["preparing"]}

available_actions и available_stages зависят от состояния заказа и прав токена. Между GET и POST заказ может измениться: передавайте актуальную revision. Если с заказом связано несколько незавершённых покупок, закрытие отклоняется.

Допустимые переходы

В v1 недоступны пропуск промежуточных этапов, возврат назад, отмена из delivering и изменение заказа с state=1. Завершение через /complete допускается при любом этапе заказа с state=0.

Исходное состояние Действие Результат
state=0, любой этап open opened=1; повтор сохраняет время первого просмотра
state=0, NULL stage, processing_stage=new Этап new, «Новый»
state=0, NULL или new accept accepted, «Принят»
state=0, accepted stage, preparing «Готовится»
state=0, preparing stage, ready «Готов к выдаче или отправке»
state=0, ready stage, delivering «Доставляется»; самовывозу этап не требуется
state=0, любой этап complete state=2, «Выполнен»
state=0, NULL/new/accepted/preparing/ready cancel state=3, возврат общего остатка, отмена покупки/бонусов
state=0, delivering или неизвестный этап cancel 409, переход запрещён
state=1 Любая команда 409; только чтение
state=2/3 open, accept, stage или другой исход закрытия 409; GET доступен
state=2 → complete, state=3 → cancel Повтор закрытия с актуальной версией Успех без повторных последствий

Повтор текущего допустимого этапа и /accept из accepted не меняет состояние повторно. /stage не принимает accepted: для принятия используйте /accept. Очистка этапа в null не поддерживается.

Пример последовательности: GET → /accept → /stage preparing → /stage ready → /complete для самовывоза. Для доставки перед complete добавляется delivering. Каждая запись использует новую revision из предыдущего ответа и собственный ключ:

curl --fail-with-body -sS -X POST "$BASE/orders/$ORDER_ID/accept" \
  -H "Authorization: Bearer $TOKEN" -H 'Content-Type: application/json' \
  -H "If-Match: \"$ORDER_REV\"" \
  -H 'Idempotency-Key: 35b533eb-bf7a-4bf8-a893-ed14518c953a' \
  --data-binary '{}'

# STAGE_REV — новая revision принятого заказа.
curl --fail-with-body -sS -X POST "$BASE/orders/$ORDER_ID/stage" \
  -H "Authorization: Bearer $TOKEN" -H 'Content-Type: application/json' \
  -H "If-Match: \"$STAGE_REV\"" \
  -H 'Idempotency-Key: 05ab9e58-eafd-4a0b-b5f4-ecac8eaef23b' \
  --data-binary '{"processing_stage":"preparing"}'

Завершение подтверждает покупку и бонусы. При отмене покупка и бонусы отменяются, количество возвращается в общий учитываемый остаток по сохранённому составу заказа. Изменение этапа не меняет оплату, остатки и бонусы. Закрытый заказ нельзя открыть заново через API.

8. Ошибки

HTTP Примеры error.code Что делать
400 https_required, invalid_json, object_required, invalid_query, invalid_page, invalid_state, invalid_stage, invalid_id, invalid_revision, idempotency_key_required Исправить запрос
401 invalid_token Проверить токен, срок, отзыв, заголовок
403 company_forbidden, scope_forbidden, catalog_unavailable Проверить компанию, права, услугу
404 not_found Проверить ID: сущность может быть чужой или удалённой
405 method_not_allowed Допустимые методы указаны в заголовке Allow
409 revision_conflict, transition_forbidden, idempotency_conflict Сверить состояние и ключ запроса
413 body_too_large, photo_too_large Уменьшить JSON или файл с учётом лимита всего запроса
415 json_required, multipart_required Для фото нужен multipart/form-data, для остальных записей JSON
422 validation_failed, unknown_fields, required_field, invalid_money, invalid_flag, invalid_balance, invalid_text, invalid_structure, invalid_product_type, variant_price_required, empty_patch, null_not_allowed Исправить поля или нарушенное правило
428 revision_required GET, затем версия в If-Match
429 rate_limit Подождать Retry-After
503 temporarily_unavailable Повторить исходную запись с прежним ключом и паузой; при длительном сбое сообщить X-Request-Id

Для фото 422 photo_required означает неверное/лишнее поле формы, photo_upload_failed — неполную или отсутствующую загрузку, validation_failed — недопустимое содержимое, размер или разрешение снимка.