Elbuz забирає замовлення з вашого магазину на Kaspi.kz через API за токеном і перетворює їх на документи, які менеджери обробляють в одній черзі з продажами інших каналів.
Коли це знадобиться:
- Замовлення Kaspi обробляють в окремому кабінеті — вони приходять у список документів Elbuz разом із покупцем і позиціями.
- Покупець замовляє повторно — він збирається в одного контрагента за телефоном.
- Замовлення мають приходити самі — шаблон за розкладом забирає нові з усіх шести станів Kaspi.
- Позиції мають лягати на ваші картки — товар шукається в каталозі за артикулом і назвою.
З чого почати: сформуйте токен у кабінеті Kaspi і вставте його в шаблон «Kaspi» вікна «Завантаження даних».
Що вміє підключення Kaspi
- Замовлення — покупець, телефон, адреса, сума, спосіб оплати й статус лягають у документ «замовлення покупця».
- Позиції — знаходять ваші картки, а незнайомі заводяться у прихованій службовій категорії.
- Статуси — стани й статуси Kaspi зводяться до ваших без налаштування.
- Розклад — кожен прогін забирає нові замовлення без дублів.
Каталог з Kaspi не завантажується: товари приходять лише як рядки замовлень.
Де це і хто має доступ
- Меню
- Операції → Завантаження даних → шаблон типу «Kaspi»
- Право доступу
- вікно «Завантаження» у «Правах груп»
- Підготувати
- токен API з вебверсії кабінету Магазину на Kaspi.kz
Один шаблон — одне підключення до одного магазину Kaspi.
1
Поле «Токен»- Поле «Токен» — сюди вставляють токен API, виданий у кабінеті Kaspi.kz.
Що потрібно від Kaspi
Потрібне одне значення — Токен, ключ доступу до API, який ви формуєте в кабінеті продавця.
Де взяти токен: крок за кроком
| Де | Що зробити |
|---|---|
| Кабінет продавця Kaspi | Увійти у вебверсію кабінету Магазину — за номером телефону й паролем із мобільного застосунку Kaspi Pay |
| Там само | Розділ «Настройки» → вкладка «Токен API» → кнопка «Сформировать» |
| Там само | Скопіювати готовий токен |
| Elbuz | Вікно завантаження → ваш шаблон «Kaspi» → картка «Підключення» → поле «Токен» |
Створити токен може тільки керівник компанії. Повторне формування токен не змінює, тож скопіювати його ще раз можна будь-коли.
У токена Kaspi немає терміну дії. Хто його має, той отримує дані про ваші замовлення й товари: передавайте токен лише тому, хто налаштовує інтеграцію, і не пересилайте у відкритих чатах.
Довідка Kaspi для партнерів: Як отримати токен авторизації в Магазині на Kaspi.kz.
Як підключити крок за кроком
- Створіть шаблон типу «Kaspi» і вставте токен у картці «Підключення». Позначки «завантажувати замовлення» немає: кожен запуск забирає замовлення.
- Збережіть і запустіть. Кнопки «Перевірити підключення» в шаблоні Kaspi немає — чи підійшов токен, видно з журналу.
- Відкрийте кілька замовлень і звірте позиції, суми, покупця й статус.
Що переноситься в замовлення
| Дані Kaspi | Поле документа в Elbuz |
|---|---|
| номер замовлення | Зовнішній номер (за ним замовлення впізнається повторно) |
| ім'я та прізвище покупця | Ім'я, прізвище (з великої літери) |
| ідентифікатор покупця | Прив'язка контрагента до джерела |
| мобільний телефон | Телефон |
| адреса доставки одним рядком | Адреса доставки |
| загальна сума | Сума документа |
| спосіб оплати | Спосіб оплати й тип оплати |
| стан і статус замовлення | Статус документа (див. таблицю статусів) |
| дата створення | Дата замовлення на майданчику |
Пошту Kaspi не передає — лише телефон. Покупець упізнається за телефоном і своїм ідентифікатором у Kaspi, тож повторні замовлення людини збираються в одного контрагента.
Позиції замовлення
Позиції Kaspi віддає окремо: на кожен товар Elbuz робить кілька запитів — перелік рядків, картку товару Kaspi, позицію з вашого прайсу продавця. Тому велика партія замовлень вантажиться помітно довше, ніж здається. З рядка беруться назва, артикул (код позиції у вашому прайсі Kaspi), ціна, кількість і сума рядка.
- Запит або дія
- Відповідь
- loop — повторюється
- Примітка
Kaspi не передає категорію товару. Позиція шукається серед ваших товарів за артикулом разом із назвою або за самою назвою. Не знайшлася — отримує картку у службовій категорії «Товари — kaspi_kz — назва вашого підключення». Категорія прихована й не бере участі у вивантаженнях.
Така картка має лише назву, артикул, ціну й кількість, без опису, фото й характеристик. Щоб службова категорія не заростала, стежте, щоб артикули в прайсі Kaspi збігалися з артикулами в Elbuz. Загальний порядок — як позиції знаходять товар.
Як статуси Kaspi стають вашими
У Kaspi два поняття: стан (де замовлення в процесі — новий, на підписанні, самовивіз, доставка, Kaspi Доставка, архів) і статус (що з ним сталося — схвалено банком, прийнято продавцем, завершено, повернено, скасовано). Обидва зводяться до ваших статусів вбудованим зіставленням:
| Стан або статус у Kaspi | Статус документа в Elbuz |
|---|---|
| новий; схвалено банком | Новий |
| на підписанні; прийнято продавцем | Погодження |
| завершено; архівне замовлення | Виконано |
| повернено | Повернення |
| скасовано | Скасовано |
| очікує скасування | Очікує скасування |
| очікує повернення | Очікує повернення |
| очікує рішення щодо повернення | Очікує рішення щодо повернення |
Покупка в кредит і передоплата лягають у різні типи оплати документа. Статус оплати ставиться «очікування» — фактичну оплату відзначаєте ви.
Кнопки ручного зіставлення в картці «Пов'язані налаштування» зберігають правила для цього шаблону й доповнюють вбудоване зіставлення: спрацьовують лише там, де воно нічого не визначило, — скажімо, для іншого способу оплати чи стану, якого немає в таблиці.
Оновлення за розкладом і глибина історії
Kaspi не надсилає миттєвих сповіщень: Elbuz звертається за розкладом, і розклад визначає, як швидко з'являться нові замовлення. Активному магазину — кільканадцять разів на день. Розклад задають кнопкою «Налаштування розкладу» в картці «Повʼязані налаштування» (сценарій).
Які замовлення забирає прогін
- Шість станів окремими запитами — нові, на підписанні, самовивіз, доставка, Kaspi Доставка, архів. Так і на першому підключенні, і на регулярних запусках, тож замовлення, що між запусками перейшло з «нового» в інший стан, однаково завантажиться.
- Від дати відліку. Її записує кожен стан, з якого прийшли замовлення: найпізніша дата створення серед них. Після запуску в шаблоні лишається дата від останнього за чергою такого стану.
- Не глибше двох тижнів. Перше завантаження бере замовлення приблизно за 14 днів. Простояв розклад місяць — наступний запуск теж візьме лише останні два тижні.
- Уже завантажене не оновлюється. Перехід замовлення в інший стан на Kaspi документ не змінює: далі статус ведете ви в Elbuz.
Підключіть Kaspi якомога раніше й одразу поставте на розклад: історія обмежена двома тижнями, і кожен день зволікання — замовлення, які вже не підтягнуться.
Як перевірити, що завантаження відпрацювало
| Рядок журналу | Що він означає |
|---|---|
| «Запитуємо список замовлень #1 NEW» | Запит однієї сторінки замовлень у стані, назва якого стоїть у кінці рядка. Elbuz просить сторінки по 1000 замовлень. Такі рядки йдуть по черзі для NEW, SIGN_REQUIRED, PICKUP, DELIVERY, KASPI_DELIVERY і ARCHIVE — і на першому підключенні, і на регулярних запусках. |
| «Отримано замовлень: N» | Скільки замовлень Kaspi віддав у цьому стані, разом із тими, що вже є в Elbuz. |
| «Всього товарів завантажено: N» | Скільки нових карток товарів створено для позицій, які не знайшлися у вашому каталозі. Ці картки лягають у службову категорію. |
| «Всього замовлень завантажено: N» | Скільки нових документів створено. |
| «Завантаження даних завершено!» і «Витрачено часу: …» | Прогін дійшов до кінця. Той самий час видно в списку шаблонів, у колонці «Останнє завантаження». |
- Пропущені — різниця між «Отримано замовлень» і «Всього замовлень завантажено»: вони вже є в Elbuz.
- Є «Отримано», немає «Всього замовлень завантажено» — нових документів не створено.
- Немає навіть «Отримано» — Kaspi не віддав замовлень за цей стан і період.
- «Завантаження даних завершено!» не означає, що помилок не було — перегляньте журнал вище (розбір помилок).
У списку документів замовлення Kaspi видно за колонками:
| Колонка | Що в ній для замовлення Kaspi |
|---|---|
| «Джерело: назва» | Назва вашого шаблону Kaspi |
| «Джерело: ID» | Номер цього шаблону |
| «№ документа (сайт)» | Ідентифікатор замовлення, яким його віддав API Kaspi |
| «Статус документа (сайт)» | Статус замовлення в Kaspi кодом, як він прийшов: APPROVED_BY_BANK, ACCEPTED_BY_MERCHANT, COMPLETED тощо |
Сценарії
Почати вести замовлення Kaspi в Elbuz
Що зробити: створіть шаблон типу «Kaspi», вставте токен у поле «Токен» і запустіть завантаження.
Що вийде: Elbuz пройде всі шість станів від дати 14 днів тому. Замовлення стануть документами, покупці — контрагентами, незнайомі позиції — картками у прихованій службовій категорії. Дата відліку записується, лише коли прийшло хоча б одне замовлення; інакше наступний запуск знову почне з 14 днів тому.
Нові замовлення мають з'являтися без ручного запуску
Що зробити: у картці «Повʼязані налаштування» форми шаблону натисніть «Налаштування розкладу» і задайте розклад.
1
Налаштування розкладу- Налаштування розкладу — відкриває окреме вікно розкладу автоматичного завантаження.
Що вийде: кожен запуск запитує шість станів від дати відліку, але не раніше 14 днів тому; наявні замовлення пропускаються. Зміна статусу в Kaspi до створеного документа не дійде.
Позиції мають лягати на ваші картки, а не в службову категорію
Що зробити: назвіть товари в Elbuz так само, як позиції у прайсі продавця Kaspi, і зведіть артикули.
Що вийде: знайдена позиція записується з вашою карткою. Не знайдена отримує картку в службовій категорії, яка запам'ятовує код товару Kaspi, — наступні замовлення з цим товаром ляжуть на неї, без дублів.
Що робити, коли замовлення не приходять
| Що ви бачите | Чому так | Що зробити |
|---|---|---|
| «Не вказано API токен» | Поле «Токен» порожнє | Вставте токен і збережіть шаблон (де взяти) |
| Помилка авторизації від Kaspi | Токен скопійовано з пробілом або без «хвоста»; строку дії в нього немає | Скопіюйте токен заново з вкладки «Токен API» |
| Текст помилки від Kaspi у журналі | Помилка на першій сторінці стану зупиняє прогін без запису цього стану; на наступних — раніші сторінки записуються, прогін іде до наступного стану | Запустіть ще раз — незаписане прийде (обрив прогону) |
| «Kaspi: не вдалося отримати товари замовлення N — сторінку замовлень не збережено, її буде завантажено при наступному запуску.» | Kaspi не віддав дані товару; сторінка не записується, щоб не було документів без позицій | Нічого: наступний запуск забере цю сторінку |
| Немає замовлень за минулий місяць | Історія береться не глибше двох тижнів | Давні замовлення ведіть у кабінеті Kaspi (глибина історії) |
Якщо прогін обірвався
Для кожного стану Elbuz спершу забирає всі сторінки з позиціями в тимчасовий файл, а потім одним проходом записує контрагентів, картки, документи, позиції й наостанок дату відліку. Кожен із шести станів зберігається незалежно. Загальні правила — в огляді.
- Початок або кінець
- Дія або результат
- Розвилка: далі шлях залежить від відповіді
- Зупинка перевіряється перед кожною сторінкою: прийняті сторінки поточного стану зберігаються, наступні стани не запитуються. У журналі «Операція перервана користувачем!», без «Завантаження даних завершено!».
- Обрив до запису дати відліку — наступний запуск почне від старої дати; створені документи впізнаються за ідентифікатором Kaspi.
- Обрив між документом і позиціями лишає документ без товарів, і повтор їх не допише. Видаліть такий документ — новий з'явиться, коли Kaspi знову віддасть це замовлення.
Як прибрати документи помилкового прогону
Відфільтруйте список документів за «Джерело: назва» (або «Джерело: ID») і часом прогону, відмітьте документи й натисніть «Видалити вибрані документи» (загальний порядок відкату).
- Проведені не видаляються: «Проведені документи не видалено (N). Спершу скасуйте проведення.»
- Видалене йде в «Кошик документів»: кнопка «Скасувати» в повідомленні «Видалено документів: N» повертає пачку, кошик зберігає її 30 днів. Якщо колишній внутрішній ідентифікатор документа вже зайнятий, він отримає новий, а номер лишиться.
- Контрагенти й картки товарів не видаляються разом із документами; картки незнайомих позицій лежать у службовій категорії.
- Відновлений документ зберігає ідентифікатор замовлення Kaspi і не задвоїться. Видалене замовлення, що знову прийде з Kaspi, отримає новий документ — на регулярних запусках це замовлення не давніші за дату відліку.
Часті запитання
Чи можна завантажити з Kaspi товари в каталог?
Ні, підключення приносить лише замовлення. Товари приходять рядками замовлень, а незнайомі — картками в службовій категорії (позиції).
Чому не завантажились замовлення за минулий місяць?
Elbuz бере історію не глибше двох тижнів, давніші замовлення не завантажуються.
Замовлення змінилося в Kaspi — чому документ у Elbuz старий?
Уже завантажений документ прогін не оновлює: після завантаження статус ведете ви в Elbuz.
Замовлення з'являються з затримкою — чому?
Kaspi не надсилає миттєвих сповіщень, замовлення приходять на черговому запуску за розкладом. Поставте частіший розклад.
Чому в контрагента з Kaspi немає пошти?
Kaspi пошту не передає — лише телефон. За ним і за ідентифікатором покупця в Kaspi контрагент упізнається повторно.
Суміжні теми
- Якщо замовлення приклеїлося не до того покупця чи товару — завантаження замовлень через API.
- Якщо треба зрозуміти, що буде з даними після обриву прогону, — огляд завантаження даних.
- Якщо продаєте й на українських майданчиках — замовлення з Prom.ua.