Разработка интернет-магазина на commercetools: headless commerce

Разработка интернет-магазина на commercetools

Типичная ситуация: монолитная платформа на WooCommerce или Magento тормозит при пиковых нагрузках. Каждая доработка требует синхронизации десятков разработчиков, а запуск нового канала продаж растягивается на месяцы. Бюджет уходит на поддержку инфраструктуры, а не на бизнес-фичи. Мы сталкивались с этим не раз. Лучший выход — headless commerce на commercetools. API-first архитектура: бэкенд уже готов, команда пишет только бизнес-логику и фронтенд. За более чем 7 лет мы реализовали 10+ проектов — от fashion-ритейла до сложных B2B-маркетплейсов. По данным Gartner, 80% новых e-commerce проектов выбирают headless подход. commercetools лидирует в этой нише. Переход на headless позволяет снизить TCO на 30-40% и ускорить вывод новых функций в 2-3 раза.

Как устроена архитектура commercetools?

commercetools — headless commerce бэкенд с полным API. Никакого монолита: всё через HTTP API, все сущности (Product, Cart, Order, Customer) управляются как ресурсы. Платформа работает как backend-as-a-service. Инфраструктура полностью на стороне commercetools. Команда пишет только бизнес-логику и фронтенд. Платформа гарантирует SLA 99.9% и выдерживает до 5000 запросов в секунду.

Компоненты решения:

• Storefront — React/Next.js/Nuxt приложение, работающее с Composable Commerce API
• Customizations — API Extensions и Subscriptions для кастомной бизнес-логики
• Integrations — подключение ERP (1С, SAP), PIM, payment gateway, email-сервисов
• Configuration — настройка Project через Merchant Center или Terraform-провайдер labd/commercetools

Платформа предоставляет: управление каталогом, многомерное ценообразование (цена зависит от канала, валюты, группы клиентов, даты), корзины, заказы, кастомеров, промокоды и инвентарь.

Почему стоит выбрать API-first подход?

Гибкость — главный козырь. Вы не привязаны к конкретному фронтенду. Можно переписать storefront, не трогая бэкенд. Цены настраиваются как многомерная матрица: канал × валюта × группа клиентов × дата. Это позволяет легко запускать региональные версии, B2B-порталы и сезонные акции. Запуск нового канала занимает дни вместо недель, что экономит до 50% бюджета на разработку.

Сравним с традиционной платформой: в типовом решении на WordPress/WooCommerce каждый новый канал продаж — копия базы данных и кастомная доработка. С commercetools достаточно создать новый Channel и настроить правила ценообразования — всё остальное переиспользуется. А при использовании Terraform конфигурация становится кодом: изменения проходят код-ревью.

Архитектура проекта

commercetools project ├── Product Types (схемы атрибутов) ├── Categories (дерево категорий) ├── Products + Variants ├── Prices (price list: channel × currency × customer group) ├── Channels (storefront RU, storefront EN, B2B portal) ├── Stores (фильтрация каталога по сторам) ├── Carts → Orders └── Customers + Customer Groups 

Фронтенд взаимодействует через @commercetools/platform-sdk:

import { createClient } from "@commercetools/sdk-client-v2"; import { createApiBuilderFromCtpClient } from "@commercetools/platform-sdk"; import { createAuthMiddlewareForClientCredentialsFlow } from "@commercetools/sdk-middleware-auth"; import { createHttpMiddleware } from "@commercetools/sdk-middleware-http"; const authMiddleware = createAuthMiddlewareForClientCredentialsFlow({ host: "https://auth.europe-west1.gcp.commercetools.com", projectKey: process.env.CTP_PROJECT_KEY!, credentials: { clientId: process.env.CTP_CLIENT_ID!, clientSecret: process.env.CTP_CLIENT_SECRET!, }, scopes: [`view_products:${process.env.CTP_PROJECT_KEY}`], }); const httpMiddleware = createHttpMiddleware({ host: "https://api.europe-west1.gcp.commercetools.com", }); const ctpClient = createClient({ middlewares: [authMiddleware, httpMiddleware], }); export const apiRoot = createApiBuilderFromCtpClient(ctpClient) .withProjectKey({ projectKey: process.env.CTP_PROJECT_KEY! }); 

Каталог: запросы с фильтрами и поиском

