פיתוח מסחר ראשי ללא ראש (Headless) ב-commercetools: חנויות ניתנות להרחבה

פיתוח מסחר ללא ראש (Headless Commerce) עם commercetools

מצב טיפוסי: פלטפורמה מונוליטית על WooCommerce או Magento מאטה בעומסי שיא. כל שינוי דורש סנכרון של עשרות מפתחים, והשקת ערוץ מכירות חדש אורכת חודשים. התקציב הולך לתמיכה בתשתית במקום לתכונות עסקיות. נתקלנו בזה פעמים רבות. הפתרון הטוב ביותר הוא מסחר ללא ראש על commercetools. ארכיטקטורת API-first: הקצה האחורי מוכן, הצוות כותב רק לוגיקה עסקית וחזית. במשך יותר מ-7 שנים, סיפקנו 10+ פרויקטים—מקמעונאות אופנה ועד שווקי B2B מורכבים. לפי Gartner, 80% מפרויקטי המסחר האלקטרוני החדשים בוחרים בגישת ה-headless. commercetools מובילה בנישה זו, ומהווה דוגמה מצוינת למסחר קומפוזבילי. מעבר ל-headless יכול להפחית את עלות הבעלות הכוללת (TCO) ב-30-40% ולהאיץ את זמן היציאה לשוק של תכונות חדשות פי 2-3. עלויות פרויקט טיפוסיות נעות בין 80,000 ל-200,000 דולר, כאשר לקוחות חוסכים 100,000+ דולר בשנה.

כיצד פועלת הארכיטקטורה של commercetools

commercetools הוא קצה אחורי למסחר ללא ראש עם API מלא. אין מונולית: הכל דרך HTTP API, כל הישויות (Product, Cart, Order, Customer) מנוהלות כמשאבים. הפלטפורמה פועלת כ-backend-as-a-service. התשתית כולה בצד של commercetools. הצוות כותב רק לוגיקה עסקית וחזית. הפלטפורמה מבטיחה SLA של 99.9% ומטפלת בעד 5000 בקשות בשנייה.

רכיבי הפתרון:

• חנות (Storefront) — אפליקציית React/Next.js/Nuxt העובדת עם Composable Commerce API
• התאמות אישיות — API Extensions ו-Subscriptions ללוגיקה עסקית מותאמת
• אינטגרציות — חיבור ERP (1C, SAP), PIM, שער תשלום, שירותי דוא"ל
• תצורה — הגדרת פרויקט דרך Merchant Center או Terraform provider labd/commercetools

הפלטפורמה מספקת: ניהול קטלוג, תמחור רב-ממדי (המחיר תלוי בערוץ, מטבע, קבוצת לקוחות, תאריך), עגלות, הזמנות, לקוחות, קודי קופון ומלאי.

למה לבחור בגישת API-first?

גמישות היא היתרון המרכזי. אתה לא כבול לחזית ספציפית. ניתן לשכתב את החנות מבלי לגעת בקצה האחורי. המחירים מוגדרים כמטריצה רב-ממדית: ערוץ × מטבע × קבוצת לקוחות × תאריך. זה מאפשר השקה קלה של גרסאות אזוריות, פורטלי B2B ומבצעים עונתיים. השקת ערוץ חדש אורכת ימים במקום שבועות, וחוסכת עד 50% מתקציב הפיתוח. למעשה, commercetools מהירה פי 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 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 :

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).

// Поиск с фасетами
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();

עגלה ותשלום (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();

גרסאות (Versioning) הוא מנגנון מפתח. כל עדכון דורש העברת @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! }); . זה מונע קונפליקטים עם בקשות מקבילות.

כיצד לשלב שער תשלום: שלב אחר שלב

1. צור אובייקט Payment ב-commercetools דרך ה-API.
2. העבר את Payment.id לשער התשלום (Stripe, Adyen, YooKassa).
3. המתן לאישור משער התשלום (callback או polling).
4. עדכן את סטטוס התשלום דרך API Extension או ידנית: הגדר // Поиск с фасетами 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(); ו-// Создать корзину 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(); .
5. חבר את התשלום להזמנה דרך פעולת version.

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)
• קוד מקור לחנות (Next.js) והתאמות אישיות (API Extensions, Subscriptions)
• הוראות פריסה (CI/CD, Docker, משתנים)
• הכשרת צוות: סדנה על ארכיטקטורה ושימוש בפלטפורמה
• אחריות ל-3 חודשים לתיקון תקלות נסתרות

מחסנית טכנית

• חנות: Next.js 14 (App Router) + React Query + 409 Concurrent Modification
• State: Zustand לעגלה, React Query לנתוני שרת
• חיפוש: commercetools Product Search או Algolia דרך Sync
• CMS: Contentful / Storyblok לדפי תוכן
• IaC: Terraform paymentStatus.interfaceCode provider לתצורה מבוקרת גרסאות

טעויות נפוצות וכיצד להימנע מהן

• טיפול לא נכון בקונפליקטי גרסאות (שגיאות 409) — תמיד בדוק paymentStatus.interfaceText בצד הלקוח. כ-10% מהבקשות ללא לוגיקת retry מובילות לכשלים.
• שאילתות API לא אופטימליות — השתמש ב-Projections ובדפדוף, הימנע מ-N+1. לדוגמה, שליפת פרטי מוצר ללא Projections יכולה לטעון 50+ שדות כאשר רק 5 נדרשים.
• התעלמות ממגבלות קצב (rate limits) — לפרויקטים יש מגבלות בקשות; יש לבנות תור. חריגה מהמגבלה מחזירה 429, ומאטה את הפיתוח.

הצוות שלנו מוסמך ובעל ניסיון של למעלה מ-7 שנים עם commercetools. אנו מבטיחים עמידה בלוחות זמנים ו-SLA. צור קשר לייעוץ—נעזור לך להעריך את הפרויקט ולהציע ארכיטקטורה אופטימלית. הזמן פיילוט של שבועיים לבדיקת איכות.

למידע נוסף על הארכיטקטורה, ראה תיעוד commercetools.