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

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

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

Что входит в полноценный магазин

Разработка на commercetools — это несколько независимых слоёв:

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

Сама платформа предоставляет: управление каталогом, ценообразование (price list per customer group, per channel), корзины, заказы, кастомеров, промокоды, инвентарь.

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

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: "SUMMER2024",
        },
      ],
    },
  })
  .execute();

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

Ценообразование

Цены в commercetools — отдельный объект с многомерной матрицей:

await apiRoot.products()
  .withId({ ID: productId })
  .post({
    body: {
      version: currentVersion,
      actions: [
        {
          action: "addPrice",
          variantId: 1,
          price: {
            value: { centAmount: 299900, currencyCode: "RUB" },
            channel: { typeId: "channel", id: "channel-ru-id" },
            customerGroup: { typeId: "customer-group", id: "wholesale-id" },
            validFrom: "2024-01-01T00:00:00.000Z",
            validUntil: "2024-12-31T23:59:59.999Z",
          },
        },
      ],
    },
  })
  .execute();

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

Интеграция платёжного провайдера

commercetools не обрабатывает платежи напрямую — это сделано осознанно. Паттерн:

1. Создать Payment объект в commercetools
2. Передать Payment.id в payment gateway (Stripe, Adyen, YooKassa)
3. Gateway подтверждает — обновить Payment через API Extension или вручную

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();

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

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

• 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 конфига