Integracja custom store: end-to-end
Dokumentacja poglądowa. Interfejs jest w trakcie udostępniania — przykłady mają charakter zapowiedzi, a finalne wartości potwierdzimy przy starcie.
Ten przewodnik prowadzi Cię od pustego sklepu do pierwszych potwierdzonych
wyników rozmów — w pięciu krokach. Integracja custom store opiera się w całości
na publicznym Commerce API: Ty wysyłasz katalog, klientów i intencje ponownego
zakupu (repurchase intent), a my zwracamy dyspozycje i finalny stan zamówienia.
Base URL wszystkich wywołań to https://api.callbotagent.ai/api/v1/commerce.
Zanim zaczniesz
Do integracji potrzebujesz klucza API (w panelu i w przykładach zawsze
maskowany: cba_test_••••••••) oraz scope adekwatnych do operacji, które
wykonujesz. Każde żądanie podpisujesz (HMAC v1) — szczegóły znajdziesz w
rozdziale Uwierzytelnianie. Kolejność ma znaczenie:
najpierw katalog i klienci, dopiero potem zamówienia — bot nie zaproponuje
produktu ani nie zadzwoni do klienta, których nie potrafi zweryfikować.
Przepływ end-to-end
Zsynchronizuj katalog
POST /products/batch — wyślij katalog ze stabilnymi external ID, dostępnością,
walutą i kategoriami. Bot nie zaproponuje produktu, którego nie może
zweryfikować w Twoim katalogu, dlatego kompletny i aktualny feed to fundament
całej integracji.
Dodaj klientów ze zgodą
PUT /customers/{externalCustomerId} — przekaż telefon w formacie E.164,
locale oraz dowód zgody na kontakt. Rekordy bez ważnej zgody nie trafiają do
kolejki dzwonienia — to warunek konieczny, nie opcja.
Prześlij intencje ponownego zakupu
POST /orders z order_kind=repurchase_intent, przewidywaną datą kontaktu w
contact_not_before, jawnymi pozycjami i cenami. Intencje pojawiają się w
panelu jako zamówienia — nigdy jako anonimowe kontakty sprzedażowe.
Polityka właściciela ma pierwszeństwo
Kraje, godziny i dni dzwonienia, polityka retry, listy DNC oraz budżet właściciela sklepu zawsze wygrywają. Dane partnera mogą politykę zawęzić (np. węższe okno kontaktu), ale nigdy jej nie poluzują.
Odbierz wyniki
Konsumuj podpisane webhooki albo odpytuj GET /orders/{externalOrderId}/result.
W final_order_snapshot znajdziesz finalny stan rozmowy: potwierdzone, zmienione
lub odrzucone produkty i ceny.
Mapowanie pól
Poniżej najczęstsze odwzorowania z modelu Twojej platformy na pola Commerce API.
| Twoja platforma | Commerce API |
|---|---|
| Merchant / rynek | Jeden sklep + connector custom |
| Przewidywanie ponownego zakupu | order_kind=repurchase_intent |
| Przewidywana data kontaktu | contact_not_before |
| Pewność / score przewidywania | priority / confidence |
| Finalna decyzja po rozmowie | final_order_snapshot |
Jeśli Twoja platforma rozróżnia wiele rynków lub kont sprzedażowych, wszystkie mapują się na jeden sklep obsługiwany przez connector custom — segmentację zachowujesz w external ID i metadanych, nie w osobnych integracjach.
Profile partnerów na platformie custom
Partnerzy przewidujący ponowne zakupy korzystają z tego samego Commerce API co każdy inny custom store. Nie ma dla nich osobnego endpointu ani osobnej platformy — różni je jedynie sposób, w jaki mapują swoje dane na pola kontraktu.
Przykładowy profil partnera
Przykładowy partner działający na platformie custom przekazuje dane tym samym Commerce API, co w krokach powyżej — nie jest to osobna integracja ani osobny kanał. W praktyce oznacza to następujące odwzorowanie:
- przewidywanie ponownego zakupu →
order_kind=repurchase_intent, - przewidywana data kolejnego zakupu →
contact_not_before, - pewność przewidywania →
priority/confidence.
Katalog, klienci ze zgodą, pierwszeństwo polityki właściciela oraz odbiór wyników działają identycznie jak dla każdego innego custom store. Dzięki temu profil partnera to wyłącznie warstwa mapowania — reszta przepływu pozostaje bez zmian.