Promocje - integracja z systemami zewnętrznymi

Artykuł opisuje, jak system zewnętrzny (sklep internetowy, aplikacja, ERP) pobiera promocje klienta z AMPER i jak należy je interpretować.

Skąd pobrać promocje

GET https://{amper_ws_url}/external/v1/promotions/?api_key={amper_api_key}

Uwierzytelnienie, paginacja (limit, offset) i limity zapytań działają tak samo jak w całym API zewnętrznym. Promocje mają rozbudowaną strukturę, więc pobieraj je stronami (np. limit=50) i nie wysyłaj więcej niż 3 zapytań jednocześnie.

Lista zawiera tylko promocje, które jednocześnie:

trwają w chwili zapytania (data start już minęła, end jeszcze nie) i są włączone,
są przeznaczone dla B2B,
obejmują klienta przypisanego do klucza API – bezpośrednio albo przez kategorię klienta (i nie wykluczają go),
mają co najmniej jedną nagrodę typu stała cena.

Ważne: API zwraca wyłącznie nagrody typu stała cena (cena promocyjna produktu). Gratisy, upusty procentowe i kwotowe – również na cały koszyk – nie są udostępniane przez to API. Jeśli promocja ma także takie nagrody, w odpowiedzi zobaczysz tylko jej nagrody ze stałą ceną.

1. Struktura promocji

Każdy element listy to jedna promocja:

{
  "id": 22960679,
  "name": "Promocja na paletę",
  "description": "",
  "start": "2025-10-23T00:00:00+02:00",
  "end": "2028-10-20T23:59:00+02:00",
  "short_code": "promocja-na-palete",
  "default_image": { "image": "https://.../promo.jpg", "alt": "Promocja na paletę" },
  "keep_bundle_multiplayer_same": false,
  "use_promotion_price_for_threshold": false,
  "calculate_using_cumulative_units": true,
  "multiply_reward": 0,
  "color_in_cart": null,
  "start_using_default_price": false,
  "is_active": true,
  "conditions": [ ... ]
}

Pole	Typ	Opis
`id`	int	ID promocji
`name`	string	nazwa promocji (nazwa handlowa, jeśli jest ustawiona)
`description`	string	opis (może być pusty)
`start`, `end`	datetime	okres obowiązywania
`short_code`	string	kod promocji
`default_image`	object	grafika promocji (`image`, `alt`); gdy promocja nie ma grafiki – obrazek domyślny
`keep_bundle_multiplayer_same`	bool	w promocjach pakietowych: czy elementy pakietu muszą być kupione w tej samej wielokrotności
`use_promotion_price_for_threshold`	bool	próg wartościowy liczony według ceny promocyjnej zamiast ceny klienta
`calculate_using_cumulative_units`	bool	próg ilościowy wyrażony w jednostkach zbiorczych (np. kartonach) zamiast podstawowych
`multiply_reward`	int	limit wielokrotności nagrody – patrz punkt 4.3
`color_in_cart`	string / null	kolor wyróżnienia produktów promocji w koszyku
`start_using_default_price`	bool	rabat liczony od ceny katalogowej zamiast od ceny klienta
`is_active`	bool	czy promocja jest aktywna – lista zawiera tylko trwające promocje, więc w praktyce zawsze `true`
`conditions`	array / null	warunki promocji; `null`, gdy promocja nie ma warunków

2. Warunki (`conditions`)

Każdy warunek opisuje próg, który trzeba osiągnąć, i nagrody, które wtedy obowiązują:

{
  "threshold_min": 10.0,
  "threshold_max": 0.0,
  "measure": "quantity",
  "rewards": [ ... ]
}

Pole	Typ	Opis
`threshold_min`	liczba	minimalny próg
`threshold_max`	liczba	maksymalny próg; `0` oznacza brak górnej granicy
`measure`	string	`quantity` – próg ilościowy (sztuki); `value` – każdy inny rodzaj progu, w tym próg wartościowy (kwota)
`rewards`	array / null	nagrody obowiązujące po osiągnięciu progu; `null`, gdy żaden produkt nagrody nie jest dostępny dla klienta

Warunki są zwracane w stałej kolejności. Kilka warunków może mieć tę samą listę nagród – należą wtedy do jednej reguły promocji. Progi cenowe (np. inna cena od 10 i od 50 sztuk) to osobne warunki z różnymi nagrodami.

measure rozróżnia tylko próg ilościowy. Progi wielokrotności, „mix wymagany” i próg liczby różnych indeksów (SKU) również są zwracane jako value.

3. Nagrody (`rewards`)

Każda nagroda to cena promocyjna jednego produktu:

