WooCommerce и Битрикс24: передача заказов, клиентов и статусов через API

Когда WooCommerce-магазин начинает получать стабильный поток заказов, ручная передача данных в CRM быстро превращается в источник ошибок: менеджеры создают дубли, забывают обновлять статусы, теряют комментарии и не всегда понимают, какой заказ на сайте соответствует какой сделке в CRM.

Эта статья полезна владельцам интернет-магазинов и разработчикам, которым нужна именно интеграция WooCommerce с Битрикс24: передавать заказы и клиентов, связывать заказ со сделкой, учитывать повторные события и безопасно синхронизировать статусы.

Ниже разберём рабочую архитектуру без привязки к конкретному коммерческому плагину: WooCommerce REST API и webhooks на стороне магазина, актуальные универсальные методы crm.item.* на стороне Битрикс24, таблица соответствий ID, защита от дублей и журналирование.

Чем эта задача отличается от обычной формы WordPress → CRM

Форма обратной связи обычно передаёт небольшой набор полей один раз: имя, телефон, email, сообщение и источник. У заказа WooCommerce жизненный цикл сложнее. Он может менять статус, состав, способ доставки, оплату, скидку, адрес и пользовательские поля.

Кроме этого, одно событие может прийти повторно. Webhook может быть повторно доставлен после сетевой ошибки, администратор может повторно сохранить заказ, а интеграционный сервис — повторить запрос после таймаута. Поэтому для интернет-магазина недостаточно «при каждом событии создать сделку».

Какие API использовать

WooCommerce: REST API и webhooks

WooCommerce REST API позволяет читать и изменять заказы, клиентов и другие сущности магазина. Для событийной синхронизации удобнее webhooks: WooCommerce может отправить уведомление, когда заказ создан или обновлён.

Для webhooks доступны события вроде order.created и order.updated. WooCommerce также передаёт заголовок X-WC-Webhook-Signature — HMAC-SHA256 подпись тела запроса, которую принимающая сторона может проверить с помощью secret webhook.

REST API полезен как второй канал: например, для первичной миграции, повторной сверки, восстановления пропущенных событий и ручной диагностики конкретного заказа.

Битрикс24: универсальные методы crm.item.*

В актуальной документации Битрикс24 для новой разработки рекомендуется использовать универсальные методы crm.item.*. Системные типы имеют числовые entityTypeId: сделка — 2, контакт — 3, компания — 4.

Это важный момент для нового проекта: старые группы методов crm.deal.* и crm.contact.* продолжают работать в существующих интеграциях, но их развитие прекращено. Поэтому новый обмен лучше строить на crm.item.add, crm.item.list, crm.item.get и crm.item.update.

Какие данные передавать из заказа

Не стоит отправлять в CRM весь JSON заказа без разбора. Лучше заранее определить минимальный контракт данных и только затем добавлять дополнительные поля.

• order_id — внутренний ID заказа WooCommerce;
• order_number — отображаемый номер заказа;
• status — текущий статус;
• total и currency — итог и валюта;
• billing name / phone / email — данные клиента;
• line_items — товары, количество, SKU и суммы;
• shipping method — способ доставки;
• payment method — способ оплаты;
• customer note — комментарий клиента;
• UTM / source metadata — только если магазин действительно их сохраняет.

Если в магазине используются ACF, Checkout Field Editor или собственные поля заказа, их нужно добавить в карту данных отдельно. Не следует рассчитывать, что стороннее поле автоматически попадёт в CRM.

Шаг 1. Создаём webhook WooCommerce

В админке WooCommerce webhook настраивается в разделе WooCommerce → Настройки → Дополнительно → Webhooks. Для первой версии интеграции обычно достаточно двух тем:

• order.created — первичное создание сделки;
• order.updated — обновление уже существующей сделки.

Delivery URL должен вести не напрямую в Битрикс24, а в ваш интеграционный endpoint. Именно он проверяет подпись, преобразует структуру WooCommerce, выполняет поиск соответствий и только после этого вызывает REST API CRM.

POST https://example.com/integrations/woocommerce/bitrix24

X-WC-Webhook-Topic: order.updated
X-WC-Webhook-Signature: BASE64_HMAC_SHA256
Content-Type: application/json

Шаг 2. Проверяем подпись webhook

Принимающая сторона должна вычислить HMAC-SHA256 от исходного тела запроса с тем же secret и сравнить результат с X-WC-Webhook-Signature. Сравнение лучше делать функцией, устойчивой к timing attack.

