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 и ускорение вывода на рынок за счёт готовых решений — реальные результаты, которые мы подтверждаем метриками. Получите консультацию по вашему проекту. Мы оценим объём работ и предложим оптимальное решение.