API мобильного приложения (1.0.0-draft)

Листинг каталога сети (разделы, карточки, цены в списке) — TODO, описывается отдельно. На него же ведут url секций satellites в карточке товара («добавить к заказу» и т. п.).

От листинга этому API нужно одно: uuid и type товара. С ними приложение открывает карточку и кладёт товар в корзину.

• Базовый путь /api/v1. JSON, UTF-8, ключи в snake_case.
• Поле без значения приходит как null, пустой список — как []. Ключи не пропадают.
• Неизвестные поля клиент игнорирует: новые поля добавляются без смены версии.
• Успех — {"data": …}. У постраничных списков рядом meta с page, per_page, total.
• Ошибка — {"error": {"code", "message", "fields"}}. Ветвиться только по code; message — готовый русский текст, его можно показать.
• Деньги — {"currency": "BYN", "amount": "26.90"}. Сумма всегда строка с двумя знаками. Суммы считает сервер, клиент их не пересчитывает.
• Телефон — +375 и 9 цифр, без пробелов и скобок.
• Дата и время — ISO 8601 со смещением (2026-11-12T18:30:00+03:00). Слоты времени — строки HH:MM по времени Минска.
• Идентификаторы — uuid. В примерах вместо настоящих uuid стоят подписи в угловых скобках (<big_size_uuid>), чтобы было видно, что на что ссылается.
• Торговая сеть в путях — её slug из GET /trade-networks (pzz, godzilla, donex); в приложение список сетей не зашивается.

401, 429, 500 и 503 возможны у любого запроса и в описаниях запросов не повторяются. Автоматически повторять можно только GET. Создание заказа повторяется с тем же Idempotency-Key.

Всё состояние посетителя живёт на сервере в сессии. Приложение хранит только токен.

Объект сети сервер выбирает сам: при доставке — по зоне выбранного адреса, при самовывозе — это выбранная точка сети. У разных объектов разные цены и наличие. В POC «Лисичка» стоит 26,90 на Немиге и 27,90 на Лобанке.

GET /session отдаёт всё это одним ответом. Запросы, которые меняют адрес, тип обслуживания или вход, возвращают обновлённую сессию. Если у сети сменился point.uuid, приложение перезагружает её листинг и корзину.

Пока у сети нет объекта (point: null), приложение показывает нулевое меню сети: общий ассортимент и общие цены. Объекта нет в трёх случаях:

1. адрес доставки ещё не выбран;
2. адрес выбран, но сеть туда не доставляет (delivery.available: false);
3. выбран самовывоз, а точка этой сети не выбрана.

В нулевом меню карточка товара открывается и отдаёт те же данные, но положить товар в корзину нельзя: POST …/cart/items ответит 409 с кодом случая. Приложение этот ответ не ждёт — оно видит point: null и по нажатию «+» открывает выбор адреса, как в POC.

1. Токена нет — POST /session, сохранить токен в защищённом хранилище. Токен есть — GET /session. На 401 session_expired создать сессию заново: адрес, корзины и вход потеряны.
2. GET /trade-networks — вкладки сетей.
3. Листинг открытой сети.
4. Дальше — по действиям пользователя.

1. Наличие в карточке товара. В структуре товара нет признака «недоступно» ни у варианта, ни у добавки. В POC он есть: зачёркнутый чип «пайк-борт с чеддером», «нет в наличии» у всей позиции. Предложение: is_available у варианта и у каждой добавки. До решения приложение узнаёт о недоступности из листинга и из ответа 422 item_unavailable.
2. Недоступные позиции при оформлении. Сейчас описано как в POC: заказ нельзя оформить, пока их не удалят. Другой вариант — заказ создаётся из доступных позиций.
3. Смена телефона. Если к первой версии не успеваем — поле телефона в профиле только для чтения.

Сессия создаётся один раз и живёт 30 дней с последнего запроса. В ней адрес, корзины, выбор по каждой сети и вошедший клиент. Гость и вошедший клиент работают одинаково: вход нужен только для кабинета.

