WooCommerce Store API vs REST API: что выбрать для интеграции магазина

У WooCommerce есть два REST-интерфейса, которые легко перепутать по названию: Store API и классический WooCommerce REST API. Оба работают через HTTP и возвращают JSON, но предназначены для разных частей магазина. Ошибка в выборе API обычно приводит либо к лишней авторизации на клиенте, либо к попытке использовать публичный интерфейс там, где нужен административный доступ.

Материал полезен разработчикам, владельцам WooCommerce-магазинов и тем, кто планирует headless-витрину, мобильный интерфейс, CRM, ERP или собственную автоматизацию. После прочтения будет понятно, какой API использовать для каталога и корзины, какой — для заказов и управления товарами, а когда разумно применять оба одновременно.

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

Короткий ответ: чем Store API отличается от REST API WooCommerce

Что такое WooCommerce Store API

Store API — публичный REST-интерфейс WooCommerce для клиентской части магазина. В официальной документации он описан как API для customer-facing функций: получения товаров, работы с корзиной, расчёта доставки и оформления заказа. Основной namespace — wc/store/v1.

Простейший запрос каталога не требует API-ключа:

curl "https://example.com/wp-json/wc/store/v1/products"

Это удобно для headless-витрины, отдельного фронтенда или интерфейса, которому нужно показывать покупателю доступные товары, цены, изображения, категории и другие опубликованные данные без размещения административных credentials в браузере.

Что Store API умеет хорошо

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

При этом Store API специально ограничен. Он не предназначен для чтения произвольного чужого заказа, получения списка клиентов или изменения настроек магазина. Публичность здесь означает не «доступ ко всему без пароля», а ограниченный набор данных и операций, необходимых покупателю.

Что такое WooCommerce REST API

Классический WooCommerce REST API — административный и интеграционный интерфейс. Он позволяет читать и изменять ресурсы магазина в соответствии с правами учётной записи или API credentials. Актуальный namespace для стандартных WooCommerce endpoints — wc/v3.

Через него обычно интегрируют WooCommerce с CRM, ERP, складом, учётной системой, собственным backend, сервисом выгрузки товаров или другой системой, которой нужны данные не только текущей покупательской сессии.

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

curl --user "API_USERNAME:APPLICATION_PASSWORD" \
  "https://example.com/wp-json/wc/v3/products"

Здесь показаны только заглушки. Credentials нельзя помещать в JavaScript публичной страницы, мобильный bundle или репозиторий. Такой запрос должен выполняться в доверенной серверной среде.

Какие задачи обычно решают через REST API

• создание и обновление товаров;
• синхронизация цен и остатков;
• чтение и обновление заказов;
• передача заказов в CRM или учётную систему;
• работа с клиентами, купонами и зонами доставки;
• массовые интеграции и фоновые синхронизации;
• служебные сценарии, которым нужны права выше покупательских.

Почему нельзя просто использовать REST API во фронтенде

Технически браузер умеет отправлять HTTP-запросы к любому REST endpoint. Проблема не в протоколе, а в правах. Если для WooCommerce REST API нужны credentials с доступом к заказам или товарам, их нельзя безопасно спрятать в клиентском JavaScript: всё, что получает браузер пользователя, в итоге может быть извлечено.

Поэтому схема «React/Vue/Next frontend напрямую обращается к wc/v3 с ключами магазина» — плохая архитектура. Либо используйте Store API для покупательских действий, либо ставьте между браузером и административным REST API собственный backend, который хранит секреты на сервере и выдаёт наружу только необходимые данные.

Почему Store API не заменяет REST API для CRM и синхронизации

Store API отражает состояние текущего пользователя и магазина с позиции покупателя. У него нет задачи дать внешнему сервису полный административный контроль. Например, публичный Products endpoint возвращает опубликованные товары, но не превращает фронтенд в панель управления каталогом.

Если нужно получить новые заказы, изменить статус, обновить SKU, цену или остаток, синхронизировать каталог с внешней базой — это уже серверная интеграция. Здесь нужен WooCommerce REST API, webhooks, собственный плагин или комбинация этих механизмов.

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

Store API и сессия покупателя: cookies, Nonce и Cart Token

Для каталога авторизация обычно не нужна, но корзина и checkout должны понимать, с каким покупателем они работают. В обычном WooCommerce текущая сессия может быть связана с cookies. Для headless-сценариев Store API также поддерживает Cart Token.

Запрос к корзине возвращает заголовок Cart-Token. Клиент может сохранить его и передавать в последующих запросах корзины и checkout:

curl --header "Cart-Token: EXAMPLE_TOKEN" \
  "https://example.com/wp-json/wc/store/v1/cart"

При использовании Cart Token отдельный Nonce для Cart и Checkout endpoints не требуется. Если Cart Token не используется, POST-запросы к корзине и запросы checkout требуют валидный Nonce в соответствии с документацией Store API.

Важно не путать эти механизмы с административной авторизацией. Cart Token идентифицирует корзину покупателя, но не выдаёт клиенту права управлять магазином.

Пример архитектуры headless WooCommerce

Для headless-магазина часто оптимальна комбинированная схема. Публичный frontend работает со Store API, а серверные процессы используют REST API.

Как выбрать API по задаче

Нужен каталог для посетителя

Начинайте со Store API. Он предоставляет публичный Products endpoint и рассчитан на отображение актуальных опубликованных товаров. В документации отдельно указано, что черновики и неопубликованные товары через Store API не выдаются как обычный публичный каталог.

Нужно создать корзину и оформить заказ

Используйте Store API. Корзина, купоны, доставка и checkout — его прямое назначение. Для headless-клиента заранее продумайте хранение Cart Token или работу с cookies/Nonce.

Нужно выгружать заказы в CRM

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

Нужно менять цены и остатки из внешней системы

Используйте REST API. Внешний сервис работает как доверенная серверная сторона, поэтому credentials хранятся вне браузера и имеют только необходимые права.

Нужны и headless-витрина, и ERP

Используйте оба API. Это не дублирование, а разделение ответственности: Store API обслуживает клиента, REST API — back office. Такой подход проще защищать и сопровождать.

Безопасность: основные правила

• Не храните REST API credentials во frontend-коде. Если секрет попал в браузер, его нельзя считать секретом.
• Используйте HTTPS. Серверная аутентификация и пользовательские данные не должны передаваться по открытому HTTP.
• Выдавайте минимальные права. Если интеграции достаточно чтения, не давайте ей write-доступ.
• Разделяйте credentials между интеграциями. Это упрощает отзыв доступа и расследование проблем.
• Не отключайте Nonce-проверки на production. Официальная документация допускает отключение только как development-механизм.
• Продумайте rate limiting. У Store API есть встроенная опциональная система ограничения запросов; по документации она выключена по умолчанию и включается отдельно.
• Логируйте ошибки без секретов. В журнале достаточно endpoint, HTTP-кода, времени и безопасного идентификатора запроса.

Обработка ошибок и повторных запросов

Интеграция должна различать ошибки клиента и временные ошибки сервера. Ответ 401 или 403 обычно требует проверить авторизацию и права, 404 — endpoint или конкретный ресурс, а 429 — ограничение частоты запросов, если rate limiting включён.

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

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

Когда Store API подходит

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

Когда лучше WooCommerce REST API

• CRM, ERP, склад и учётные системы;
• импорт и экспорт каталога;
• обновление цен и остатков;
• управление заказами и статусами;
• серверные автоматизации и фоновые задачи;
• доступ к данным, которые не должны быть публичными.

Когда одного API недостаточно

Полноценный headless commerce почти всегда содержит как минимум два уровня доверия. Покупателю нужна безопасная публичная часть, а внутренним системам — привилегированный доступ. Поэтому связка Store API + REST API часто естественнее, чем попытка протянуть один интерфейс через весь проект.

Например, frontend показывает каталог и ведёт корзину через Store API. После создания заказа серверный webhook сообщает о нём интеграционному сервису. Затем сервис передаёт заказ в CRM и при необходимости обновляет его через REST API. Секреты при этом никогда не попадают в браузер.

Вывод

Store API и WooCommerce REST API решают не конкурирующие, а разные задачи. Если запрос выполняется от имени покупателя и связан с каталогом, корзиной или checkout, сначала смотрите в сторону Store API. Если внешняя система должна управлять товарами, заказами или другими данными магазина, нужен REST API с серверной авторизацией.

В сложном проекте правильный ответ часто звучит не «Store API или REST API», а «Store API для frontend и REST API для back office». Такое разделение уменьшает риск утечки credentials и делает интеграцию понятнее.

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

• WooCommerce: Getting Started with APIs
• WooCommerce Store API
• WooCommerce REST API
• WooCommerce REST API Authentication
• WooCommerce Store API: Cart Tokens
• WooCommerce Store API: Nonce Tokens
• WooCommerce Store API: Rate Limiting