REST: оплата и доставка через REST

REST API Битрикс24 позволяет подключить внешнюю платёжную систему и службу доставки как обработчик приложения — без модуля на сервере портала. Логика оплаты и расчёта доставки живёт на вашей стороне, а Битрикс24 вызывает её через события REST. Это ключевой механизм для интеграции эквайринга, агрегаторов и логистики.

Как работают REST-обработчики

Обычная платёжная система или доставка в Битрикс24 — это серверный обработчик. Через REST его роль берёт на себя приложение: вы регистрируете REST-обработчик, описываете его поля настроек, а бизнес-логику (создать платёж, рассчитать доставку) выполняете у себя, отвечая на события портала.

• sale.paysystem.handler.* — обработчики платёжных систем;
• sale.delivery.handler.* — обработчики служб доставки;
• sale.paysystem.* и sale.delivery.* — сами подключённые платёжные системы и службы.

Регистрация платёжного обработчика

Обработчик описывается методом sale.paysystem.handler.add. В SETTINGS задаются поля формы (ключи API, идентификатор магазина), а также URL обработчика, куда портал шлёт события:

sale.paysystem.handler.add { "CODE": "my_acquiring", "NAME": "Моя касса", "SORT": 100, "SETTINGS": { "URL": { "TYPE": "STRING" }, "HANDLER": "https://app.example.com/pay/" } }

После регистрации создаётся платёжная система через sale.paysystem.add с указанием этого обработчика. Настройки конкретной подключённой системы читаются и обновляются через sale.paysystem.settings.get и .update. В CODES обработчика описывают, какие данные заказа передавать в платёж: сумма, валюта, номер заказа, email и телефон плательщика. Эти значения приходят в событие оплаты уже подставленными, что упрощает формирование запроса к эквайрингу.

Событие инициации оплаты

Когда покупатель нажимает «Оплатить», Битрикс24 вызывает событие инициации оплаты для REST-обработчика. Приложение получает данные платежа и возвращает HTML-форму или ссылку на страницу оплаты.

1. покупатель инициирует оплату — портал шлёт событие на ваш HANDLER;
2. приложение создаёт платёж на стороне эквайринга и возвращает URL или форму;
3. после оплаты ваш сервер отмечает платёж: sale.payment.update с paid=Y.

Обработчик доставки и расчёт

Служба доставки регистрируется через sale.delivery.handler.add, а конкретная служба — через sale.delivery.add. Обработчик может рассчитывать стоимость динамически: при оформлении заказа портал вызывает событие расчёта, передавая вес, габариты и адрес.

В ответ на событие расчёта приложение возвращает стоимость, срок и статус доступности. Так подключают тарифы курьерских служб и пунктов выдачи. Если для адреса доставка недоступна (нет ПВЗ, превышен вес), верните признак недоступности — Битрикс24 скроет способ доставки на оформлении заказа. Кешируйте тарифы на своей стороне: событие расчёта вызывается часто, а внешние API логистов имеют собственные лимиты и задержки, из-за которых оформление заказа может подтормаживать.

Заявки на доставку

Для служб, которым нужно передавать отправления (курьерка, ПВЗ), используется механизм заявок sale.delivery.request.*. Он позволяет из карточки заказа формировать заявку, получать статусы и трек-номера:

• создание заявки на отгрузку в службу;
• обновление статусов доставки в отгрузке заказа;
• возврат трек-номера покупателю.

Логика заявки описывается в конфигурации обработчика доставки: какие действия доступны (создать, отменить, распечатать этикетку) и какие поля собирает менеджер. Когда сотрудник в CRM нажимает «Отправить в службу», портал вызывает соответствующее действие вашего обработчика, а приложение обращается к API курьерской службы и возвращает результат.

Статусы удобно синхронизировать событиями отгрузки (OnSaleShipmentEntitySaved), а при смене состояния — обновлять заказ через sale.shipment.update. Трек-номер обычно кладут в отдельное свойство отгрузки, чтобы он был виден и в CRM, и в уведомлениях покупателю.

Справочники и привязка к заказу

Перед созданием оплаты или отгрузки получите доступные системы и службы:

• sale.paysystem.list — подключённые платёжные системы (нужен paySystemId для sale.payment.add);
• sale.delivery.getlist — службы доставки (deliveryId для sale.shipment.add);
• sale.paysystem.settings.getsettings — метаданные полей обработчика.

Оплата и отгрузка создаются в контексте заказа: sale.payment.add и sale.shipment.add с orderId. Так внешняя оплата и доставка становятся частью заказа CRM-магазина. Идентификаторы обработчиков и подключённых систем стабильны в пределах портала, поэтому в интеграции их удобно сопоставлять с внутренними кодами вашего эквайринга и логиста один раз при установке приложения.

Итог

REST-обработчики позволяют подключить любой эквайринг и любую логистику к Битрикс24 без модуля на сервере портала: платёжные системы через sale.paysystem.handler.*, службы доставки через sale.delivery.handler.*, а бизнес-логика живёт в приложении и вызывается событиями. Важно проверять подписи платёжных колбэков, корректно отмечать оплату и синхронизировать статусы отгрузок.

Мы разрабатываем такие интеграции: подключаем платёжные шлюзы и курьерские службы, настраиваем расчёт тарифов и обмен статусами, автоматизируем сценарии оплаты и доставки. Если нужно подключить свой эквайринг или логистику к Битрикс24 — поможем сделать это надёжно.