<?php
$rawBody   = file_get_contents('php://input');
$signature = $_SERVER['HTTP_X_WC_WEBHOOK_SIGNATURE'] ?? '';
$secret    = getenv('WOOCOMMERCE_WEBHOOK_SECRET');

$expected = base64_encode(
    hash_hmac('sha256', $rawBody, $secret, true)
);

if (!hash_equals($expected, $signature)) {
    http_response_code(401);
    exit('Invalid signature');
}

Не храните secret в публичном JavaScript, HTML страницы или в JSON статьи. В рабочем проекте это должна быть серверная переменная окружения, секрет хостинга или другая закрытая конфигурация.

Шаг 3. Вводим idempotency и таблицу соответствий

Для каждого заказа нужно хранить связь:

woocommerce_order_id = 12345
bitrix24_deal_id     = 67890
last_event_hash      = ...
last_synced_at       = ...
sync_status          = success

Хранилищем может быть отдельная таблица WordPress, собственная база интеграционного сервиса или надёжное key-value хранилище. Для небольшой интеграции допустимо использовать метаданные заказа, но отдельная таблица удобнее для журналирования и поиска проблем.

Алгоритм обработки события:

1. проверить подпись;
2. получить WooCommerce order ID;
3. найти сохранённый Bitrix24 deal ID;
4. если связи нет — создать контакт при необходимости и затем сделку;
5. сохранить соответствие ID;
6. если связь уже есть — выполнить update, а не add;
7. записать результат и код ответа API.

Шаг 4. Создаём сделку в Битрикс24

Для новой интеграции сделку можно создать через crm.item.add с entityTypeId = 2. Перед реализацией стоит получить доступные поля через crm.item.fields и список воронок/стадий для конкретного портала.

POST WEBHOOK_URL/crm.item.add.json
Content-Type: application/json

{
  "entityTypeId": 2,
  "fields": {
    "title": "Заказ WooCommerce #12345",
    "opportunity": 12900,
    "currencyId": "RUB",
    "contactIds": [321],
    "comments": "Заказ создан в интернет-магазине"
  }
}

Значения categoryId и stageId нельзя бездумно копировать из примера. Они зависят от конкретной конфигурации CRM. Сначала нужно получить реальные воронки и стадии портала, затем зафиксировать карту соответствий.

Шаг 5. Не создаём дубли клиентов

Один и тот же покупатель может оформить несколько заказов. Поэтому контакт нельзя создавать каждый раз заново.

Практический порядок:

1. если WooCommerce customer ID уже связан с Bitrix24 contact ID — использовать сохранённую связь;
2. если связи нет — выполнить поиск в CRM по нормализованному телефону и/или email;
3. если найден один подходящий контакт — связать его с новым заказом;
4. если совпадения неоднозначны — не объединять записи автоматически без дополнительного правила;
5. если контакт не найден — создать новый и сохранить соответствие.

Телефон перед сравнением полезно нормализовать: убрать пробелы, скобки и дефисы, привести к согласованному международному формату. Email — привести к нижнему регистру и убрать случайные пробелы.

Шаг 6. Передаём товары заказа

Есть два распространённых подхода.

Вариант 1. Сохранять состав заказа текстом

Подходит для простых процессов, когда CRM нужна менеджерам как карточка заказа, а товарный каталог ведётся только в WooCommerce. В комментарий или пользовательское поле сделки передаётся список:

SKU-001 — Фильтр — 2 × 1 500 ₽
SKU-017 — Картридж — 1 × 900 ₽

Плюсы — проще внедрение и меньше точек отказа. Минус — товары не становятся полноценными товарными позициями сделки.

Вариант 2. Синхронизировать товарные позиции

Если Битрикс24 используется для расчётов, аналитики или документов, товары можно привязывать к сделке отдельными REST-методами товарных позиций. Тогда заранее нужно решить, чем связываются каталоги: SKU, внешний ID или отдельная таблица соответствий.

SKU обычно удобнее числового ID WooCommerce, потому что внутренние ID отличаются между сайтами и средами. Но использовать SKU можно только если он действительно уникален и поддерживается в порядке.

Шаг 7. Настраиваем карту статусов

Статусы WooCommerce и стадии Битрикс24 — разные сущности. Их не нужно синхронизировать по названию. Создайте явную карту.

Конкретные stage ID нужно получать из самого Битрикс24. В новой интеграции лучше не хардкодить чужие значения из документации или примеров.

Односторонняя или двусторонняя синхронизация

Односторонняя: WooCommerce → Битрикс24

Самый надёжный стартовый вариант. Магазин остаётся источником истины по заказам, оплате и составу. CRM получает копию нужных данных для работы менеджеров.

