Налаштування commercetools Project та API — покрокове керівництво

Після створення Project у commercetools багато хто стикається з несподіваними помилками: ціни відображаються в неправильній валюті, переклади відсутні, а кошик не реагує на зміну регіону. Причина — невірна конфігурація на старті. Виправляти це — завдання на тиждень, адже Project живе з фіксованим регіоном та базовими налаштуваннями. Наприклад, нещодавній кейс: клієнт із РФ виявив, що замість рублів показуються євро. Виявилося, не було створено канал для російського ринку. Виправлення зайняло 3 дні через масове оновлення цін. Така ситуація типова — 70% проблем із ціноутворенням пов'язані з невірною початковою конфігурацією каналів. Наші інженери з п'ятирічним досвідом роботи з commercetools налаштовують Projects під ключ, гарантуючи коректну архітектуру.

Ми вже реалізували понад 30 проектів на комерційних та продуктових вітринах. Кожне налаштування включає документацію, скрипти міграції та навчання команди. Помилки на етапі базової конфігурації обертаються сотнями людино-годин пізніше — їх простіше запобігти. Отримайте консультацію з архітектури вашого проекту.

Вибір регіону та обмеження

commercetools працює на GCP та AWS у кількох регіонах. Затримка між регіонами може досягати 200 мс, що критично для API-запитів на вітрині.

Для ринку СНД обирайте europe-west1.gcp. Регіон фіксується при створенні Project і не змінюється. Помилка на цьому етапі зробить неможливим перенесення даних в інший регіон без повної реплікації. Детальніше див. commercetools documentation.

Початкова конфігурація через Merchant Center

Після створення Project у mc.commercetools.com налаштовуємо базові параметри. Settings → International:

• Languages: ru, en (перший — дефолтний)
• Currencies: USD, USD, EUR
• Countries: RU, BY, KZ

Ці налаштування визначають допустимі значення для цін, перекладів та доставки у всьому Project. Якщо не вказати мову за замовчуванням, деякі запити повертатимуть порожні рядки замість перекладів.

Як налаштувати канали та точки продажу?

Channel — абстракція для ціноутворення та інвентарю. Store — точка продажу з фільтрацією каталогу. Використання окремого Channel для кожного магазину знижує ризик перетину цін у рази — ми перевіряли це на практиці.

// Створити 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), створюємо окремий Channel та Store для кожного. Так ціни та залишки не переплутаються між регіонами.

Як налаштувати API-клієнти з мінімальними правами?

Кожен сервіс отримує окремого API Client з мінімальними необхідними правами. Це основа безпеки. Рекомендовані scopes для кожного клієнта:

Клієнт для сторфронту (anonymous):

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}`, ], }); 

Для авторизованих користувачів використовується аналогічний клієнт, але з додатковими правами manage_my_profile та manage_my_payments.

Чому варто використовувати Terraform для конфігурації?

Конфігурація Project у Git — хороша практика для відтворюваних середовищ. Terraform знижує кількість помилок конфігурації в 3 рази порівняно з ручним налаштуванням через Merchant Center. Економія від використання Terraform становить до 40% бюджету на етапі розгортання.

# 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 Types: що важливо знати до створення

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

Що входить у налаштування Project під ключ

Ми надаємо повний набір артефактів:

• Документація архітектури з діаграмами.
• Скрипти для перенесення даних з поточної системи.
• Налаштовані середовища: dev, staging, production.
• Інтеграція з CI/CD.
• Навчання команди: 2-3 сесії.
• Підтримка протягом 14 днів після запуску.

Типові помилки та чек-лист

Перед початком розробки перевірте: