Современный магазин не остров. Заказ должен уйти в CRM, оплата — в бухгалтерию, статус доставки — прийти от службы, остаток — обновиться со склада, лид — попасть в систему маркетинга. Всё это живёт в разных сервисах, и связывают их две технологии: API и вебхуки. Когда они настроены плохо, данные теряются молча, а об этом узнают от разгневанного клиента, а не из системы.
В этой статье разберём, как связать магазин на 1С-Битрикс со сторонними сервисами через API и вебхуки: чем они отличаются, как использовать REST и события D7, как строить входящие и исходящие интеграции надёжно и безопасно, с повторами, идемпотентностью и мониторингом. Материал опирается на нашу практику поддержки API-обменов и webhook-интеграций.
Коротко
- API — вы обращаетесь к чужому сервису; вебхук — чужой сервис уведомляет вас о событии.
- В Битриксе исходящие вебхуки строят на событиях D7, не выполняя долгих запросов прямо в обработчике.
- Надёжность держится на повторах, идемпотентности и очереди — сеть и чужие сервисы ненадёжны.
- Входящие вебхуки аутентифицируют и валидируют; без этого интеграция становится дырой в безопасности.
Зачем магазину связь со сторонними сервисами
По мере роста магазина вокруг него появляется экосистема сервисов, и каждый решает свою задачу. Ручной перенос данных между ними быстро становится узким местом: менеджеры копируют заказы в CRM, сверяют оплаты, вбивают трек-номера. Интеграции убирают эту рутину и ошибки.
Типичные направления связи:
- CRM. Заказы и лиды уходят в систему продаж автоматически.
- Платёжные сервисы. Статусы оплат приходят вебхуками от эквайринга.
- Службы доставки. Передача заказов и получение трек-номеров и статусов.
- Склад и учёт. Обмен остатками, ценами, документами с 1С.
- Маркетинг. Передача событий в аналитику, рассылки, сервисы удержания.
Общий смысл — данные текут между системами сами, в реальном времени или по расписанию, без ручного переноса. Именно это делает магазин управляемым при росте объёма заказов.
API и вебхуки: в чём разница
Эти два понятия часто путают, хотя разница принципиальна и определяет архитектуру интеграции.
| Критерий | Вызов API (pull) | Вебхук (push) |
|---|---|---|
| Кто инициирует | Вы обращаетесь к сервису | Сервис обращается к вам |
| Когда | Когда вам нужны данные | Когда произошло событие |
| Аналогия | Вы спрашиваете | Вам сообщают |
| Пример | Запросить список ПВЗ у службы | Эквайринг сообщил об оплате |
На практике направления сочетаются. Оплату вы узнаёте вебхуком от эквайринга (push), а детали заказа при необходимости запрашиваете через его API (pull). Понимание, кто инициатор в каждом обмене, — основа проектирования интеграции.
REST и события D7 в Битрикс
В 1С-Битрикс есть два ключевых механизма для интеграций, и важно не путать их роли.
- REST API. Программный интерфейс сайта: через него внешние системы читают и создают данные (товары, заказы) по HTTP. Это входящее направление — кто-то обращается к вам.
- События D7. Внутренний механизм: при изменениях (оформлен заказ, оплачен, изменён товар) запускается ваш обработчик. Это точка, откуда удобно инициировать исходящие вебхуки.
Связка обычно такая: событие D7 ловит изменение внутри сайта и запускает отправку вебхука наружу, а REST API принимает входящие обращения внешних систем. Про то, как устроена система событий и работа с данными на D7, мы подробно пишем в статье про D7 ORM в Битрикс.
Исходящие вебхуки на события
Исходящий вебхук — это когда ваш сайт сам уведомляет внешний сервис о событии. Строят его на событиях D7, но с важной оговоркой: нельзя выполнять долгий HTTP-запрос прямо в обработчике события, иначе пользователь будет ждать ответа стороннего сервиса при оформлении заказа.
Правильная схема отправки:
- Подпишитесь на событие. Обработчик на нужное событие (например, оплата заказа) фиксирует факт.
- Поставьте задачу в очередь. Событие складывается в очередь на отправку, а пользователь не ждёт.
- Отправьте асинхронно. Агент или фоновый обработчик берёт задачу и шлёт вебхук во внешний сервис.
- Обработайте результат. Успех — отметить, ошибка — запланировать повтор.
Входящие вебхуки и API
Входящее направление — когда внешние сервисы обращаются к вашему сайту: эквайринг сообщает об оплате, служба доставки — о смене статуса, CRM — об изменении заказа. Здесь главное правило: не доверять входящим данным.
- Аутентификация. Каждый входящий запрос проверяется: секретный токен, подпись тела, ограничение по IP.
- Валидация. Данные проверяются перед обработкой — как потенциально враждебные.
- Быстрый ответ. На вебхук отвечают быстро (приняли), а тяжёлую обработку выносят в фон.
- Идемпотентная обработка. Повторная доставка того же события не должна ломать данные.
Открытый вход без проверки подписи — прямая уязвимость: через него можно подделать оплату или заказ. Тему безопасности входящих обращений мы подробно разбираем в статье про REST, вебхуки и безопасность в Битрикс.
Надёжность: повторы и идемпотентность
Главная иллюзия начинающих интеграций — что сеть и чужие сервисы всегда доступны. На деле запросы теряются, случаются таймауты, сервисы падают. Интеграция обязана переживать это без потери данных.
- Повторы с задержкой. Не доставилось — повторить через нарастающие интервалы, а не бесконечно долбить сразу.
- Идемпотентность. Повторная доставка события не должна создавать дубль — проверяют по уникальному идентификатору события.
- Очередь необработанных. События, которые пока не удалось доставить, хранятся и повторяются, а не исчезают.
- Логирование попыток. Каждая попытка фиксируется — видно, что и почему не прошло.
Без идемпотентности повтор доставки «заказ оплачен» может создать вторую отгрузку или списать бонусы дважды. Поэтому её закладывают с самого начала, а не прикручивают после первого инцидента с дублями.
Безопасность интеграций
Интеграции — это дополнительные двери в систему, и каждую нужно запирать. Безопасность здесь не опция, а условие.
- Только HTTPS. Данные в обмене шифруются в транспорте.
- Минимальные права токенов. Токен обмена умеет ровно то, что нужно интеграции, и не больше.
- Безопасное хранение секретов. Ключи и токены не лежат в коде и репозитории, а хранятся защищённо.
- Подпись и проверка. Входящие вебхуки проверяются по подписи, исходящие — подписываются.
- Ротация ключей. Секреты периодически меняют, скомпрометированные отзывают.
Слабое звено интеграции быстро становится слабым звеном всего сайта: через открытый вебхук или утёкший токен можно испортить данные или получить доступ. Поэтому безопасность обмена проектируют наравне с функциональностью.
Онлайн или пакетный обмен
Не всё нужно синхронизировать в реальном времени — выбор между онлайн и пакетным обменом определяется задачей.
| Подход | Когда уместен | Пример |
|---|---|---|
| Онлайн (вебхуки) | Важна оперативность | Статусы оплат, срочные остатки |
| Пакетный (по расписанию) | Большие объёмы, секунды не критичны | Ночная выгрузка каталога, сверка |
| Гибрид | База пакетом, срочное — онлайн | CommerceML с 1С + вебхуки на события |
Частая рабочая схема — гибрид: базовый обмен каталогом и заказами идёт пакетно (например, CommerceML с 1С), а срочные события вроде оплаты доставляются вебхуками. Так система остаётся и надёжной на объёме, и оперативной там, где это важно.
Мониторинг и отладка
Интеграции ломаются тихо — в отличие от упавшего сайта, сбой обмена не виден пользователю сразу. Поэтому мониторинг для них обязателен.
- Журнал обменов. Что отправлено и получено, коды ответов, ошибки, повторы.
- Алерты. Уведомления на рост ошибок и застрявшую очередь событий.
- Тестовые приёмники. Для отладки исходящих вебхуков — приёмник, показывающий сырой запрос.
- Логирование входящих. Сырые входящие запросы сохраняются для разбора инцидентов.
Без мониторинга о сбое узнают от клиента, у которого «оплата прошла, а заказ не оформился», — и это всегда дороже, чем поймать проблему по алерту. Надёжность обмена сильно зависит и от окружения: про инфраструктуру мы пишем в статье про хостинг и инфраструктуру BitrixVM.
Типичные сценарии интеграций
Чтобы теория стала практикой, вот частые связки, которые встречаются почти в каждом магазине:
- Оплата. Эквайринг присылает вебхук о статусе оплаты, заказ переходит в оплаченный, событие уходит дальше в учёт.
- Доставка. Заказ передаётся в службу по API, трек и статусы возвращаются вебхуками.
- CRM. Новый заказ или лид исходящим вебхуком уходит в CRM, обновления возвращаются обратно.
- 1С. Каталог, цены и остатки — пакетным обменом, срочные события — онлайн.
Каждый сценарий — это комбинация направлений (API и вебхуки), надёжности (повторы, идемпотентность) и безопасности. Собранные по единым принципам, они образуют устойчивую экосистему вокруг магазина.
Частые ошибки
- Синхронная отправка в обработчике. Вебхук шлётся прямо в событии, тормозя оформление заказа.
- Нет повторов. Первый же сбой сети теряет данные навсегда.
- Нет идемпотентности. Повторная доставка создаёт дубли заказов и списаний.
- Открытый вход. Входящий вебхук без проверки подписи — подделать оплату элементарно.
- Секреты в коде. Токены лежат в репозитории и утекают.
- Всё онлайн. Большие объёмы гонят вебхуками там, где хватило бы пакетного обмена.
- Нет мониторинга. Сбои обмена всплывают через жалобы клиентов, а не через алерты.
Чек-лист интеграции
- Направления определены. Ясно, где API (pull), где вебхуки (push) и кто инициатор.
- События настроены. Обработчики D7 на нужные события ставят отправку в фон.
- Отправка асинхронна. Долгие запросы не блокируют пользователя.
- Надёжность заложена. Повторы с задержкой, идемпотентность, очередь необработанных.
- Вход защищён. Аутентификация, подпись, валидация входящих запросов, HTTPS.
- Секреты в безопасности. Минимальные права токенов, безопасное хранение, ротация.
- Обмен спроектирован. Онлайн и пакет распределены по задачам осознанно.
- Мониторинг работает. Журнал обменов, алерты на ошибки и очередь.
Вывод
API и вебхуки — это нервная система магазина, по которой данные текут между сайтом, учётом, платежами, доставкой и CRM. На 1С-Битрикс исходящие интеграции строят на событиях D7 с асинхронной отправкой, входящие принимают через REST с обязательной аутентификацией, а надёжность держат на повторах и идемпотентности.
Ключевое — относиться к интеграциям как к инженерной системе, а не к «скрипту, который отправляет запрос»: закладывать отказоустойчивость, безопасность и мониторинг с самого начала. Тогда данные не теряются, а сбои ловятся раньше клиентов. Если нужно настроить и сопровождать такие интеграции надёжно, доверьте это поддержке API-обменов и webhook-интеграций от команды, которая делает это ежедневно.
