Headless commercetools интеграция: Next.js + API — под ключ

Интеграция commercetools с фронтендом: архитектура и практика

commercetools не имеет готового UI — только API. Это значит, фронтенд приходится строить с нуля, и выбор стека напрямую влияет на производительность и стоимость поддержки. Наиболее зрелая экосистема сложилась вокруг Next.js с @commercetools/platform-sdk. За 5 лет мы реализовали более 20 headless-проектов — от интернет-магазинов до B2B-порталов, и набили шишки, которые вам не придётся повторять. Типичные боли: ошибка ConcurrentModification при работе с корзиной, потерянные цены из-за неправильного priceCurrency, тормозящий поиск без кэширования. Чтобы не наступать на эти грабли, разберём ключевые архитектурные решения и покажем, как ISR даёт TTFB в 5 раз быстрее традиционного SSR, а синхронизация через Subscriptions обновляет поиск за секунды вместо часов.

Почему headless commercetools — это вызов для фронтенда?

В отличие от монолитных CMS, commercetools не предоставляет ни рендеринга, ни кэширования. Всю логику представления берёт на себя фронтенд. Это даёт свободу, но требует грамотной архитектуры: разделение клиентов (серверный и клиентский), инкрементальная статика, обработка конфликтов версий. Неподготовленная команда часто получает N+1 запросы, высокий TTFB и потерю данных корзины.

SDK и инициализация клиента

npm install @commercetools/platform-sdk @commercetools/sdk-client-v2 \
  @commercetools/sdk-middleware-auth @commercetools/sdk-middleware-http \
  @commercetools/sdk-middleware-queue

Три клиента для трёх контекстов:

// lib/ctpClient.ts
import { createClient } from "@commercetools/sdk-client-v2";
import { createApiBuilderFromCtpClient } from "@commercetools/platform-sdk";

function buildClient(authMiddleware: Middleware) {
  return createApiBuilderFromCtpClient(
    createClient({
      middlewares: [
        authMiddleware,
        createQueueMiddleware({ concurrency: 5 }),
        createHttpMiddleware({
          host: `https://api.${process.env.CTP_REGION}.commercetools.com`,
        }),
      ],
    })
  ).withProjectKey({ projectKey: process.env.CTP_PROJECT_KEY! });
}

export const serverApiRoot = buildClient(
  createAuthMiddlewareForClientCredentialsFlow({
    host: `https://auth.${process.env.CTP_REGION}.commercetools.com`,
    projectKey: process.env.CTP_PROJECT_KEY!,
    credentials: {
      clientId: process.env.CTP_SERVER_CLIENT_ID!,
      clientSecret: process.env.CTP_SERVER_CLIENT_SECRET!,
    },
    scopes: [`view_products:${process.env.CTP_PROJECT_KEY}`],
  })
);

Server-side клиент используется в getStaticProps / RSC. Клиентский (с токеном пользователя) — только в браузере.

ISR решает проблему динамических цен

Если публиковать каталог полностью статически, цены устаревают. Мы используем Incremental Static Regeneration с revalidate: 300 для страниц товаров. Это даёт TTFB 80 мс и свежесть цен не более 5 минут. Для каталогов с частыми обновлениями — Redis-кэш поверх SDK с инвалидацией через webhook.

// app/catalog/[slug]/page.tsx (App Router)
import { serverApiRoot } from "@/lib/ctpClient";

export async function generateStaticParams() {
  const products = await serverApiRoot
    .productProjections()
    .get({
      queryArgs: {
        limit: 500,
        staged: false,
        where: 'masterData(published = true)',
      },
    })
    .execute();

  return products.body.results.map((p) => ({
    slug: p.slug["ru"],
  }));
}

export default async function ProductPage({
  params,
}: {
  params: { slug: string };
}) {
  const result = await serverApiRoot
    .productProjections()
    .get({
      queryArgs: {
        where: `slug(ru = "${params.slug}")`,
        expand: ["productType", "categories[*]"],
        priceCurrency: "RUB",
        priceChannel: "channel-key=storefront-ru",
      },
    })
    .execute();

  const product = result.body.results[0];
  if (!product) notFound();

  return <ProductDetail product={product} />;
}

Корзина: клиентский state + API

