Kaspi.kz — маркетплейс №1 у Казахстані. Якщо ви продаєте на ньому, замовлення надходять у ваш кабінет продавця Kaspi; Elbuz забирає їх напряму через API й перетворює на документи, з якими працюють ваші менеджери. Так замовлення Kaspi опиняються в одній черзі обробки разом із продажами з інших каналів, а не в окремому кабінеті.
Ця стаття — про підключення саме Kaspi. Загальний порядок для всіх систем із замовленнями описано в огляді імпорту замовлень через API; тут — особливості Kaspi: який ключ потрібен, як іде перше завантаження і що з зіставленням статусів. Kaspi приносить лише замовлення — каталог з нього не завантажується, товари приходять як рядки самих замовлень.
Де це у програмі
У вікні імпорту створіть шаблон і оберіть тип «Kaspi». Це API-джерело: файл не потрібен, підключення відбувається за токеном. Один шаблон — одне підключення до одного магазину Kaspi.
1
Поле «Токен»- Поле «Токен» — сюди вставляють токен API, виданий у кабінеті Kaspi.kz.
Що потрібно для підключення
Для Kaspi потрібне лише одне значення — Токен. Це ключ доступу до API, який ви формуєте самі в кабінеті продавця. Вставляєте його в поле «Токен» у картці «Підключення» — і цього достатньо.
Де взяти токен: крок за кроком
| Де | Що зробити |
|---|---|
| Кабінет продавця Kaspi | Увійти у вебверсію кабінету Магазину — за номером телефону й паролем із мобільного застосунку Kaspi Pay |
| Там само | Розділ «Настройки» → вкладка «Токен API» → кнопка «Сформировать» |
| Там само | Скопіювати готовий токен |
| Elbuz | Вікно завантаження → ваш шаблон «Kaspi» → картка «Підключення» → поле «Токен» |
Створити токен може тільки керівник компанії — в інших співробітників такої кнопки не буде. Формувати його можна в будь-який момент: токен при цьому не змінюється, тож подивитися й скопіювати його повторно завжди можна.
У токена Kaspi немає терміну дії — він працює, доки ви ним користуєтесь. Зворотний бік: будь-хто, у кого він опиниться, зможе отримувати дані про ваші замовлення й товари. Тому передавайте його лише технічному спеціалісту, який налаштовує інтеграцію, і не пересилайте у відкритих чатах.
Довідка Kaspi для партнерів: Як отримати токен авторизації в Магазині на Kaspi.kz.
Як підключити крок за кроком
Створіть шаблон типу «Kaspi». Вставте токен у картці «Підключення». Переконайтесь, що ввімкнено завантаження замовлень. Збережіть і запустіть. Перше підключення забере наявні замовлення, наступні — лише нові й змінені. Радимо перший запуск перевірити очима: відкрийте кілька завантажених замовлень і звірте позиції, суми, покупця й статус.
Що приходить із замовленням: маппінг полів
Із кожного замовлення Kaspi Elbuz бере ось що:
| Дані Kaspi | Поле документа в Elbuz |
|---|---|
| номер замовлення | Зовнішній номер (за ним замовлення впізнається повторно) |
| ім'я та прізвище покупця | Ім'я, прізвище (з великої літери) |
| ідентифікатор покупця | Прив'язка контрагента до джерела |
| мобільний телефон | Телефон |
| адреса доставки одним рядком | Адреса доставки |
| загальна сума | Сума документа |
| спосіб оплати | Спосіб оплати й тип оплати |
| стан і статус замовлення | Статус документа (див. таблицю нижче) |
| дата створення | Дата замовлення на майданчику |
Зверніть увагу: пошту Kaspi не передає — у замовленні є лише телефон. Тому покупець упізнається за телефоном і за своїм ідентифікатором у Kaspi; саме за ними повторні замовлення тієї самої людини збираються в одного контрагента, а не плодять дублі.
Позиції замовлення
Позиції Kaspi віддає не разом із замовленням, а окремо: на кожен товар Elbuz робить кілька додаткових запитів — спершу перелік рядків замовлення, потім картку товару Kaspi, потім позицію з вашого прайсу продавця. Через це завантаження великої партії замовлень помітно повільніше, ніж могло б здаватися: запитів виходить у рази більше, ніж самих замовлень. З кожного рядка беруться назва, артикул (код позиції у вашому прайсі Kaspi), ціна, кількість і сума рядка.
Kaspi не передає категорію товару. Тому позиція спершу шукається серед ваших товарів — за артикулом разом із назвою або за самою назвою, — а якщо не знайшлася, для неї створюється картка у службовій категорії виду «Товари — kaspi — назва вашого підключення». Категорія прихована й не бере участі у вивантаженнях, тож такі картки не поїдуть на ваші канали продажу випадково.
Картка з рядка замовлення містить лише назву, артикул, ціну й кількість — без опису, фото й характеристик. Практичний висновок: тримайте каталог заповненим і стежте, щоб артикули в прайсі Kaspi збігалися з артикулами товарів в Elbuz — тоді позиції зіставляються з наявними картками, а службова категорія не заростає напівпорожніми дублікатами. Докладніше про порядок зіставлення — в огляді імпорту замовлень через API.
На основі цих даних створюється документ — замовлення покупця, — з яким далі працюють ваші менеджери: підтверджують, комплектують, відвантажують. Покупець із замовлення заводиться у вашу базу контрагентів, тож історія його покупок збирається в одному місці, а не лишається розкиданою по кабінету маркетплейсу.
Перше завантаження і період
Перше підключення Kaspi відрізняється від подальших, і різниця істотна. Першого разу Elbuz проходить по всіх шести станах замовлень окремими запитами — нові, на підписанні, самовивіз, доставка, Kaspi Доставка та архів, — щоб підтягнути повну поточну картину. Далі, на регулярних оновленнях, забираються замовлення у стані «новий»: саме вони щойно з'явилися й потребують обробки.
Із цього випливає практичний наслідок: коли замовлення на боці Kaspi переходить у наступний стан (скажімо, у доставку), регулярне оновлення його вже не перечитує — далі його статус ведете ви у себе в Elbuz. Це логічно для роботи: замовлення потрапило до вас новим, і саме ви рухаєте його по своїх статусах, а не чекаєте, поки маркетплейс повідомить.
Важлива деталь: Elbuz бере історію максимум за два тижні назад — цей запобіжник діє і на перше завантаження, і на всі наступні. Тобто перше завантаження підтягне замовлення приблизно за останні 14 днів, а не за весь час існування магазину. Так само, якщо шаблон довго не запускався (скажімо, місяць), наступний запуск однаково візьме лише останні два тижні, а глибший проміжок лишиться незавантаженим. Тому не варто відкладати перше підключення й не варто надовго вимикати розклад — що регулярніші запуски, то повніша історія в Elbuz.
Статуси і їх зіставлення
У Kaspi два різні поняття: стан замовлення (де воно в процесі — новий, на підписанні, самовивіз, доставка, Kaspi Доставка, архів) і статус (що з ним сталося — схвалено банком, прийнято продавцем, завершено, повернено, скасовано). Elbuz зводить обидва до ваших статусів, і це зіставлення вбудоване в саме підключення:
| Стан або статус у Kaspi | Статус документа в Elbuz |
|---|---|
| новий; схвалено банком | Новий |
| на підписанні; прийнято продавцем | Погодження |
| завершено; архівне замовлення | Виконано |
| повернено | Повернення |
| скасовано | Скасовано |
| очікує скасування | Очікує скасування |
| очікує повернення | Очікує повернення |
| очікує рішення щодо повернення | Очікує рішення щодо повернення |
Тип оплати теж визначається одразу: покупка в кредит і передоплата Kaspi розрізняються й лягають у різні типи оплати документа. Статус оплати за замовчуванням ставиться «очікування» — фактичну оплату ви відзначаєте вже у себе.
У картці «Пов'язані налаштування» є кнопки ручного зіставлення статусів і видів оплати та доставки. Для Kaspi важливо розуміти порядок: спочатку спрацьовує вбудоване зіставлення з таблиці вище, і лише те, для чого відповідності не знайшлося, добирається з ваших ручних правил. Тобто ручна таблиця не перевизначає вбудовані статуси, а доповнює їх для випадків, яких у переліку немає.
Розклад і оновлення
Kaspi працює поллінгом: Elbuz сам звертається до нього за розкладом і забирає свіжі замовлення — вебхука (миттєвого сповіщення) тут немає. Тому саме розклад визначає, наскільки швидко нові замовлення з'являться в Elbuz. Для активного магазину має сенс перевіряти часто — кільканадцять разів на день. Розклад задають кнопкою налаштування завдання прямо у формі шаблону. Elbuz веде інкремент за датою й номером останнього замовлення, тож повторно те саме не тягнеться.
Навіщо зводити замовлення Kaspi в Elbuz
Кабінет Kaspi добре показує замовлення самого Kaspi, але якщо ви продаєте ще десь, продажі опиняються в різних місцях. Звівши замовлення Kaspi в Elbuz, ви обробляєте їх в одній черзі разом з іншими каналами: списання зі складу, облік покупців, єдині статуси, друк документів. Менеджеру не треба тримати окрему вкладку Kaspi — усі замовлення в одному списку.
Часті труднощі
Найчастіша причина, чому замовлення не приходять, — токен. Перевірте, що він скопійований повністю: без зайвих пробілів на початку чи в кінці й без обрізаного «хвоста» — саме на цьому спотикаються найчастіше. Термін дії у токена Kaspi не обмежений, тож «протухнути» він не може; якщо в журналі помилка авторизації, поверніться в кабінет, скопіюйте токен заново з вкладки «Токен API» і вставте ще раз.
Друга типова ситуація — «не бачу старих замовлень». Це не помилка: Kaspi віддає історію приблизно за два тижні, тож замовлення давніші за цей період через API не приходять. Працюйте з ними в кабінеті Kaspi, а Elbuz нехай веде все нове з моменту підключення. Якщо ж нові замовлення приходять, а якесь одне «загубилось», перевірте його стан у кабінеті: можливо, воно в тому стані, який на регулярних оновленнях уже не забирається (беруться переважно нові) — тоді досить дочекатися, доки воно перейде в актуальний робочий статус.
Підключіть Kaspi якомога раніше й одразу поставте на розклад: оскільки історія обмежена двома тижнями, кожен день зволікання — це замовлення, які в Elbuz уже не підтягнуться. А от нове піде повністю, щойно шаблон запрацює.
Що далі із завантаженими замовленнями
Завантажити замовлення — це початок. Далі вони живуть у Elbuz як документи «замовлення покупця», і з ними працюють як зі звичайними: підтверджують, резервують і списують товар зі складу, оформлюють доставку й друкують документи, ведуть покупця в базі контрагентів. Якщо ви тільки починаєте знайомство з системою, орієнтуйтеся на загальну карту дій — з чого почати і куди рухатися: там показано весь робочий цикл в Elbuz.
Коли Kaspi — не єдиний ваш канал, його замовлення сходяться в один список разом з іншими майданчиками, і менеджер обробляє їх однаково. Загальні принципи роботи із замовленнями з різних систем описано в огляді імпорту замовлень через API — Kaspi підпорядковується тому самому порядку, з поправкою на свій дволанковий перший імпорт і обмеження історії двома тижнями.
Часті питання
Де взяти токен Kaspi?
Токен видає сам Kaspi в кабінеті продавця, у розділі налаштувань магазину / інтеграцій. Ви вставляєте його в поле «Токен» у формі шаблону — це єдине, що потрібно для підключення.
Чи можна завантажити з Kaspi товари в каталог?
Ні. Kaspi у Elbuz приносить лише замовлення; товари приходять як рядки замовлень. Каталог з Kaspi через це підключення не завантажується. Kaspi не передає й категорію товару, тому невідомі позиції потрапляють у приховану службову категорію «Товари — kaspi — назва підключення» окремими картками (лише назва, артикул, ціна, кількість). Їх варто перенести у правильну гілку каталогу й дозаповнити.
Чому не завантажились замовлення за минулий місяць?
Kaspi віддає замовлення за обмежений період, і Elbuz бере історію максимум за два тижні назад. Давніші замовлення через API не приходять — це обмеження джерела, а не Elbuz.
Як налаштувати відповідність статусів?
Базове зіставлення вже вбудоване. Для тонкого налаштування у формі шаблону є кнопки: статус замовлення, статус доставки, статус оплати, тип оплати й тип доставки — там ви задаєте, який зовнішній статус відповідає якому вашому.
Замовлення з'являються з затримкою — чому?
Kaspi працює поллінгом, без миттєвих сповіщень, тож нові замовлення підтягуються під час чергового запуску за розкладом. Щоб затримка була меншою, поставте частіший розклад.