Бизнес-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 или мобильном приложении.
Как получить и отозвать токен
- Войдите в кабинет под аккаунтом подтверждённого владельца нужной компании. Одного доступа сотрудника к каталогу недостаточно.
- В меню «Магазин» → «API и обмен данными» нажмите «Создать подключение». Адрес раздела:
/{город}/my/biz/{адрес-компании}/shop-api. Для создания нужна действующая услуга «Интернет-магазин» или «Витрина». - Укажите название интеграции и выберите права чтения и изменения товаров, категорий и заказов. Нажмите «Создать и получить токен».
- Скопируйте секрет сразу: после закрытия окна он повторно не показывается. Передайте его интегратору по защищённому каналу. В блоке «Для разработчика» указан базовый адрес с числовым
companyId; там же доступны файлы Postman. - Для отключения нажмите «Отозвать доступ» у нужного подключения. Восстановить отозванный токен нельзя. Отзыв доступен и после окончания услуги каталога.
Кабинет выпускает бессрочные токены. Новое подключение не отключает прежнее: для замены создайте новое, настройте интеграцию и затем отзовите старое. Если ответ при создании потерялся, обновите список; появившееся подключение с неизвестным секретом отзовите и создайте заново. Внешний 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
- Скачайте два JSON-файла по ссылкам в начале руководства. В Postman нажмите Import и выберите оба файла. Коллекция содержит все 22 метода в папках «Товары», «Категории», «Заказы», «Фотографии товара».
- Выберите импортированное окружение в правом верхнем углу. В его переменных укажите
company_idиbusiness_api_token.base_urlзадан какhttps://lyubimiigorod.ru, без завершающего/. Секрет храните в локальном значении переменной, не публикуйте окружение и не включайте его в общий репозиторий. - Отправьте «01. Список товаров». Успешный ответ — HTTP 200 и
ok: true. Во вкладке Params можно включить фильтры; изначально они выключены. - Для работы с существующим объектом задайте
product_id,category_idилиorder_idв переменных коллекции и выполните соответствующий GET карточки. Скрипт сохранит её ID и версии. После создания товара/категории ID также сохранится автоматически. Не создавайте одноимённые переменные ID/версий в окружении: они перекроют значения коллекции. - Откройте нужную операцию, проверьте 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-параметры не принимаются. Ссылку на изображение передавать нельзя: интеграция отправляет сам файл.
Форматы и ограничения:
- JPG/JPEG, PNG или WebP; формат определяется по содержимому. SVG, GIF и другие форматы не принимаются.
- Файл до 8 МиБ (8 388 608 байт), разрешение до 16 000 000 пикселей. Весь multipart-запрос — до 9 МиБ.
- Изображение декодируется и сохраняется заново под случайным именем. Основной файл вписывается в 1600 × 1600, миниатюра — в 320 × 320 с сохранением пропорций. Имя и MIME-тип клиента не используются для выбора расширения.
- Существующие фотографии остаются. Новая добавляется в конец галереи; у товара без фотографий становится главной. Цена, остаток, описание, варианты и опции не меняются.
# 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 — недопустимое содержимое, размер или разрешение снимка.