Корзина хранится в commercetools — cartId сохраняется в cookie. Никакого дублирования в localStorage.

// hooks/useCart.ts
import { useMutation, useQuery, useQueryClient } from "@tanstack/react-query";
import { browserApiRoot } from "@/lib/ctpClientBrowser";
import Cookies from "js-cookie";

export function useCart() {
  const queryClient = useQueryClient();
  const cartId = Cookies.get("cart_id");

  const { data: cart } = useQuery({
    queryKey: ["cart", cartId],
    queryFn: async () => {
      if (!cartId) return null;
      return (await browserApiRoot.carts().withId({ ID: cartId }).get().execute()).body;
    },
    enabled: !!cartId,
  });

  const addToCart = useMutation({
    mutationFn: async ({
      productId,
      variantId,
      quantity,
    }: {
      productId: string;
      variantId: number;
      quantity: number;
    }) => {
      if (!cartId) {
        const newCart = await browserApiRoot.carts().post({
          body: {
            currency: "RUB",
            store: { typeId: "store", key: "web-ru" },
            lineItems: [{ productId, variantId, quantity }],
          },
        }).execute();
        Cookies.set("cart_id", newCart.body.id, { expires: 30 });
        return newCart.body;
      }
      return (await browserApiRoot.carts().withId({ ID: cartId }).post({
        body: {
          version: cart!.version,
          actions: [
            { action: "addLineItem", productId, variantId, quantity },
          ],
        },
      }).execute()).body;
    },
    onSuccess: (updatedCart) => {
      queryClient.setQueryData(["cart", updatedCart.id], updatedCart);
    },
  });

  return { cart, addToCart };
}

Поиск с синхронизацией Algolia

Commercetools не предоставляет полнотекстовый поиск с релевантностью уровня Algolia. Продуктивное решение — синхронизация через Subscriptions:

// subscriptions/algolia-sync.ts
// Commercetools Subscription → SQS → Lambda → Algolia
export async function handler(event: SQSEvent) {
  for (const record of event.Records) {
    const message = JSON.parse(record.body);
    const { notificationType, resourceTypeId, resourceUserProvidedIdentifiers } = message;
    if (resourceTypeId !== "product") continue;
    const product = await serverApiRoot
      .products()
      .withId({ ID: message.resource.id })
      .get({ queryArgs: { expand: ["productType"] } })
      .execute();
    if (notificationType === "ResourceDeleted") {
      await algoliaIndex.deleteObject(message.resource.id);
    } else {
      await algoliaIndex.saveObject(transformForAlgolia(product.body));
    }
  }
}

Аутентификация покупателей и объединение корзин

Для логина используем Customer SDK. После успешной аутентификации объединяем анонимную корзину с корзиной пользователя — это стандарт для commercetools. Детали реализации в Next.js Route Handlers с httpOnly cookies.

Server-side vs Client-side клиенты

Как избежать ошибок интеграции: типичные проблемы и процесс работы

Конфликт версий (409 ConcurrentModification) — не передан актуальный version. Решение: retry с получением свежего объекта. Мы добавляем механизм автоматической повторной попытки.

400 InvalidInput на корзине — triggered Extension отклонил операцию, читать extensionExtraInfo. Цены не отображаются — не передан priceCurrency и priceChannel в запросе.

Slug не найден — товар не опубликован (staged: true вместо false).

Этапы и сроки

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

• Документация: схема эндпоинтов, описание типов, примеры запросов.
• Доступы: client_id/secret для серверного клиента, парольный флоу для покупателей.
• Обучение: демонстрация работы с SDK, объяснение типичных ошибок.
• Поддержка: 2 недели после деплоя — баг-фиксы и консультации.

Почему выбирают нас

• 5+ лет опыта с commercetools и платформами headless.
• 20+ успешных проектов для e-commerce и B2B.
• Гарантия: Code Review перед каждым деплоем, тесты покрытия >80%.
• Сертификация: наши инженеры прошли официальное обучение commercetools.

Снижение затрат на инфраструктуру на 30-50% благодаря ISR и ускорение вывода на рынок за счёт готовых решений — реальные результаты, которые мы подтверждаем метриками. Получите консультацию по вашему проекту. Мы оценим объём работ и предложим оптимальное решение.