Розробка інтернет-магазину на 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 рази. Наші клієнти економлять у середньому $30,000–$50,000 на рік на інфраструктурі після переходу на headless рішення.

Як влаштована архітектура 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% бюджету на розробку. commercetools в 2-3 рази швидше за Magento при запуску нових каналів продажів.

Порівняємо з традиційною платформою: в типовому рішенні на 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, що сповільнює розробку.
• Для забезпечення ідемпотентності при інтеграції з ERP використовуйте унікальні ключі запитів.

Наша команда сертифікована та має досвід роботи з commercetools понад 7 років. Ми гарантуємо дотримання строків та SLA. Пишіть нам на пошту або заповніть форму — оцінимо ваш проєкт безкоштовно за 1 день. Наша команда має 7+ років досвіду в e-commerce та реалізувала 10+ успішних проєктів на commercetools. Зв'яжіться з нами для консультації — допоможемо оцінити ваш проєкт і запропонуємо оптимальну архітектуру. Замовте пілот на 2 тижні, щоб переконатися в якості.

Детальніше про архітектуру можна дізнатися в документації commercetools.