commercetools предоставляет два механизма поиска: Product Projections Search (на Elasticsearch) и Product Projections Query (SQL-like).

// Поиск с фасетами const searchResult = await apiRoot .productProjections() .search() .get({ queryArgs: { "text.ru": "кроссовки", fuzzy: true, filter: [ 'categories.id: subtree("cat-footwear-id")', 'variants.attributes.brand: "Nike","Adidas"', 'variants.price.centAmount: range(0 to 1000000)', ], facet: [ 'variants.attributes.brand counting products', 'variants.attributes.size counting products', 'variants.price.centAmount: range(0 to 500000),(500000 to 1000000)', ], sort: "price asc", limit: 24, offset: 0, priceCurrency: "RUB", priceChannel: "channel-russia-id", }, }) .execute(); 

Cart и Checkout

// Создать корзину const cart = await apiRoot.carts().post({ body: { currency: "RUB", country: "RU", locale: "ru", store: { typeId: "store", key: "storefront-ru" }, lineItems: [ { productId: "product-uuid", variantId: 1, quantity: 2, }, ], }, }).execute(); // Применить промокод const updatedCart = await apiRoot.carts() .withId({ ID: cart.body.id }) .post({ body: { version: cart.body.version, actions: [ { action: "addDiscountCode", code: "SUMMER", }, ], }, }) .execute(); 

Версионирование — ключевая механика. Каждый update требует передачи актуального version, иначе получаем 409 Concurrent Modification. Это предотвращает конфликты при параллельных запросах.

Как интегрировать платежный шлюз: пошаговая инструкция

1. Создайте Payment объект в commercetools через API.
2. Передайте Payment.id в платёжный шлюз (Stripe, Adyen, YooKassa).
3. Дождитесь подтверждения от шлюза (callback или polling).
4. Обновите статус Payment через API Extension или вручную: установите paymentStatus.interfaceCode и paymentStatus.interfaceText.
5. Привяжите Payment к заказу через action addPayment.

commercetools не обрабатывает платежи напрямую — это архитектурное решение, которое даёт гибкость.

const payment = await apiRoot.payments().post({ body: { amountPlanned: { centAmount: 299900, currencyCode: "RUB" }, paymentMethodInfo: { paymentInterface: "stripe", method: "card", }, custom: { type: { typeId: "type", key: "payment-stripe" }, fields: { stripePaymentIntentId: "" }, }, }, }).execute(); // Привязать к заказу await apiRoot.orders().withId({ ID: orderId }).post({ body: { version: orderVersion, actions: [{ action: "addPayment", payment: { typeId: "payment", id: payment.body.id } }], }, }).execute(); 

Этапы разработки и сроки

Что входит в работу

• Архитектурная документация: схема проекта, описание интеграций, политика обновлений
• Доступ к проекту commercetools с настроенными окружениями (dev, staging, prod)
• Исходный код storefront (Next.js) и customizations (API Extensions, Subscriptions)
• Инструкция по развертыванию (CI/CD, Docker, variables)
• Обучение команды: воркшоп по архитектуре и работе с платформой
• Гарантия 3 месяца на исправление скрытых дефектов

Технический стек

• Storefront: Next.js 14 (App Router) + React Query + @commercetools/platform-sdk
• State: Zustand для корзины, React Query для серверных данных
• Поиск: commercetools Product Search или Algolia через Sync
• CMS: Contentful / Storyblok для контентных страниц
• IaC: Terraform labd/commercetools provider для version-controlled конфига

Типичные ошибки и как их избежать

• Некорректная обработка версий (409 ошибки) — всегда проверять version на клиенте. Около 10% запросов без retry-логики приводят к сбоям.
• Неоптимальные запросы к API — использовать Projections и пагинацию, избегать N+1. Например, запрос деталей товара без Projections может загрузить 50+ полей, из которых нужны только 5.
• Игнорирование rate limits — проекты имеют ограничения на количество запросов, нужно строить очередь. При превышении лимита API возвращает 429, что замедляет разработку.

Наша команда сертифицирована и имеет опыт работы с commercetools более 7 лет. Мы гарантируем соблюдение сроков и SLA. Свяжитесь с нами для консультации — поможем оценить ваш проект и предложим оптимальную архитектуру. Закажите пилот на 2 недели, чтобы убедиться в качестве.

Подробнее об архитектуре можно узнать в документации commercetools.