REST: онлайн-продажи и заказы (sale)

Группа sale.* отвечает за онлайн-продажи в Битрикс24: заказы CRM-магазина, позиции корзины, свойства заказа, оплаты и отгрузки, статусы и торговые площадки. Через неё внешний сайт или мобильное приложение создаёт полноценный заказ, который менеджеры ведут в CRM.

Модель данных заказа

Заказ (sale.order) — корневая сущность. К нему привязаны дочерние объекты, каждый со своей группой методов:

Тип плательщика и справочники

Перед созданием заказа выясните доступные типы плательщика и статусы. Тип плательщика (personTypeId) разделяет схемы «физлицо» и «юрлицо» и определяет набор свойств:

• sale.persontype.list — типы плательщиков;
• sale.status.list — статусы заказов и отгрузок;
• sale.paysystem.list — платёжные системы;
• sale.delivery.getlist — службы доставки;
• sale.orderproperty.list — описание свойств заказа для нужного типа плательщика.

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

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

Заказ создаётся методом sale.order.add. Минимально нужны валюта, тип плательщика и хотя бы одна позиция корзины:

sale.order.add { "fields": { "currency": "RUB", "personTypeId": 1, "basketItems": [ { "productId": 240, "quantity": 2, "price": 24990, "currency": "RUB", "name": "Кофемашина Bosch" } ] } }

В ответе — result.order.id, а также вложенные basketItems, shipments и payments с их идентификаторами. Позиции можно передать сразу в sale.order.add или добавлять позже через sale.basketitem.add с orderId. Поле productId позиции ссылается на товар каталога; если товара в каталоге нет, допустимо передать произвольную позицию с именем и ценой, но тогда она не свяжется с остатками и аналитикой каталога. Валюта позиции должна совпадать с валютой заказа, иначе сумма пересчитается некорректно.

Свойства заказа

Контактные данные (ФИО, телефон, адрес, комментарий) хранятся не в самом заказе, а в значениях свойств. Список свойств для типа плательщика даёт sale.orderproperty.list, а значения задаются через sale.propertyvalue.add:

sale.propertyvalue.add { "fields": { "orderId": 1024, "orderPropsId": 5, "value": "+7 900 000-00-00" } }

Оплаты и отгрузки

Финансовую и логистическую части ведут отдельные объекты. Оплата создаётся sale.payment.add с указанием orderId, paySystemId и суммы; факт оплаты — обновлением поля paid в Y. Отгрузка создаётся sale.shipment.add с deliveryId, а состав задаётся sale.shipmentitem.*.

1. оплата: sale.payment.add → отметка paid=Y;
2. отгрузка: sale.shipment.add → наполнение sale.shipmentitem.add → отметка deducted=Y (списание со склада);
3. смена статуса заказа: sale.order.update с полем statusId.

События и синхронизация

Чтобы реагировать на изменения заказа в реальном времени, подпишитесь на события через event.bind. Полезные события группы sale:

• OnSaleOrderSaved — заказ создан или изменён;
• OnSalePaymentEntitySaved — изменение оплаты;
• OnSaleShipmentEntitySaved — изменение отгрузки.

Обработчик получает POST на ваш URL с идентификаторами; в ответ подтяните полные данные через sale.order.get. Это надёжнее периодического опроса и не расходует лимиты на постоянный sale.order.list.

Выборка и фильтрация заказов

Метод sale.order.list поддерживает select, filter, order и постраничный start. В filter работают префиксы операторов: >=, <=, % (подстрока), ! (не равно). Типовые сценарии выгрузки:

• новые заказы за период — фильтр { ">=dateInsert": "2026-07-01" };
• неоплаченные — фильтр по payed равному N;
• заказы в конкретном статусе — фильтр по statusId;
• заказы конкретной торговой площадки — по tradingPlatform.

Для получения дочерних сущностей одним запросом объединяйте sale.order.get, sale.basketitem.list и sale.payment.list в batch. Ответы list-методов содержат total и next для постраничного перебора по 50 элементов. Чтобы не выгружать весь массив ради подсчёта, запрашивайте только select с полем id и берите total из первого ответа.

Итог

Группа sale.* представляет заказ как дерево объектов: сам заказ, корзина, свойства, оплаты и отгрузки. Корректная интеграция начинается со справочников (типы плательщика, статусы, платёжные системы и доставки), затем идёт создание заказа, заполнение штатных свойств и управление оплатой и отгрузкой, а синхронизация статусов держится на событиях, а не на опросе.

Мы связываем внешние сайты и учётные системы с CRM-магазином Битрикс24 так, чтобы заказы, оплаты и отгрузки шли единым потоком без ручного переноса. Если нужен надёжный обмен заказами с сайтом или 1С — поможем спроектировать и внедрить его.