Методы заказа
| Метод | Адрес | Кто вызывает | Начинает сессию |
|---|---|---|---|
| Настройки магазина и выбор покупателя | GET /api/sale | гость и вошедший | нет |
| Типы плательщиков | GET /api/sale/personTypes | гость и вошедший | нет |
| Справочник статусов заказа | GET /api/sale/orderStatus | гость и вошедший | нет |
| Пересчитать заказ при оформлении | POST /api/sale/order/refresh | гость и вошедший | да |
| Оформить заказ | POST /api/sale/order/save | гость и вошедший | да |
| История заказов | GET /api/sale/orderByStatus | вошедший | нет |
| Карточка заказа | GET /api/sale/order | вошедший | нет |
| Отменить заказ | POST /api/sale/order/cancel | вошедший | нет |
| Действие над заказом | POST /api/sale/orderOperation | вошедший | нет |
Методы «только для вошедших» отвечают гостю одинаково: статус 401 и тело {"success": false, "error": "Требуется авторизация"}; проверка идёт до разбора параметров.
Сценарий оформления
- Корзина собрана (Корзина), у витрины есть
X-Session-Id. GET /api/sale— ограничения магазина (минимальная сумма заказа, бесплатная доставка, вес) и текущий выбор покупателя.GET /api/sale/personTypes— переключатель «Физическое лицо / Юридическое лицо».GET /api/profile/fields?personTypeId=...— поля формы (Профили покупателя).- Город и доставка:
GET /api/sale/location/search,POST /api/sale/setLocation,GET /api/sale/delivery,POST /api/sale/setDelivery(Доставка и местоположение). - После каждого выбора (тип плательщика, доставка, оплата, свойства, купон, списание баллов) —
POST /api/sale/order/refresh: витрина получает пересчитанный заказ. - Кнопка «Оформить заказ» —
POST /api/sale/order/saveс теми же данными. - Страница «Спасибо за заказ» —
GET /api/sale/order?orderID=...; оплата — Оплата.
Данные заказа
Тело order/refresh и order/save — данные заказа напрямую, все поля необязательные:
| Поле | Что это |
|---|---|
personTypeID | тип плательщика (GET /api/sale/personTypes) |
deliveryID | служба доставки (GET /api/sale/delivery) |
paymentID | платёжная система |
profileID | сохранённый профиль покупателя (GET /api/profile) |
description | комментарий к заказу |
properties | значения свойств заказа: ID свойства => значение; для свойства-местоположения — code из /api/sale/location/search, для «да / нет» — Y или N |
withdraw | сумма списания баллов со внутреннего счёта, по умолчанию 0 |
enterCoupon, removeCoupon | только в refresh: прикрепить или убрать купон (взаимоисключающие; прикреплённый купон повторно отправлять не нужно) |
basketOnly | только в refresh: Y — считать только корзину, без доставки и оплаты (по умолчанию N; иное значение — 400) |
curl -X POST "https://example.ru/api/sale/order/refresh" \
-H "X-Session-Id: JLfAjGOFZ3qb2elyU2VIxlhvt1kYjQMZ" \
-H "Content-Type: application/json" \
-d '{"personTypeID": 1, "deliveryID": 2, "paymentID": 3, "properties": {"1": "Иван Иванов"}}' Ответ refresh (сокращён):
{
"data": {
"basket": [ { "id": 15, "productId": 105, "name": "Футболка базовая", "quantity": 2, "price": 2000 } ],
"discountList": [],
"order": {
"orderDescription": "",
"personType": [ { "id": 1, "name": "Физическое лицо", "checked": "Y" } ]
},
"locations": []
}
} basket — позиции корзины заказа (как в GET /api/sale/basket), order — полные данные текущего заказа (order.orderProp — значения выбранных свойств), locations — выбранные местоположения (ключ — ID свойства), discountList — применённые скидки. Если компонент оформления вернул ошибки, статус 400 и тело {"errors": [тексты компонента]}.
Оформление
POST /api/sale/order/save принимает то же тело без полей купонов. Ответ:
{
"data": {
"payment": "<a href=\"https://pay.example.ru/p/56\">Оплатить</a>",
"paymentUrl": "https://pay.example.ru/p/56",
"order": {
"id": 56,
"accountNumber": "56",
"personTypeId": 1,
"userId": 12,
"payed": "N",
"canceled": "N",
"statusId": "N",
"priceDelivery": 300,
"price": 4300,
"currency": "RUB",
"paySystemId": 3,
"deliveryId": 2
},
"paysystem": { "id": 3, "name": "Оплата картой" }
}
} payment — HTML формы оплаты (пусто, если оплата не требуется), paymentUrl — ссылка на оплату (null, если у платёжной системы её нет или заказ уже оплачен). После успеха купоны сессии очищаются. Заказ можно оплатить позже — Оплата.
Телефон уже зарегистрирован
При включённой настройке «Требовать авторизацию, если телефон уже зарегистрирован» (Магазин -> «Оформление заказа») и невошедшем покупателе:
- телефон из заказа уже принадлежит другому пользователю: заказ не создаётся, статус 409, витрина открывает вход по SMS (Авторизация и регистрация);
- телефон свободен: пользователь создаётся по телефону и авторизуется, заказ оформляется.
Ответ 409:
{
"success": false,
"code": "PHONE_ALREADY_REGISTERED",
"error": "Пользователь с таким номером телефона уже существует, авторизуйтесь перед тем как оформить заказ"
} При выключенной настройке заказ оформляется штатным компонентом.
История и карточка заказа
GET /api/sale/orderByStatus — страница «Мои заказы»: заказы пользователя постранично (limit, offset, pagen), новые сверху. Параметры: statuses — JSON-массив кодов статусов (обязателен по сигнатуре: если фильтр не нужен, передайте []), searchable_content — поиск по номеру заказа (пустая строка, если не нужен), sort — {"ID":"DESC"} по умолчанию. GET /api/sale/order?orderID=56 — один заказ пользователя; если заказа нет или он чужой, тело {"errors": null}.
В заказе: statusId — код статуса (N — принят, P — оплачен, F — выполнен, C — отменён покупателем, D — отмена действием orderOperation; полный список — GET /api/sale/orderStatus), а не признак «да / нет». Признаки payed, canceled и products[].canBuy — "Y" или "N". Состав: delivery (служба доставки), paySystem (платёжная система), properties (значения свойств заказа), products (позиции; состав карточки element — набор «Корзина и заказ»). У карточки заказа дополнительно sumToPay (сумма неоплаченных платежей) и sumPayedBonus (оплачено внутренним счётом, поле есть, только когда такой платёж оплачен).
{
"data": {
"id": 56,
"accountNumber": "56",
"dateInsert": "17.11.2026 12:00:00",
"payed": "N",
"statusId": "N",
"priceDelivery": 300,
"price": 4300,
"currency": "RUB",
"canceled": "N",
"deliveryId": 2,
"paySystemId": 3,
"sumToPay": 4300,
"products": [
{ "id": 15, "orderId": 56, "productId": 105, "name": "Футболка базовая", "quantity": 2, "price": 2000, "element": { "id": 105, "name": "Футболка базовая" } }
]
}
} Ответ сокращён, полный набор полей — в документации API.
Отмена
POST /api/sale/order/cancelсorderID— «Отменить заказ»: причина «Отменено пользователем», статусC. Только свой заказ: чужой и несуществующий неразличимы — 404. Успех —{"errors": null}.POST /api/sale/orderOperationсorderIDиaction. Поддержаноcancel: статусD; оплаченный или отгруженный заказ покупатель сам не отменяет (400), для любого другогоactionзаказ сохраняется без изменений.
Где настраивается оформление заказа
- Настройки модуля -> вкладка «Магазин»: минимальная сумма заказа, минимальная сумма бесплатной доставки, максимальный вес и плата за перегруз (отдаются в
GET /api/sale, модуль заказ по ним не отклоняет), «Город по умолчанию», «Требовать авторизацию, если телефон уже зарегистрирован». - Состав товаров заказа — набор «Корзина и заказ» (вкладка «Инфоблоки»).
- Типы плательщиков, свойства заказа, статусы, службы доставки и платёжные системы — штатные настройки магазина Битрикса.
- Проект может изменить ответ событием
OnAfterSaleOrderBuild(Контроллеры).
Ограничения заказа
- Ошибки приходят в двух формах:
{errors: [текст]}и{success: false, error: текст}— читайте текст изerrorилиerrors[0]. GET /api/sale/orderByStatus: параметрыstatusesиsearchable_contentобязательны по сигнатуре.