Ціни

Ціну через API магазин рахує так само, як для покупця на вітрині. Окремого прайсу для API немає. Покупцем при цьому вважається контакт, якому власник видав ключ, тому дропшипер чи оптовик одразу бачить свою ціну.

Ціну можна отримати двома способами:

• блоком price у кожного артикула в /products, /products/{id} і /skus, якщо ключ має право prices:read;
• окремим легким списком /prices без описів і фото. Йому потрібне лише право prices:read, право на каталог не потрібне.

Як рахується ціна#

1. Магазин бере ціну артикула. Якщо власник задав артикулу ціну в іншій валюті, магазин переводить її в основну валюту.
2. Застосовує акції каталогу, які зараз діють на товар.
3. Застосовує правила доповнень цін для вашого контакту, тобто ціну для його категорії покупців і персональні ціни. Так працює, наприклад, доповнення «Оптові ціни». Якщо таких доповнень у магазині немає, ціна одна для всіх. Якщо у вашого контакту є особистий кабінет на сайті магазину, ви вважаєтеся зареєстрованим покупцем і отримуєте ціни для зареєстрованих покупців, а без кабінету — ціни гостя.
4. Переводить підсумок у валюту вітрини за поточним курсом магазину. Один курс діє на всю відповідь.

Зважайте на кілька правил:

• Поле price — ціна однієї одиниці продажу під час купівлі однієї одиниці. Ціни від кількості («від 10 штук дешевше») приходять окремо, у списку tiers. Його поля описано в розділі «Щаблі за кількістю».
• Якщо найменша купівля товару менша за одну одиницю, наприклад 0,1 кг, і ціна за неї інша, ця ціна прийде першим щаблем у tiers.
• Знижки кошика, промокоди й бонуси магазин рахує лише під час оформлення замовлення, у ціні API їх немає.
• Податок уже входить у ціну, як і на вітрині.
• Закупівельну ціну API не віддає ніколи.

За цими ж правилами магазин рахує ціни в замовленні, яке ви передаєте через API. Ціна позиції в замовленні збігається з price із /prices, а за великої кількості — з ціною відповідного щабля з tiers. Докладніше на сторінці «Замовлення партнера».

Валюта вітрини приходить у полі currency. Ціни іншої вітрини ви отримаєте, передавши її номер у storefront_id. Номери й валюти вітрин віддає /storefronts.

Поля ціни#

Ці поля однакові в блоці price в артикула й у записі списку /prices.

Приклад блоку в артикула:

"price": { "price": "208.32", "compare_price": "320.00", "discount_percent": 35, "currency": "UAH", "tiers": [] }

Той самий артикул на вітрині в доларах за курсу 41,25:

"price": { "price": "5.05", "compare_price": "7.76", "discount_percent": 35, "currency": "USD", "tiers": [] }

Щаблі за кількістю#

Щабель задає ціну однієї одиниці, якщо в замовленні не менше вказаної кількості цього артикула, наприклад «від 10 штук по 180 ₴». Щаблі задає доповнення цін, зараз це «Оптові ціни» версії 1.4.0 і новіших. Список tiers порожній, якщо такого доповнення в магазині немає або воно вимкнене, а також якщо в артикула немає щаблів для вашого контакту.

У список потрапляють загальні щаблі та щаблі тієї категорії покупців, до якої належить ваш контакт. Щаблів інших категорій ви не побачите. Власник задає щабель усьому товару або окремому артикулу. Щабель товару приходить у кожного його артикула, щабель артикула — лише в нього.

Ціну щабля магазин рахує так само, як у кошику за такої кількості. У ній уже враховано акції каталогу та знижку вашої категорії. Враховано й два налаштування доповнення «Оптові ціни»: «Якщо на товар уже діє акція» і «Не продавати нижче закупівельної ціни». Знижок кошика, промокодів і бонусів у ціні щабля немає, як і в price.

У товару, який продають лише упаковками (pack_only: true), поріг, що не ділиться на упаковку націло, починає діяти пізніше, ніж зазначено в min_quantity. Кошик округлює кількість такого товару вгору до цілих упаковок. Тому ціна щабля діє з першої цілої кількості упаковок, яка не менша за поріг. Наприклад, якщо поріг 10 м², а упаковка 1,4 м², ціна щабля діє з 8 упаковок, тобто з 11,2 м².

Правила списку:

• щаблі відсортовано за min_quantity за зростанням;
• на один поріг приходить один щабель із тією ціною, яку ви отримаєте під час замовлення такої кількості. Якщо власник задав однаковий поріг і товару, і його артикулу, діє щабель артикула;
• ціна щабля діє від його порогу до порогу наступного щабля, сам цей поріг уже не входить. Останній щабель діє від свого порогу на будь-яку кількість;
• щабель приходить, якщо його ціна відрізняється від ціни попереднього щабля, а в першого щабля — від price. Ціни порівнюються у валюті відповіді, після округлення до двох знаків. Щабель із тією самою ціною нічого не змінює, тому його немає в списку. Щабель, дорожчий за попередній, приходить, бо з його порогу ви платите більше;
• якщо найменша купівля товару менша за одну одиницю, першим може прийти щабель із таким порогом. Його поріг дорівнює мінімальній кількості товару. У товару, який продають лише упаковками, мінімальну кількість округлюють угору до цілої кількості упаковок. Такий щабель приходить, лише коли його ціна відрізняється від price. Не пізніше порогу в одну одиницю в списку завжди є щабель за ціною price, тому ціна найменшої купівлі діє лише на кількість, меншу за одну одиницю.

Приклад: звичайна ціна 200 ₴, від 10 штук 180 ₴, від 50 штук мінус 20 %.

"price": {
    "price": "200.00",
    "compare_price": null,
    "discount_percent": null,
    "currency": "UAH",
    "tiers": [
        { "min_quantity": "10.000", "min_packs": null, "price": "180.00", "discount_percent": 10 },
        { "min_quantity": "50.000", "min_packs": null, "price": "160.00", "discount_percent": 20 }
    ]
}

Верхній щабель буває дорожчим за нижній. Наприклад, звичайна ціна артикула 100 ₴. Власник задав усьому товару ціну 80 ₴ від 10 штук, а цьому артикулу — 100 ₴ від 50 штук. Тоді артикул від 10 до 49 штук коштує 80 ₴, а від 50 штук знову 100 ₴, і відсотка знижки в цього щабля немає:

"tiers": [
    { "min_quantity": "10.000", "min_packs": null, "price": "80.00", "discount_percent": 20 },
    { "min_quantity": "50.000", "min_packs": null, "price": "100.00", "discount_percent": null }
]

Ваговий товар продають від 0,1 кг по 100 ₴ за кілограм, а від 1 кг — по 90 ₴. Ціна одного кілограма вже оптова, тому в price прийде 90 ₴. Щоб було видно, що менше кілограма коштує 100 ₴, першим прийде щабель із порогом 0,1. Другий щабель повертає ціну 90 ₴ з одного кілограма. Відсотка знижки немає в жодного з них, бо жоден не дешевший за price:

"price": {
    "price": "90.00",
    "compare_price": "100.00",
    "discount_percent": 10,
    "currency": "UAH",
    "tiers": [
        { "min_quantity": "0.100", "min_packs": null, "price": "100.00", "discount_percent": null },
        { "min_quantity": "1.000", "min_packs": null, "price": "90.00", "discount_percent": null }
    ]
}

Коли власник змінює щабель, магазин позначає зміненими всі артикули цього товару, і нові щаблі прийдуть через updated_since у /products і /skus. Зміна знижки категорії чи налаштувань доповнення «Оптові ціни» позначає зміненим увесь каталог.

GET /api/v1/prices#

Ціни артикулів опублікованих товарів. Право: prices:read. Порядок: за номером артикула, за зростанням. Адреса підходить, щоб регулярно звіряти ціни, наприклад раз на годину.

Код і штрихкод шукаються так само, як у /products. Потрібен збіг повністю, а регістр літер не важливий.

У /prices немає updated_since. Ціна артикула змінюється від його правки, від акції, нового курсу, зміни валюти вітрини й правки в доповненні «Оптові ціни» версії 1.3.1 і новіших, зокрема щаблів. Такі зміни видно через updated_since у /skus. Інше доповнення цін може не повідомляти магазин про свої правки, і тоді нові ціни через updated_since не прийдуть. Тому звіряйте /prices повністю, гортаючи за after_id. Як часто це робити, описано в розділі «Зміни: updated_since». Якщо власник увімкнув вам повідомлення «Могли змінитися ціни», магазин сам надішле номери артикулів, ціни яких варто перечитати. Як приймати таке повідомлення, описано на сторінці «Повідомлення партнерові (вебхуки)».

Коли ваш контакт переводять до іншої категорії покупців, змінюються ціни всього каталогу. Про це свідчить поле settings_changed_at відповіді GET /api/v1/me. Якщо цей час пізніший за вашу минулу звірку, заберіть ціни заново.

Номери в sku_ids, яких немає або які належать неопублікованим товарам, магазин мовчки пропускає, а повтори рахує один раз. Звіряйте відповідь за полем sku_id.

curl "https://shop.example.ua/api/v1/prices?sku_ids=2108,2109" \
  -H "Authorization: Bearer <ключ>"

{
    "data": [
        {
            "sku_id": 2108,
            "product_id": 1045,
            "sku": "730601",
            "price": "208.32",
            "compare_price": "320.00",
            "discount_percent": 35,
            "currency": "UAH",
            "tiers": []
        },
        {
            "sku_id": 2109,
            "product_id": 1045,
            "sku": "730602",
            "price": "250.00",
            "compare_price": null,
            "discount_percent": null,
            "currency": "UAH",
            "tiers": [
                { "min_quantity": "10.000", "min_packs": null, "price": "225.00", "discount_percent": 10 }
            ]
        }
    ],
    "meta": { "total": 2, "limit": 100, "offset": 0 },
    "links": { "next": null, "prev": null }
}

Повна звірка всіх цін має такий вигляд:

url="https://shop.example.ua/api/v1/prices?after_id=0&limit=200"

while [ "$url" != "null" ]; do
    page=$(curl -s "$url" -H "Authorization: Bearer $CARTIX_KEY")
    echo "$page" | jq -c '.data[] | {sku_id, price, currency}'
    url=$(echo "$page" | jq -r '.links.next')
done