После входа по SMS сервер выдаёт новый токен, прежний перестаёт работать. Адрес и корзины при этом сохраняются.

Список сетей маркетплейса. Справочник, меняется редко — можно держать в памяти 5 минут.

Карточка товара. Структура зависит от type; общие поля у всех типов одинаковые, остальное лежит в ключе с именем типа.

Цены и доступность зависят от объекта сети. Объект сервер берёт из сессии; если объекта нет — отдаёт данные нулевого меню.

1. dims — измерения и их значения. У пиццы одно измерение size; экран рисует по строке на каждое значение.
2. variants — продаваемые варианты. Вариант находится по совпадению его dims с выбранными значениями. Комбинации без варианта не продаются.
3. known_additions и known_modifiers — справочник всего, что бывает у товара. Что доступно конкретному варианту, перечислено в его suitable_additions и suitable_modifiers: там uuid записей верхнего уровня справочника — одиночных добавок и контейнеров.
4. Одна и та же по смыслу добавка у разных вариантов — разные записи с разными uuid и ценами: «Двойной сыр» стоит 4,00 для стандартной и 5,00 для большой. Показывать name; inner_name — служебное название.

default контейнера — uuid записи, выбранной изначально, или null, если изначально ничего не выбрано. В корзину передаются uuid самих добавок и модификаторов, не контейнеров.

Цена единицы = base_price варианта + сумма цен выбранных добавок с учётом количества. Это для показа до добавления; после добавления цену позиции отдаёт корзина. suppressed_price — прежняя, зачёркнутая цена; null, если скидки нет.

recipes — данные по конкретным сочетаниям. Запись подходит, если её properties.dims равны выбранным, а properties.additions содержит ровно выбранные добавки. Порядок поиска:

1. точное совпадение варианта и добавок;
2. тот же вариант без добавок;
3. ничего не нашлось — блок состава и КБЖУ не показывать.

nutrition_facts — на 100 г: белки, жиры, углеводы в граммах, энергия в ккал. product_amount и product_measure — готовые строки для показа («830 г», «36 см»).

У group вложенные товары в items[].target показываются как состав набора («Что входит в набор»), отдельно их не купить. В корзину кладётся сам набор; добавки и модификаторы у набора свои, по тем же правилам.

У family каждый вложенный товар — полноценный товар своего типа со своим uuid, ценой и добавками. Экран рисует по строке на каждый; в корзину кладётся uuid вложенного товара, не семейства. У самого семейства нет ни цены, ни добавок, ни состава. Количество для карточки семейства в листинге отдаёт корзина в counters.

satellites — секции под карточкой («добавить к заказу» и т. п.). В товаре секция только объявлена: для каждой приложение делает отдельный запрос по её url и рисует её независимо от карточки. url ведёт на листинг каталога, ответ — в формате листинга.

Адрес доставки один на все сети. Выбрали «Гикало, 18» в Лисицце — он же действует в Godzilla и Donex.

По одному адресу сети работают по-разному. PUT /address всегда отвечает 200, если дом существует, и возвращает сессию, где у каждой сети свой итог:

Выбор адреса включает доставку для всех сетей: service_type сессии становится delivery.

То, что сеть не доставляет по адресу, — не ошибка запроса. Корзина такой сети отдаётся с 200 и причиной address_out_of_zone в blockers.

В POC два поля: «Улица», затем «Дом». GET /address/search?kind=street — подсказки улиц, GET /address/streets/{uuid}/buildings — дома улицы. Тот же поиск без kind принимает строку целиком («лобанка 77») и возвращает и улицы, и дома.

Дом выбирается только из списка: свободного ввода нет. Запрос подсказок — от 2 символов, с задержкой не меньше 250 мс после последнего нажатия; предыдущий незавершённый запрос отменяется. Подсказки не кэшируются.

Это не часть адреса сессии: их вводят в форме заказа. Если адрес выбран из сохранённых (saved_address_uuid), сессия отдаёт их в address.details — ими заполняется форма.