{
  "given_price": 8.0,
  "reward_value": 0.0,
  "value_type": "3",
  "quantity": 0.0,
  "product": {
    "id": 817,
    "ean": "5901234123457",
    "name": "BATERIA ENERGIZER...",
    "short_code": "426684-CC",
    "default_unit_of_measure": "bl.",
    "cumulative_unit_of_measure": "karton",
    "cumulative_converter": "24.00",
    "can_be_split": true,
    "cumulative_unit_ratio_splitter": "24.00",
    "unit_roundup": false
  }
}

Pole	Typ	Opis
`given_price`	liczba	cena promocyjna netto produktu
`reward_value`	liczba	wartość rabatu – dla nagrody ze stałą ceną zwykle `0`
`value_type`	string	kod rodzaju wartości (patrz tabela niżej)
`quantity`	liczba	ilość nagrody – dla nagrody ze stałą ceną zwykle `0`
`product`	object	produkt objęty ceną promocyjną

Kody value_type:

Kod	Znaczenie
`1`	wartość
`2`	ilość
`3`	stała cena
`4`	ilościowy próg wielokrotności
`5`	mix wymagany
`6`	kwotowy próg wielokrotności
`7`	SKU (liczba unikalnych indeksów)

Pola produktu w nagrodzie:

Pole	Typ	Opis
`id`	int	ID produktu w AMPER
`ean`	string	kod EAN
`name`	string	nazwa
`short_code`	string	kod produktu
`default_unit_of_measure`	string	jednostka podstawowa
`cumulative_unit_of_measure`	string	jednostka zbiorcza
`cumulative_converter`	string (liczba dziesiętna)	liczba jednostek podstawowych w jednostce zbiorczej
`can_be_split`	bool	czy jednostkę zbiorczą można dzielić
`cumulative_unit_ratio_splitter`	string (liczba dziesiętna)	na ile części można podzielić jednostkę zbiorczą
`unit_roundup`	bool	czy ilość jest zaokrąglana w górę do kroku jednostki

4. Logika promocji

4.1 Rodzaj progu

quantity – liczy się ilość produktów objętych warunkiem.
value – liczy się wartość produktów objętych warunkiem (domyślnie według ceny klienta; według ceny promocyjnej, gdy use_promotion_price_for_threshold = true).

4.2 Jednostki zbiorcze

Gdy calculate_using_cumulative_units = true, próg ilościowy jest liczony w jednostkach zbiorczych produktu (cumulative_unit_of_measure, przelicznik cumulative_converter), a nie w jednostkach podstawowych.

4.3 Wielokrotność nagrody

Gdy klient osiąga próg kilka razy (np. próg 10 szt., w koszyku 30 szt.), nagroda może zostać zwielokrotniona. multiply_reward ogranicza tę wielokrotność:

0 – bez limitu (próg osiągnięty 3 razy = nagroda 3 razy),
N większe od zera – najwyżej N razy (dla multiply_reward = 1 i 30 szt. nagroda zostanie przyznana raz).

4.4 Typowe przypadki

Stała cena przy minimalnej ilości – np. „5 zł za sztukę przy zakupie min. 10 szt.”: warunek z measure = quantity, threshold_min = 10, nagroda z given_price = 5.00.

Progi cenowe – kilka warunków dla tego samego produktu z rosnącym threshold_min i coraz niższą given_price.

5. Schemat struktury

Promocja
 ├── conditions [Warunek]
 │     ├── threshold_min
 │     ├── threshold_max
 │     ├── measure (quantity / value)
 │     └── rewards [Nagroda]
 │            ├── given_price
 │            ├── reward_value
 │            ├── value_type
 │            ├── quantity
 │            └── product (Produkt)
 └── pozostałe pola promocji

6. Wyliczanie cen po stronie systemu zewnętrznego

Pełna logika promocji AMPER (pakiety, wielokrotności, łączenie promocji, kolejność ich stosowania) jest rozbudowana i nie zalecamy odtwarzania jej po stronie systemu zewnętrznego. Dane z tego API nadają się do prezentacji – np. oznaczenia produktów w promocji i pokazania ceny promocyjnej od określonej ilości.

Aby poznać ostateczne ceny dla konkretnego koszyka, wyślij go do AMPER w trybie symulacji:

POST /create-order
{ "customer_id": 42, "playground": true, "lines": [ ... ] }

AMPER zwróci dla każdej linii zastosowaną promocję i cenę, nie tworząc zamówienia. Szczegóły: Tworzenie zamówienia „create-order”.

7. Prezentacja w sklepie (koszyk)

System zewnętrzny powinien:

wyróżnić produkty w promocji (kolor color_in_cart, jeśli jest ustawiony),
pokazać cenę promocyjną given_price i próg, od którego obowiązuje (threshold_min),
pokazać nazwę i opis promocji (name, description) oraz jej grafikę (default_image),
przy finalizacji zamówienia polegać na cenach wyliczonych przez AMPER (create-order).

API zewnętrzne – integracja sklepu internetowego