HappyCake

Меню на дату для города (опционально — для конкретной точки). Показывает только позиции, которые реально в наличии (без числового остатка — просто да/нет). id варианта (product_def_id) используется в add_to_cart/remove_from_cart. date обязателен и равен желаемой дате получения заказа: на сегодня остаток реальный, на будущее — по плану продаж.

list_menu

Сохранённые адреса доставки клиента в этом городе (из прошлых заказов/профиля). id адреса передавай в create_cart как address_id — предпочтительнее suggest_address, координаты уже подтверждены.

get_my_addresses

История заказов клиента, постранично (0 — самая свежая страница).

list_my_orders

Отправить в HappyCake отзыв о своём полученном заказе: общая оценка 1-5, по желанию текст и отдельная оценка доставки или точки самовывоза. Отзыв передаётся магазину, это не личная заметка клиента. Работает только после получения заказа и не дольше 4 дней после него. Повторный вызов ЗАМЕНЯЕТ прежний отзыв по этому заказу. Оценку и текст передавай только со слов пользователя — не выдумывай и не улучшай формулировки.

leave_review

Отменить заказ. Если заказ уже оплачен, вместо простой отмены магазин автоматически оформит ВОЗВРАТ средств через платёжного провайдера тем же способом оплаты — статус возврата проверяй через get_order_status. Если заказ уже в пути к получателю (курьер выехал), отмена невозможна — направь пользователя в колл-центр точки (см. get_store_info). Спроси у пользователя явное подтверждение перед вызовом — действие необратимо. Требуется НОМЕР заказа (orderNumber из get_order_status/list_my_orders, не id) — это подтверждает, что ты отменяешь именно тот заказ, который только что показал пользователю, а не какой-то другой из его истории на другом канале (сайт/приложение/колл-центр).

cancel_order

Оформить заказ и оплатить. expected_total ОБЯЗАТЕЛЕН и должен совпадать с суммой из preview_order — если сумма успела измениться, тул откажет и вернёт новую сумму (защита от оплаты неподтверждённой суммы). Способы оплаты: CARD — банковской картой, вернёт ссылку на оплату на happycake.kz. FORTE — прежнее имя того же способа, тоже принимается. Пользователю оба варианта называй «картой»; KASPI — ссылки НЕ будет, счёт придёт в приложение Kaspi на телефон клиента, статус проверяй через get_order_status; PAY_ON_PICKUP — оплата на месте, доступна только если у точки это разрешено (см. get_store_info/preview_order). pickup_time обязателен для самовывоза. recipient_phone — ТОЛЬКО телефон, который явно продиктовал пользователь; никогда не придумывай и не подставляй чужой номер — на него будет отправлено SMS/счёт.

place_order_and_pay

Подбор нового адреса доставки по тексту (город + что вводит пользователь). Возвращает варианты с suggestion_id — именно его, а НЕ текст/координаты, передавай в create_cart как suggestion_id. Никогда не придумывай координаты или адрес сам — только через этот тул или через сохранённые адреса (get_my_addresses).

suggest_address

Обязательный шаг перед оплатой: пересчитывает корзину и ПЕРЕЗАПИСЫВАЕТ сохранённые суммы и рассчитанные скидки. Возвращает актуальную сумму expected_total — именно её передай в place_order_and_pay после подтверждения пользователем. Заказ не оформляет и деньги не списывает. Также показывает доступные способы оплаты для точки. FORTE в списке означает банковскую карту — пользователю говори «картой».

preview_order

Применить промокод к текущей активной корзине. Если код не подошёл (не существует, не действует или уже использован), корзина вернётся БЕЗ изменений и без ошибки — сообщи об этом пользователю честно, не выдумывай причину. Промокод только тот, что продиктовал пользователь — не придумывай и не предлагай его сам; список акций в list_promos не гарантирует, что их name совпадает с промокодом.

apply_promo

Проверка возможности доставки по адресу: доступна ли доставка прямо сейчас, минимальная сумма заказа для доставки в этом городе, и ближайшие свободные диапазоны времени доставки (их id передавай в create_cart как delivery_range_id). Вызывай ДО сборки корзины на доставку. Передай product_def_ids (из list_menu/get_cart), если уже известно, что именно заказывают — иначе тул может вернуть диапазон точки, у которой нет нужного товара, и create_cart с ним не пройдёт.

check_delivery

Данные профиля текущего клиента: телефон, имя, e-mail и дата рождения (если указаны). Используй, чтобы напомнить пользователю его данные или подставить полное имя в место заказа — не спрашивай эти данные заново, если они уже здесь.

get_profile

Завести новую корзину — самовывоз (mode=PICKUP, нужны store_id и pickup_time) или доставка (mode=DELIVERY, нужны delivery_range_id из check_delivery и ОДИН из address_id/suggestion_id + city_id). Подсказка адреса даёт только дом: если это многоквартирный дом или бизнес-центр, ОБЯЗАТЕЛЬНО спроси у пользователя номер квартиры или офиса и передай в flat, иначе курьеру некуда звонить. Для частного дома flat не нужен — не спрашивай. Если активная корзина уже есть, вернёт её содержимое без ошибки — всегда вызывай get_cart перед этим тулом.

create_cart

Включить/выключить списание бонусных коинов Happy Cake на ТЕКУЩУЮ активную корзину (см. get_cart) — переключает существующую корзину, не создаёт новую. Итоговую сумму списания (не больше половины суммы заказа и не больше баланса клиента) магазин посчитает сам при оплате — здесь только переключается флаг, точную сумму скидки узнать заранее нельзя, проверяй фактический итог через preview_order/get_order_status. После оплаты или отмены заказа переключение уже не действует (магазин молча игнорирует вызов).

apply_coins

Статус заказа по его id: оплачен ли, текущий статус, сумма, дата/время получения, история событий. Используй после place_order_and_pay, особенно для Kaspi (там нет ссылки на оплату — статус узнаётся только так) и когда неясно, создался ли заказ после ошибки.

get_order_status

Список точек (кондитерских) Happy Cake в конкретном городе. city_slug бери из list_cities. date — опционально, по умолчанию сегодня; влияет на то, какие точки работают в этот день.

list_stores

Убрать товар из корзины (на 1 штуку, либо весь остаток при remove_all=true). Если это был последний товар, корзина закрывается — cart в ответе будет пустым.

remove_from_cart

Убрать применённый промокод с текущей активной корзины.

cancel_promo

Фискальный чек заказа: номер, дата/сумма, ссылка на электронный чек (OFD). Пока заказ не оплачен и не пробит на кассе — фискальных полей и ссылки не будет, это не ошибка.

get_receipt