Тип обслуживания один на все сети: выбрали самовывоз — он действует в Лисицце, Godzilla и Donex. Точка самовывоза у каждой сети своя. Сеть, в которой точка ещё не выбрана, остаётся без объекта и показывает нулевое меню.

Переключение ничего не стирает: адрес и выбранные точки остаются в сессии. Вернулись на доставку — сети снова работают по адресу, вернулись на самовывоз — по своим точкам.

Смена типа обслуживания или точки меняет объект сети, а с ним цены и наличие. Корзина остаётся та же: сервер пересчитывает её по новому объекту, позиции, которых там нет, становятся inactive.

У каждой сети своя корзина. Она появляется при первом добавлении и живёт 24 часа с последнего изменения. Пустая корзина — обычный ответ 200 с uuid: null и пустым items.

Каждый запрос корзины возвращает её целиком и уже пересчитанной. Отдельного запроса «проверить корзину» нет: GET и есть проверка. Его вызывают при открытии корзины и при возврате приложения из фона.

Позиция — это товар, вариант, набор добавок и набор модификаторов. У позиции свой uuid.

• Тот же товар с тем же составом — одна позиция, растёт quantity.
• Тот же товар с другим составом — другая позиция.
• Состав относится ко всем единицам позиции. Изменить одну пиццу из трёх: уменьшить количество на 1 и добавить новую позицию с другим составом.

counters в корзине — готовое количество для карточек листинга: uuid товара карточки и сколько его единиц в корзине. У товара с вариантами это сумма по всем его позициям, у family — сумма по вложенным товарам. Приложение само ничего не складывает и состав семейства для этого не запрашивает.

В POC пицца попадает в корзину нажатием кнопки в строке размера, а добавки переключаются уже после. Это три запроса:

POST  /trade-networks/pzz/cart/items
      {"product_uuid": "<pizza>", "dims": {"size": "<big>"}}
      → meta.item_uuid = "<line>"

PATCH /trade-networks/pzz/cart/items/<line>
      {"modifiers": ["<без лука>"]}

PATCH /trade-networks/pzz/cart/items/<line>
      {"additions": [{"uuid": "<двойной сыр для большой>", "quantity": 1}]}

Если состав выбран до нажатия, всё уходит одним POST с dims, additions и modifiers.

Правила PATCH:

• Переданный ключ заменяет свою часть целиком. additions — это полный новый список добавок, а не «добавь ещё одну». Снять все добавки — "additions": []. Ключ не передан — часть не меняется.
• quantity — итоговое количество, а не приращение. Серию нажатий «+» можно отправить одним запросом. 0 удаляет позицию.
• Вариант (dims) у позиции не меняется. Другой размер — это другая позиция: в POC у каждого размера своя строка и свой счётчик.
• Если после замены состав совпал с другой позицией, они сливаются. meta.item_uuid указывает на оставшуюся.

При ошибке корзина не меняется.

Позиция может стать недоступной уже в корзине: товар поставили на стоп, сменился объект, закончилось время действия меню. Такая позиция остаётся в корзине со status: inactive и причиной в inactive_reason. В суммы она не входит. Количество и состав у неё менять нельзя — только удалить. Пока в корзине есть такие позиции, оформить заказ нельзя: в blockers причина items_inactive. Когда товар снова доступен, позиция сама становится active.

Если у сети пропал объект (сменили адрес, сеть туда не доставляет), недоступными становятся все позиции, суммы обнуляются, в blockers — address_out_of_zone. Позиции не удаляются: вернули адрес — корзина ожила.

can_checkout: false и список blockers. Приложение показывает message и не даёт нажать «заказать».

warnings оформлению не мешают, их просто показывают: price_changed — цена позиции изменилась с прошлого ответа.

delivery.cost — стоимость доставки по адресу при текущей сумме. free_from — порог бесплатной доставки, left_to_free — сколько до него осталось. Заказ ниже порога оформить можно, доставка будет платной. Порог сравнивается с суммой до скидок.

discounts — применённые скидки с готовыми подписями («Скидка 10% на товары»). В POC скидка видна только в чеке после заказа; в API она есть в корзине всегда.