Когда интернет-магазин растёт, ручное копирование заказов, клиентов и остатков из WooCommerce в CRM или другие сервисы быстро становится источником ошибок. Для таких задач WooCommerce предоставляет REST API, а webhooks позволяют реагировать на события магазина почти сразу после их возникновения.
Материал полезен владельцам магазинов, разработчикам и интеграторам, которым нужно связать WooCommerce с CRM, учётной системой, таблицами, Make, n8n или собственным backend без правки ядра WordPress.
Ниже — практическая архитектура: какие данные передавать через API, где использовать webhook, как не создавать дубли, как хранить состояние интеграции и что проверить перед запуском.
Что даёт WooCommerce REST API
Актуальная REST API-интеграция WooCommerce работает поверх WordPress REST API. Через неё внешняя система может читать и изменять данные магазина в JSON-формате: например, получать заказы, работать с товарами и использовать другие доступные ресурсы. В текущей документации WooCommerce основной веткой для интеграции указана wc/v3.
Практически это означает, что CRM или промежуточный сервис не обязаны напрямую работать с базой WordPress. Они обращаются к публичным API-маршрутам и получают структурированный ответ.
Архитектура решения
- WooCommerceЗаказы, товары, клиенты и статусы
- WebhookСигнал о создании или изменении объекта
- ОбработкаПроверка, нормализация и маршрутизация данных
- СостояниеСвязка ID и журнал обработанных событий
- CRM/APIСоздание или обновление сущности во внешней системе
Главный принцип: webhook сообщает, что произошло событие, а REST API используется там, где нужно запросить или изменить актуальные данные.
REST API и webhook решают разные задачи
REST API удобно использовать по запросу: получить заказ по ID, прочитать список товаров, обновить объект или сверить состояние. Webhook работает наоборот — WooCommerce сам отправляет уведомление на заданный URL, когда происходит выбранное событие.
Для интеграции магазина с CRM часто полезна комбинация обоих механизмов. Например, webhook сообщает о новом заказе, обработчик принимает событие, а при необходимости дополнительно запрашивает заказ через REST API перед передачей в CRM.
| Механизм | Когда использовать | Типичный пример |
|---|---|---|
| REST API | Нужно получить или изменить данные по запросу | Загрузить заказ, обновить товар, синхронизировать каталог |
| Webhook | Нужно отреагировать на событие | Передать новый заказ в CRM |
| REST API + webhook | Нужна событийная обработка с проверкой актуального состояния | Webhook запускает сценарий, API подтверждает данные перед записью |
Пошаговая настройка интеграции
1. Определите источник истины
До настройки API важно решить, где хранится основное состояние каждой сущности. Если цены и остатки редактируются в WooCommerce, внешняя система не должна самопроизвольно перезаписывать их своими значениями. Если главным источником является ERP, направление синхронизации будет обратным.
Для каждой сущности полезно зафиксировать правило отдельно: товары, остатки, цены, клиенты, заказы и статусы могут иметь разные источники истины.
2. Создайте API-ключ с минимально необходимыми правами
Ключи WooCommerce создаются в разделе WooCommerce → Настройки → Дополнительно → REST API. Права ключа могут быть Read, Write или Read/Write и зависят от пользователя WordPress, для которого создан ключ.
Если интеграции нужно только читать заказы, не стоит выдавать запись. Для двусторонней синхронизации требуются права на изменение конкретных ресурсов.
3. Используйте HTTPS и не храните секреты в сценарии
Внешние credentials должны храниться в менеджере секретов, защищённых credentials n8n/Make, переменных окружения или другом закрытом хранилище. Их не следует вставлять в HTML, публичный JavaScript, GitHub-репозиторий, Google Sheets или логи.
Для запросов к WooCommerce по HTTPS документация поддерживает HTTP Basic Auth с REST API credentials. Сам секрет показывается при создании ключа, поэтому его нужно сохранить сразу в безопасном месте.
4. Настройте webhook для событий, которые действительно нужны
WooCommerce позволяет создавать webhooks для событий заказов, товаров, клиентов и других объектов. Не стоит отправлять все события подряд, если бизнес-сценарию нужен только новый заказ или изменение статуса.
При создании webhook задаются topic, Delivery URL и secret. Secret используется для формирования подписи запроса, которую принимающая сторона может проверять перед обработкой payload.
5. Приведите данные к внутреннему формату
Не передавайте payload WooCommerce напрямую во все внешние сервисы. Между источником и CRM полезно иметь нормализованный объект с теми полями, которые реально нужны бизнес-процессу.
| Поле | Назначение | Пример значения |
|---|---|---|
| source | Источник события | woocommerce |
| source_id | ID объекта в WooCommerce | 12345 |
| event | Тип события | order.created |
| status | Текущий статус | processing |
| external_id | ID объекта во внешней системе | CRM-987 |
| processed_at | Время успешной обработки | ISO 8601 |
Пример безопасного API-запроса
Ниже показана только структура запроса. Значение EXAMPLE_TOKEN — заглушка, а не реальный credential.
curl --request GET 'https://example.com/wp-json/wc/v3/orders/12345' --header 'Authorization: Basic EXAMPLE_TOKEN' --header 'Accept: application/json'В рабочей интеграции токен не должен находиться в исходном коде. Сценарий получает его из защищённого хранилища во время выполнения.
Как защититься от дублей заказов
Webhook нельзя считать гарантией однократной доставки бизнес-операции. Сетевые повторы, повторный запуск сценария или ручное переотправление события могут привести к повторной обработке. Поэтому интеграция должна быть идемпотентной.
Простой вариант — хранить соответствие WooCommerce order ID → CRM entity ID. Перед созданием новой сделки обработчик проверяет таблицу соответствий. Если внешний ID уже известен, выполняется обновление вместо повторного создания.
Для сложных сценариев дополнительно хранят идентификатор события или собственный idempotency key, статус обработки и время последней успешной синхронизации.
Обработка ошибок и повторные попытки
Интеграция не должна молча терять заказы при временной ошибке CRM. Ошибки полезно разделять как минимум на повторяемые и неповторяемые.
- 401/403: проверить credentials, пользователя и права API.
- 404: проверить endpoint, ID объекта и структуру URL.
- 429: уменьшить частоту запросов и использовать задержку перед повтором.
- 5xx: записать событие в очередь повторной обработки, а не создавать новый объект вслепую.
- Ошибка валидации CRM: сохранить payload и конкретную причину, чтобы исправить данные без повторного заказа.
WooCommerce также ведёт логи доставки webhooks, поэтому при диагностике стоит смотреть не только внешний обработчик, но и журнал отправки на стороне магазина.
Когда интеграция через REST API подходит
Этот вариант хорошо подходит, если у сервиса есть API, требуется контролировать структуру данных и важно сохранять связь между объектами. Особенно удобно, когда магазин должен обмениваться заказами, товарами или статусами с CRM, ERP, складом или собственным backend.
Если требуется интеграция CRM с сайтом, такую схему можно расширить очередью, журналом ошибок и правилами маршрутизации заявок. Для более широких сценариев полезна автоматизация бизнес-процессов.
Когда лучше выбрать другой вариант
REST API не всегда нужен напрямую. Если требуется один простой сценарий без сложного состояния, задачу иногда быстрее собрать в Make, Albato или n8n. Если же синхронизация критична, включает большой каталог, двусторонние обновления и строгий контроль ошибок, лучше выделить отдельный интеграционный слой.
Для самого магазина важно сначала привести в порядок каталог, оформление заказа и базовые сценарии. Подробнее об этом — на странице разработки WooCommerce-магазинов.
Безопасность интеграции
- используйте HTTPS для API и webhook endpoints;
- выдавайте ключу только необходимые права;
- не храните API credentials в репозитории и клиентском JavaScript;
- проверяйте подпись входящих webhook-запросов;
- логируйте технические ID и код ошибки, но не секреты;
- предусмотрите отзыв и замену ключа без остановки всей системы.
Чек-лист перед запуском
- Определён источник истины для товаров, заказов, остатков и статусов
- API-ключ создан с минимально необходимыми правами
- Webhook отправляется только на HTTPS endpoint и его подпись проверяется
- Связка WooCommerce ID и external ID сохраняется отдельно
- Повторное событие не создаёт дубль заказа или клиента
- Ошибки 429 и 5xx попадают в повторную обработку
- В логах и коде нет API-ключей и других credentials
Частые вопросы
Можно ли передавать новые заказы WooCommerce в CRM автоматически?
Да. Обычно webhook сообщает о новом заказе, после чего обработчик создаёт или обновляет сущность в CRM и сохраняет соответствие ID.
Что лучше для заказов: REST API или webhook?
Для реакции на событие удобнее webhook. REST API нужен, когда система сама запрашивает или изменяет данные. В надёжной интеграции их часто используют вместе.
Как не создавать одну сделку в CRM дважды?
Хранить связь WooCommerce order ID с ID сделки в CRM и перед созданием проверять, обрабатывался ли этот заказ ранее.
Можно ли синхронизировать товары и остатки?
Да, если заранее определить источник истины и правила обновления. Для каталога особенно важно не допустить циклической синхронизации между двумя системами.
Где хранить Consumer Key и Consumer Secret?
В защищённых credentials сервиса автоматизации, менеджере секретов или переменных окружения. Не в таблицах, публичном коде или репозитории.
Что делать, если webhook временно не доставлен?
Проверить журнал webhook в WooCommerce, ответ принимающего endpoint и настроить безопасные повторные попытки без повторного создания бизнес-объекта.
Нужен ли отдельный сервер для интеграции?
Не всегда. Простые сценарии можно выполнять в сервисах автоматизации или serverless-обработчике. Отдельный backend оправдан, когда нужны очереди, сложное состояние, высокий контроль и собственная логика.
Вывод
WooCommerce REST API лучше воспринимать не как «способ отправить заказ», а как контракт между магазином и внешней системой. Webhooks дают событийный запуск, API — управляемый доступ к данным, а таблица соответствий и идемпотентность защищают бизнес-процесс от дублей.
Если требуется спроектировать такую интеграцию под конкретную CRM или учётную систему, можно описать текущую схему через форму связи A.S Groups: какие данные создаются в WooCommerce, куда их нужно передавать и что должно происходить при ошибке.
Обсуждение
Вопросы и комментарии
Можно уточнить детали статьи или поделиться своим опытом. Первый комментарий проходит проверку.