Такой вариант подходит, если менеджеры не должны менять статус заказа из CRM.

Двусторонняя: WooCommerce ↔ Битрикс24

Нужна, когда стадия сделки должна менять заказ на сайте или когда CRM управляет частью исполнения. Здесь появляются дополнительные риски:

• циклы синхронизации;
• конфликты одновременных изменений;
• неоднозначные соответствия статусов;
• повторные webhooks;
• необходимость определять источник изменения.

Для двусторонней схемы добавьте поле last_sync_source или аналогичную метку и не отправляйте обратно изменение, которое только что пришло из второй системы.

Что делать, если webhook потерялся

Интеграция не должна целиком зависеть от единственной доставки webhook. Полезно иметь сверочный процесс:

1. раз в заданный интервал получать изменённые заказы через WooCommerce REST API;
2. сравнивать их с таблицей соответствий;
3. повторно отправлять только отсутствующие или ошибочные записи;
4. не создавать вторую сделку, если связь уже существует.

Это особенно полезно после временного сбоя CRM, хостинга или сетевого маршрута.

Логи, которые реально помогают при поддержке

Не нужно записывать в лог все персональные данные клиента. Для диагностики достаточно технических идентификаторов и результата:

event_id
woocommerce_order_id
bitrix24_deal_id
topic
attempt
http_status
result
error_code
created_at

Телефон, email и полный адрес лучше не дублировать в логах без необходимости. Это уменьшает объём чувствительных данных и упрощает поддержку.

Безопасность интеграции

• проверяйте HMAC-подпись WooCommerce webhook;
• храните ключи REST и incoming webhook Bitrix24 только на сервере;
• используйте HTTPS;
• не помещайте токены в GitHub, HTML, клиентский JavaScript или журналы;
• ограничивайте права интеграции только нужными CRM-операциями;
• проверяйте входные типы, суммы и идентификаторы;
• для retry используйте ограниченное число попыток и backoff;
• не создавайте новый объект после таймаута, пока не проверили, не был ли предыдущий запрос фактически выполнен.

Когда готовый коннектор подходит лучше кастомной интеграции

Готовый плагин или сервис автоматизации разумно выбрать, если процесс стандартный: один магазин, одна воронка, простая передача заказов и нет сложной логики по товарам, складам и статусам.

Кастомная интеграция оправдана, когда есть несколько воронок, нестандартные поля checkout, собственная логика статусов, необходимость связывать товарные каталоги, сложное предотвращение дублей или обмен должен работать независимо от SaaS-посредника.

Когда лучше сначала доработать сам WooCommerce

Если в магазине уже есть проблемы с заказами, HPOS, кастомными полями или webhook-доставкой, сначала лучше привести WooCommerce в предсказуемое состояние. Интеграция не исправит хаотичную модель данных — она только быстрее перенесёт хаос в CRM.

Для таких задач можно начать с доработки WordPress или отдельной доработки WooCommerce, а затем подключать CRM.

Когда это решение подходит

• магазин на WooCommerce уже принимает реальные заказы;
• менеджеры работают в Битрикс24;
• нужно автоматически создавать сделки из заказов;
• нужно видеть клиента, сумму и состав заказа в CRM;
• важна защита от дублей и повторной доставки событий;
• нужна расширяемая архитектура без привязки к одной теме WordPress.

Когда лучше выбрать другой вариант

• если заказов мало и CRM не участвует в процессе — автоматизация может быть избыточной;
• если нужны только уведомления менеджеру — иногда достаточно Telegram или email;
• если бизнес-процесс полностью стандартный — готовый коннектор может быть дешевле поддержки кастомного кода;
• если CRM должна стать главным источником товаров, цен и остатков — проект уже ближе к полноценной ERP/CRM-синхронизации и требует отдельной архитектуры.

Официальные источники

• WooCommerce REST API: Orders
• WooCommerce: работа с webhooks
• WooCommerce REST API: Webhooks
• Bitrix24: универсальные методы CRM
• Bitrix24: сделки CRM
• Bitrix24: контакты CRM

Вывод

Надёжная интеграция WooCommerce с Битрикс24 — это не один запрос «создать сделку». Нужна архитектура, которая понимает жизненный цикл заказа, умеет искать существующего клиента, хранит соответствия ID, проверяет подпись webhook и безопасно переживает повторные события.

Если нужна интеграция под конкретный магазин, можно начать с аудита текущего WooCommerce и бизнес-процесса CRM. Для реализации доступны направления интеграции CRM с сайтом, разработка WordPress-плагинов и обсуждение задачи.