מדריך הגדרת פרויקט ו-API של commercetools

לאחר יצירת פרויקט ב-commercetools, רבים נתקלים בשגיאות בלתי צפויות: מחירים המוצגים במטבע שגוי, תרגומים חסרים, סל קניות שאינו מגיב לשינויי אזור. הסיבה היא תצורה ראשונית לא תקינה. תיקון הבעיה אורך שבוע, מכיוון שהפרויקט חי עם אזור קבוע והגדרות בסיסיות. לדוגמה, מקרה אחרון: לקוח מרוסיה ראה יורו במקום דולרים. התברר שלא נוצרה ערוץ (Channel) לשוק הרוסי. התיקון ארך 3 ימים באמצעות עדכון מחירים בכמות גדולה. מצב זה אופייני — 70% מבעיות התמחור נובעות מתצורת ערוצים ראשונית שגויה. המהנדסים שלנו, עם חמש שנות ניסיון בעבודה עם commercetools, מקימים פרויקטים במפתח מלא, ומבטיחים ארכיטקטורה נכונה.

כבר סיפקנו למעלה מ-30 פרויקטים עבור חנויות מסחריות ומוצריות. כל התקנה כוללת תיעוד, סקריפטים להעברת נתונים והדרכת צוות. טעויות בשלב התצורה הראשונית עולות מאוחר יותר במאות שעות עבודה — קל יותר למנוע. קבלו ייעוץ על הארכיטקטורה של הפרויקט שלכם.

בחירת אזור והמגבלות שלו

commercetools פועל על GCP ו-AWS במספר אזורים. זמן השהייה בין אזורים יכול להגיע ל-200 אלפיות השנייה, מה שקריטי עבור בקשות API של חנות. בחירת אזור שגוי עלולה להוביל לעלויות העברת נתונים נוספות, שהיקפן תלוי בפרויקט.

עבור שוק חבר העמים, בחרו ב-europe-west1.gcp. האזור קבוע עם יצירת הפרויקט ואינו ניתן לשינוי. שגיאה בשלב זה הופכת העברת נתונים לאזור אחר לבלתי אפשרית ללא שכפול מלא. ראו תיעוד commercetools.

תצורה ראשונית דרך Merchant Center

לאחר יצירת פרויקט ב-mc.commercetools.com, הגדירו את הפרמטרים הבסיסיים. הגדרות → בינלאומי:

• שפות: ru, en (הראשונה היא ברירת המחדל)
• מטבעות: USD, USD, EUR
• מדינות: RU, BY, KZ

הגדרות אלו קובעות את הערכים המותרים עבור מחירים, תרגומים ומשלוחים בכל הפרויקט. אם לא צוינה שפת ברירת מחדל, חלק מהבקשות יחזירו מחרוזות ריקות במקום תרגומים.

כיצד להגדיר ערוצים וחנויות?

ערוץ (Channel) הוא הפשטה לתמחור ומלאי. חנות (Store) היא נקודת מכירה עם סינון קטלוג. שימוש בערוץ נפרד לכל חנות מפחית משמעותית את הסיכון לחפיפת מחירים — אימתו זאת בפועל.

// Создать Channel и Store
const channel = await apiRoot.channels().post({
  body: {
    key: "storefront-ru",
    roles: ["ProductDistribution", "InventorySupply"],
    name: {
      ru: "Сайт Россия",
      en: "Website Russia"
    },
    defaultLocale: "ru",
    defaultCurrency: "USD",
    address: {
      country: "RU"
    },
  },
}).execute();

const store = await apiRoot.stores().post({
  body: {
    key: "web-ru",
    name: {
      ru: "Веб-магазин Россия"
    },
    countries: [{ code: "RU" }],
    languages: ["ru"],
    distributionChannels: [{ typeId: "channel", id: channel.body.id }],
    supplyChannels: [{ typeId: "channel", id: channel.body.id }],
  },
}).execute();

אם אתם צריכים מספר אתרים (RU/BY/KZ), צרו ערוץ וחנות נפרדים לכל אחד. זה מבטיח שמחירים ומלאי לא יתערבבו בין אזורים.

כיצד להגדיר לקוחות API עם הרשאות מינימליות?

כל שירות מקבל לקוח API משלו עם ההרשאות המינימליות הנדרשות. זהו הבסיס לאבטחה. היקפי הרשאות מומלצים לכל לקוח:

לקוח עבור חנות (אנונימי):

const anonymousAuthMiddleware = createAuthMiddlewareForAnonymousSessionFlow({
  host: "https://auth.europe-west1.gcp.commercetools.com",
  projectKey: process.env.CTP_PROJECT_KEY!,
  credentials: {
    clientId: process.env.CTP_STOREFRONT_CLIENT_ID!,
    clientSecret: process.env.CTP_STOREFRONT_CLIENT_SECRET!,
  },
  scopes: [
    `view_products:${process.env.CTP_PROJECT_KEY}`,
    `manage_my_carts:${process.env.CTP_PROJECT_KEY}`,
    `manage_my_orders:${process.env.CTP_PROJECT_KEY}`,
  ],
});

