Elbuz pobiera zamówienia z Twojego sklepu na Kaspi.kz przez API za pomocą tokena i zamienia je w dokumenty, które menedżerowie obsługują we wspólnej kolejce ze sprzedażą z innych kanałów.
Kiedy to się przyda:
- Zamówienia Kaspi obsługujesz w osobnym koncie — trafiają na listę dokumentów Elbuz razem z klientem i pozycjami.
- Klient zamawia ponownie — jest łączony w jednego kontrahenta po numerze telefonu.
- Zamówienia mają przychodzić same — Elbuz co 5 minut pobiera nowe ze wszystkich sześciu stanów Kaspi.
- Pozycje mają trafiać na Twoje karty — produkt jest szukany w katalogu po kodzie produktu i nazwie.
Od czego zacząć: wygeneruj token w koncie Kaspi i wklej go w szablon „Kaspi” okna „Import danych”.
Co potrafi połączenie z Kaspi
- Zamówienia — klient, telefon, adres, kwota, sposób płatności i status trafiają do dokumentu „Zamówienie klienta”.
- Pozycje — znajdują Twoje karty, a nieznane są zakładane w ukrytej kategorii technicznej.
- Statusy — stany i statusy Kaspi zamieniają się na Twoje bez konfiguracji.
- Harmonogram — każdy przebieg pobiera nowe zamówienia bez duplikatów.
Katalog z Kaspi nie jest importowany: produkty przychodzą tylko jako wiersze zamówień.
Czego potrzeba od Kaspi
Potrzebna jest jedna wartość — Token, klucz dostępu do API, który generujesz w koncie sprzedawcy.
Skąd wziąć token: krok po kroku
| Gdzie | Co zrobić |
|---|---|
| Konto sprzedawcy Kaspi | Zaloguj się do wersji webowej konta Sklepu — numerem telefonu i hasłem z aplikacji mobilnej Kaspi Pay |
| Tamże | Sekcja «Настройки» (Ustawienia) → karta «Токен API» → przycisk «Сформировать» (Wygeneruj) |
| Tamże | Skopiuj gotowy token |
| Elbuz | Okno importu → Twój szablon „Kaspi” → karta „Połączenie” → pole „Token” |
Token może utworzyć tylko kierownik firmy. Ponowne generowanie nie zmienia tokena, więc skopiować go jeszcze raz można w każdej chwili.
Token Kaspi nie ma terminu ważności. Kto go ma, ten dostaje dane o Twoich zamówieniach i produktach: przekazuj token tylko osobie, która konfiguruje integrację, i nie wysyłaj go na otwartych czatach.
Pomoc Kaspi dla partnerów: Jak uzyskać token autoryzacji w Sklepie na Kaspi.kz.
Jak połączyć krok po kroku
- Utwórz szablon typu „API - kaspi.kz”. Pola „Importuj zamówienia” nie ma: każde uruchomienie pobiera zamówienia. Chcesz najpierw sprawdzić — przełącz plakietkę „Aktywny” na „Wyłączony”.
- Wklej token w karcie „Połączenie”. Formularz zapisuje się sam, przycisku zapisu nie ma: w aktywnym szablonie zwykle w ciągu 5 minut Elbuz sam zacznie pobierać zamówienia — do 14 dni wstecz. Nie chcesz czekać — kliknij „Importuj”. Przycisku „Sprawdź połączenie” w szablonie Kaspi nie ma — czy token pasuje, widać w dzienniku.
- Otwórz kilka zamówień i porównaj pozycje, kwoty, klienta i status.
Co trafia do zamówienia
| Dane Kaspi | Pole dokumentu w Elbuz |
|---|---|
| numer zamówienia | Numer zewnętrzny (po nim zamówienie jest rozpoznawane ponownie) |
| imię i nazwisko klienta | Imię, nazwisko (wielką literą) |
| identyfikator klienta | Powiązanie kontrahenta ze źródłem |
| telefon komórkowy | Telefon |
| adres dostawy w jednym wierszu | Adres dostawy |
| kwota łączna | Kwota dokumentu |
| sposób płatności | Sposób płatności i typ płatności |
| stan i status zamówienia | Status dokumentu (zob. tabelę statusów) |
| data utworzenia | Data zamówienia na marketplace |
Kaspi nie przekazuje e-maila — tylko telefon. Klient jest rozpoznawany po telefonie i swoim identyfikatorze w Kaspi, więc kolejne zamówienia tej samej osoby łączą się w jednego kontrahenta.
Pozycje zamówienia
Pozycje Kaspi zwraca osobno: dla każdego produktu Elbuz wysyła kilka zapytań — listę wierszy, kartę produktu Kaspi, pozycję z Twojego cennika sprzedawcy. Dlatego duża partia zamówień importuje się wyraźnie dłużej, niż się wydaje. Z wiersza brane są nazwa, kod produktu (kod pozycji w Twoim cenniku Kaspi), cena, ilość i kwota wiersza.
- Запит або дія
- Відповідь
- loop — повторюється
- Примітка
Kaspi nie przekazuje kategorii produktu. Pozycja jest szukana wśród Twoich produktów po kodzie produktu razem z nazwą albo po samej nazwie. Jeśli się nie znajdzie — dostaje kartę w kategorii technicznej „Produkty — kaspi_kz — nazwa Twojego połączenia”. Kategoria jest ukryta i nie bierze udziału w eksportach.
Taka karta ma tylko nazwę, kod produktu, cenę i ilość, bez opisu, zdjęć i cech. Żeby kategoria techniczna się nie rozrastała, pilnuj, aby kody produktów w cenniku Kaspi zgadzały się z kodami w Elbuz. Ogólna kolejność — jak pozycje znajdują produkt.
Jak statusy Kaspi stają się Twoimi
Kaspi ma dwa pojęcia: stan (gdzie zamówienie jest w procesie — nowe, do podpisania, odbiór osobisty, dostawa, Kaspi Dostawa, archiwum) i status (co się z nim stało — zatwierdzone przez bank, przyjęte przez sprzedawcę, zakończone, zwrócone, anulowane). Oba zamieniają się na Twoje statusy wbudowanym dopasowaniem:
| Stan lub status w Kaspi | Status dokumentu w Elbuz |
|---|---|
| nowe; zatwierdzone przez bank | Nowy |
| do podpisania; przyjęte przez sprzedawcę | Uzgodnienie |
| zakończone; zamówienie archiwalne | Zrealizowano |
| zwrócone | Zwrócono |
| anulowane | Anulowano |
| oczekuje na anulowanie | Oczekuje na anulowanie |
| oczekuje na zwrot | Oczekuje na zwrot |
| oczekuje na decyzję o zwrocie | Oczekuje na decyzję o zwrocie |
Zakup na kredyt i przedpłata trafiają do różnych typów płatności dokumentu. Status płatności to „Oczekiwanie” — faktyczną płatność oznaczasz Ty.
Przyciski ręcznego dopasowania w karcie „Powiązane ustawienia” zapisują reguły dla tego szablonu i uzupełniają wbudowane dopasowanie: działają tylko tam, gdzie ono niczego nie ustaliło — na przykład dla innego sposobu płatności albo stanu, którego nie ma w tabeli.
Automatyczny import i głębokość historii
Kaspi nie wysyła natychmiastowych powiadomień, więc Elbuz odpytuje go sam: zadanie systemowe „Zamówienia z marketplace’ów” co 5 minut pobiera zamówienia ze wszystkich aktywnych szablonów Kaspi z tokenem. Harmonogram szablonu nie jest potrzebny, interwał zmienia się w oknie „Harmonogram zadań”, w wierszu tego zadania (scenariusz). Jeśli w tej minucie importuje się inny szablon, także ręcznie, przebieg jest po cichu pomijany, a zamówienia pobierze następny.
Które zamówienia pobiera przebieg
- Sześć stanów osobnymi zapytaniami — nowe, do podpisania, odbiór osobisty, dostawa, Kaspi Dostawa, archiwum. Tak jest i przy pierwszym połączeniu, i przy regularnych uruchomieniach, więc zamówienie, które między uruchomieniami przeszło z „nowego” w inny stan, i tak się zaimportuje.
- Od daty odniesienia, ale co najmniej z 7 dni. Datę zapisuje każdy stan, z którego przyszły zamówienia: najpóźniejszą datę utworzenia wśród nich. Przebieg bierze wcześniejszą z dwóch — ją albo datę sprzed tygodnia.
- Nie głębiej niż dwa tygodnie. Pierwszy import bierze zamówienia z około 14 dni. Jeśli szablon był wyłączony przez miesiąc, kolejne uruchomienie też weźmie tylko ostatnie dwa tygodnie.
- Statusy już zaimportowanych się aktualizują — w zamówieniach, które trafiły w okno przebiegu. Twój status zmienia się dopiero po nowej zmianie na Kaspi — kto kogo nadpisuje.
Połącz Kaspi jak najwcześniej: historia jest ograniczona do dwóch tygodni, a każdy dzień zwłoki to zamówienia, które już się nie pobiorą.
Jak sprawdzić, że import się udał
| Wiersz dziennika | Co oznacza |
|---|---|
| „Pobieranie listy zamówień #1 NEW” | Zapytanie o jedną stronę zamówień w stanie, którego nazwa stoi na końcu wiersza. Elbuz prosi o strony po 1000 zamówień. Takie wiersze idą po kolei dla NEW, SIGN_REQUIRED, PICKUP, DELIVERY, KASPI_DELIVERY i ARCHIVE — i przy pierwszym połączeniu, i przy regularnych uruchomieniach. |
| „Pobrano zamówień: N” | Ile zamówień Kaspi zwrócił w tym stanie, łącznie z tymi, które już są w Elbuz. |
| „Łącznie zaimportowano produktów: N” | Ile nowych kart produktów utworzono dla pozycji, których nie znaleziono w Twoim katalogu. Te karty trafiają do kategorii technicznej. |
| „Łącznie zaimportowano zamówień: N” | Ile nowych dokumentów utworzono. |
| „Import danych zakończony!” i „Czas wykonania: …” | Przebieg doszedł do końca. Ten sam czas widać na liście szablonów, w kolumnie „Ostatni import”. |
- Pominięte — różnica między „Pobrano zamówień” a „Łącznie zaimportowano zamówień”: te już są w Elbuz.
- Jest „Pobrano”, nie ma „Łącznie zaimportowano zamówień” — nowych dokumentów nie utworzono.
- Nie ma nawet „Pobrano” — Kaspi nie zwrócił zamówień dla tego stanu i okresu.
- „Import danych zakończony!” nie oznacza, że nie było błędów — przejrzyj dziennik wyżej (omówienie błędów).
Na liście dokumentów zamówienia Kaspi rozpoznasz po kolumnach:
| Kolumna | Co w niej jest dla zamówienia Kaspi |
|---|---|
| „Źródło: nazwa” | Nazwa Twojego szablonu Kaspi |
| „Źródło: ID” | Numer tego szablonu |
| „Nr dokumentu (sklep)” | Identyfikator zamówienia, z jakim zwróciło je API Kaspi |
| „Status dokumentu (sklep)” | Status zamówienia w Kaspi jako kod, w takiej postaci, w jakiej przyszedł: APPROVED_BY_BANK, ACCEPTED_BY_MERCHANT, COMPLETED itd. |
Scenariusze
Zacząć prowadzić zamówienia Kaspi w Elbuz
Co zrobić. Utwórz szablon typu „API - kaspi.kz”, wklej token w pole „Token” i uruchom import.
Efekt. Elbuz przejdzie wszystkie sześć stanów od daty sprzed 14 dni. Zamówienia staną się dokumentami, klienci — kontrahentami, nieznane pozycje — kartami w ukrytej kategorii technicznej. Data odniesienia zapisuje się tylko wtedy, gdy przyszło choć jedno zamówienie; w przeciwnym razie kolejne uruchomienie znów zacznie od 14 dni wstecz.
Nowe zamówienia mają pojawiać się bez ręcznego uruchamiania
Co zrobić. Nic poza tokenem i stanem „Aktywny”. W karcie „Powiązane ustawienia” przypomina o tym podpowiedź — przycisku „Ustawienia harmonogramu” tam nie ma.
1
Automatyczny import- Automatyczny import — Elbuz sam pobiera zamówienia Kaspi co 5 minut, więc szablon nie potrzebuje własnego harmonogramu.
Efekt. Co 5 minut przebieg odpytuje sześć stanów co najmniej z 7 dni, nie głębiej niż 14: nowe stają się dokumentami, w już zaimportowanych aktualizują się statusy.
Pozycje mają trafiać na Twoje karty, a nie do kategorii technicznej
Co zrobić. Nazwij produkty w Elbuz tak samo jak pozycje w cenniku sprzedawcy Kaspi i ujednolić kody produktów.
Efekt. Znaleziona pozycja zapisuje się z Twoją kartą. Nieznaleziona dostaje kartę w kategorii technicznej, która zapamiętuje kod produktu Kaspi, — kolejne zamówienia z tym produktem trafią na nią, bez duplikatów.
Co zrobić, gdy zamówienia nie przychodzą
| Co widzisz | Dlaczego tak jest | Co zrobić |
|---|---|---|
| „Nie podano tokenu API” | Pole „Token” jest puste | Wklej token — formularz zapisze się sam (skąd go wziąć) |
| Błąd autoryzacji od Kaspi | Token skopiowano ze spacją albo bez końcówki; terminu ważności nie ma | Skopiuj token od nowa z karty «Токен API» |
| Treść błędu od Kaspi w dzienniku | Błąd na pierwszej stronie stanu zatrzymuje przebieg bez zapisu tego stanu; na kolejnych — wcześniejsze strony się zapisują, a przebieg idzie do następnego stanu | Uruchom jeszcze raz — niezapisane przyjdzie (przerwanie przebiegu) |
| „Kaspi: nie udało się pobrać pozycji zamówienia N — strony zamówień nie zapisano, zostanie pobrana przy następnym uruchomieniu.” | Kaspi nie zwrócił danych produktu; strona nie jest zapisywana, żeby nie było dokumentów bez pozycji | Nic: kolejne uruchomienie pobierze tę stronę |
| Brak zamówień z poprzedniego miesiąca | Historia jest pobierana nie głębiej niż dwa tygodnie | Starsze zamówienia prowadź w koncie Kaspi (głębokość historii) |
Jeśli przebieg się przerwał
Dla każdego stanu Elbuz najpierw pobiera wszystkie strony z pozycjami do pliku tymczasowego, a potem jednym przejściem zapisuje kontrahentów, karty, dokumenty, pozycje i na końcu datę odniesienia. Każdy z sześciu stanów zapisuje się niezależnie. Ogólne zasady — w przeglądzie.
- Початок або кінець
- Дія або результат
- Розвилка: далі шлях залежить від відповіді
- Zatrzymanie jest sprawdzane przed każdą stroną: przyjęte strony bieżącego stanu się zapisują, kolejne stany nie są pobierane. W dzienniku „Operacja przerwana przez użytkownika!”, bez „Import danych zakończony!”.
- Przerwanie przed zapisem daty odniesienia — kolejne uruchomienie zacznie od starej daty; utworzone dokumenty są rozpoznawane po identyfikatorze Kaspi.
- Przerwanie między dokumentem a pozycjami zostawia dokument bez produktów, a powtórka ich nie dopisze. Usuń taki dokument — nowy pojawi się, gdy Kaspi znów zwróci to zamówienie.
Jak usunąć dokumenty z błędnego przebiegu
Przefiltruj listę dokumentów po „Źródło: nazwa” (lub „Źródło: ID”) i czasie przebiegu, zaznacz dokumenty i kliknij „Usuń zaznaczone dokumenty” (ogólne zasady wycofywania).
- Zatwierdzone nie są usuwane: „Nie usunięto zatwierdzonych dokumentów (N). Najpierw anuluj zatwierdzenie.”
- Usunięte trafia do „Kosza dokumentów”: przycisk „Cofnij” w komunikacie „Usunięto dokumentów: N” przywraca paczkę, a kosz przechowuje ją 30 dni. Jeśli dawny wewnętrzny identyfikator dokumentu jest już zajęty, dokument dostanie nowy, a numer zostanie.
- Kontrahenci i karty produktów nie są usuwani razem z dokumentami; karty nieznanych pozycji leżą w kategorii technicznej.
- Przywrócony dokument zachowuje identyfikator zamówienia Kaspi i się nie zdubluje. Usunięte zamówienie, które znowu przyjdzie z Kaspi, dostanie nowy dokument — przy regularnych uruchomieniach dotyczy to zamówień nie starszych niż data odniesienia.
Najczęstsze pytania
Czy można zaimportować z Kaspi produkty do katalogu?
Nie, połączenie przynosi tylko zamówienia. Produkty przychodzą jako wiersze zamówień, a nieznane — jako karty w kategorii technicznej (pozycje).
Dlaczego nie zaimportowały się zamówienia z poprzedniego miesiąca?
Elbuz bierze historię nie głębiej niż dwa tygodnie, starsze zamówienia nie są importowane.
Zamówienie zmieniło się w Kaspi — dlaczego dokument w Elbuz jest nieaktualny?
Przebieg odczytuje zamówienia co najmniej z 7 dni i nie głębiej niż z 14 — starszym status się nie zaktualizuje. Twój status zmienia się dopiero po nowej zmianie na Kaspi (kto kogo nadpisuje).
Zamówienia pojawiają się z opóźnieniem — dlaczego?
Kaspi nie wysyła natychmiastowych powiadomień: Elbuz pobiera zamówienia co 5 minut, więc opóźnienie to zwykle do 5 minut. Dłuższe bywa, gdy w tym momencie trwał inny import, także ręczny: przebieg jest pomijany do następnego.
Dlaczego kontrahent z Kaspi nie ma e-maila?
Kaspi nie przekazuje e-maila — tylko telefon. Po nim i po identyfikatorze klienta w Kaspi kontrahent jest rozpoznawany ponownie.
Gdzie to jest i kto ma dostęp
- Menu
- Słowniki → Operacje → Import danych → szablon typu „API - kaspi.kz”
- Uprawnienia
- okno „Import” w „Uprawnieniach grup”
- Przygotuj
- token z wersji webowej konta Sklepu na Kaspi.kz
Jeden szablon — jedno połączenie z jednym sklepem Kaspi.
1
Pole Token- Pole Token — jedyne ustawienie połączenia; wklej tu token API Kaspi.
Powiązane tematy
- Jeśli zamówienie przypisało się do niewłaściwego klienta lub produktu — import zamówień przez API.
- Jeśli chcesz zrozumieć, co stanie się z danymi po przerwaniu przebiegu, — przegląd importu danych.
- Jeśli sprzedajesz też na ukraińskich marketplace’ach — zamówienia z Prom.ua.
