REST: sale.order.add — создание заказа

Метод sale.order.add создаёт заказ в онлайн-магазине Битрикс24. Но сам по себе он лишь «шапка» — товары, свойства, оплата и отгрузка добавляются отдельными методами scope sale. Разберём корректную последовательность создания заказа.

Предусловия: тип плательщика и валюта

Заказ нельзя создать «в пустоте» — ему нужны тип плательщика (personType) и валюта. Тип плательщика определяет набор свойств заказа (физлицо/юрлицо).

• sale.persontype.list — получить доступные типы плательщика и их id;
• sale.order.getFields — узнать полный список полей заказа перед вставкой.

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

Сам метод принимает объект fields. Минимально обязательны personTypeId и currency:

sale.order.add(fields: {personTypeId: 1, currency: "RUB", userId: 12, responsibleId: 5, statusId: "N"})

В ответе придёт объект order с полем id — идентификатор нового заказа для последующих шагов.

Стоит понимать, что созданный на этом шаге заказ имеет нулевую сумму — она пересчитается автоматически, как только вы добавите позиции корзины. Поле userId связывает заказ с покупателем: в CRM-магазине это контакт, в классическом интернет-магазине — пользователь портала. Если покупатель ещё не заведён, его создают заранее (crm.contact.add или user.add) и подставляют полученный ID. Поле responsibleId задаёт ответственного менеджера, что важно для распределения заказов по воронке.

Товары: корзина заказа

Шапка заказа не содержит товаров. Каждую позицию добавляют методом sale.basketitem.add с привязкой к orderId:

sale.basketitem.add(fields: {orderId: 730, productId: 145, quantity: 2, price: 1990, currency: "RUB", name: "Кресло офисное"})

• productId — ID товара из каталога (scope catalog);
• quantity — количество;
• price — можно задать вручную или дать системе взять из каталога.

Для товаров с торговыми предложениями (SKU) в productId передают идентификатор конкретного предложения, а не родительского товара, — иначе в заказ попадёт «пустой» товар без характеристик. Ставку НДС и признаки маркировки задают дополнительными полями позиции, что важно для последующей фискализации чека. Удалить ошибочно добавленную позицию можно методом sale.basketitem.delete, а изменить количество — sale.basketitem.update.

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

Данные покупателя — ФИО, телефон, адрес — это значения свойств заказа. Их набор зависит от personTypeId. Заполняют методом sale.propertyvalue.add:

1. получаем доступные свойства: sale.property.list(filter: {personTypeId: 1});
2. добавляем значение: sale.propertyvalue.add(fields: {orderId: 730, orderPropsId: 8, value: "+7 900 000-00-00"}).

Так заполняются контакты, комментарий, адрес доставки — всё, что настроено для данного типа плательщика.

Идентификатор orderPropsId — это не произвольное имя, а ID конкретного свойства из настроек магазина. Поэтому перед загрузкой заказов один раз выгружают карту свойств для каждого personTypeId и сопоставляют поля внешней системы с ID свойств Битрикс24. Свойства с типом «привязка к местоположению» требуют кода из справочника локаций, а не текстовой строки, — это частая причина, по которой адрес не сохраняется. Обновить уже заполненное значение можно методом sale.propertyvalue.update.

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

Чтобы заказ стал полноценным, к нему добавляют оплату и отгрузку — тоже отдельными методами:

• sale.payment.add — создать оплату (orderId, paySystemId, sum);
• sale.shipment.add — создать отгрузку (orderId, deliveryId);
• sale.payment.update — пометить оплату как проведённую (paid: "Y").

sale.payment.add(fields: {orderId: 730, paySystemId: 3, sum: 3980, currency: "RUB"})

Разделение оплаты и отгрузки на самостоятельные сущности — сильная сторона модели: один заказ может иметь несколько оплат (аванс и доплата) и несколько отгрузок. Идентификаторы paySystemId и deliveryId берут из справочников платёжных систем и служб доставки — их отдают sale.paysystem.list и sale.delivery.getlist. Когда деньги поступили, оплату помечают проведённой через sale.payment.update с paid: "Y", и заказ автоматически двигается по статусам.

Полная последовательность вызовов

Собираем всё в один предсказуемый сценарий. Именно такой порядок избавляет от «пустых» заказов без товаров и свойств:

1. sale.persontype.list — определить personTypeId;
2. sale.order.add — создать шапку, получить orderId;
3. sale.basketitem.add — добавить товары (по одному на позицию);
4. sale.propertyvalue.add — заполнить свойства покупателя;
5. sale.shipment.add и sale.payment.add — доставка и оплата.

Итог

Метод sale.order.add создаёт только каркас заказа — реальный заказ собирается из связки методов scope sale: корзина, свойства, отгрузка и оплата. Ключ к стабильности — соблюдать последовательность, брать orderId из ответа и по возможности использовать batch. Не забудьте про включённый функционал магазина и корректный personTypeId.

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