עבור משתמשים מאומתים, נעשה שימוש בלקוח דומה עם הרשאות נוספות // Создать Channel и Store const channel = await apiRoot.channels().post({ body: { key: "storefront-ru", roles: ["ProductDistribution", "InventorySupply"], name: { ru: "Сайт Россия", en: "Website Russia" }, defaultLocale: "ru", defaultCurrency: "USD", address: { country: "RU" }, }, }).execute(); const store = await apiRoot.stores().post({ body: { key: "web-ru", name: { ru: "Веб-магазин Россия" }, countries: [{ code: "RU" }], languages: ["ru"], distributionChannels: [{ typeId: "channel", id: channel.body.id }], supplyChannels: [{ typeId: "channel", id: channel.body.id }], }, }).execute(); ו-const anonymousAuthMiddleware = createAuthMiddlewareForAnonymousSessionFlow({ host: "https://auth.europe-west1.gcp.commercetools.com", projectKey: process.env.CTP_PROJECT_KEY!, credentials: { clientId: process.env.CTP_STOREFRONT_CLIENT_ID!, clientSecret: process.env.CTP_STOREFRONT_CLIENT_SECRET!, }, scopes: [ `view_products:${process.env.CTP_PROJECT_KEY}`, `manage_my_carts:${process.env.CTP_PROJECT_KEY}`, `manage_my_orders:${process.env.CTP_PROJECT_KEY}`, ], }); .

מדוע להשתמש ב-Terraform לתצורה?

שמירת תצורת הפרויקט ב-Git היא פרקטיקה טובה לסביבות ניתנות לשחזור. Terraform מפחית שגיאות תצורה פי 3 בהשוואה להגדרה ידנית דרך Merchant Center. שימוש ב-Terraform יכול להפחית משמעותית שגיאות תצורה ולייעל פריסות.

# main.tf
terraform {
  required_providers {
    commercetools = {
      source = "labd/commercetools"
      version = "~> 1.4"
    }
  }
}

provider "commercetools" {
  client_id = var.ctp_client_id
  client_secret = var.ctp_client_secret
  project_key = var.ctp_project_key
  token_url = "https://auth.europe-west1.gcp.commercetools.com"
  api_url = "https://api.europe-west1.gcp.commercetools.com"
}

resource "commercetools_channel" "storefront_ru" {
  key = "storefront-ru"
  roles = ["ProductDistribution", "InventorySupply"]
  name = {
    ru = "Сайт Россия"
    en = "Website Russia"
  }
}

resource "commercetools_store" "web_ru" {
  key = "web-ru"
  name = {
    ru = "Веб-магазин Россия"
  }
  languages = ["ru", "en"]
  countries = ["RU"]
  distribution_channels = [commercetools_channel.storefront_ru.key]
  supply_channels = [commercetools_channel.storefront_ru.key]
}

terraform init terraform plan terraform apply 

סוגי מוצרים: מה לדעת לפני היצירה

סוג מוצר (Product Type) הוא סכמת תכונות עבור קבוצת מוצרים. לא ניתן לשנות סוג תכונה לאחר היצירה; ניתן רק למחוק וליצור מחדש. לכן, לפני הפיתוח, ודאו שהסכמה מסוכמת עם צוות התוכן.

await apiRoot.productTypes().post({
  body: {
    key: "apparel",
    name: "Одежда",
    description: "Атрибуты для одежды",
    attributes: [
      {
        name: "brand",
        label: { ru: "Бренд", en: "Brand" },
        type: { name: "text" },
        isRequired: false,
        isSearchable: true,
      },
      {
        name: "size",
        label: { ru: "Размер", en: "Size" },
        type: {
          name: "enum",
          values: [
            { key: "XS", label: "XS" },
            { key: "S", label: "S" },
            { key: "M", label: "M" },
            { key: "L", label: "L" },
            { key: "XL", label: "XL" },
          ],
        },
        isRequired: true,
        isSearchable: true,
      },
    ],
  },
}).execute();

מה כלול בהקמת פרויקט במפתח מלא

אנו מספקים סט מלא של נכסים:

• תיעוד ארכיטקטורה עם דיאגרמות.
• סקריפטים להעברת נתונים מהמערכת הנוכחית שלכם.
• סביבות מוגדרות: dev, staging, production.
• אינטגרציית CI/CD.
• הדרכת צוות: 2-3 מפגשים.
• תמיכה למשך 14 ימים לאחר ההשקה.

טעויות אופייניות ורשימת בדיקה

לפני תחילת הפיתוח, בדקו: