# Promocje - integracja z systemami zewnętrznymi

#### **📘 Dokumentacja techniczna struktura i logika promocji**

##### **🧩 1. Struktura pojedynczej promocji**

Każdy element tablicy to *jedna promocja* w systemie AMPER B2B.

```
{
  "id": 22960679,
  "name": "promocja na palete",
  "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": "...", "alt": "..." },
  "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": [ ... ]
}
```

##### **🔍 Kluczowe pola**

<table id="bkmrk-pole-typ-opis-id-int"><thead><tr><th>**Pole**

</th><th>**Typ**

</th><th>**Opis**

</th></tr></thead><tbody><tr><td>id

</td><td>int

</td><td>ID promocji

</td></tr><tr><td>name

</td><td>string

</td><td>Nazwa promocji

</td></tr><tr><td>description

</td><td>string

</td><td>Opis (opcjonalny)

</td></tr><tr><td>start<span class="s1">, </span>end

</td><td>datetime

</td><td>Zakres obowiązywania promocji

</td></tr><tr><td>short\_code

</td><td>string

</td><td>Jednoznaczny kod identyfikacyjny

</td></tr><tr><td>default\_image

</td><td>object

</td><td>Domyślna grafika promocji

</td></tr><tr><td>keep\_bundle\_multiplayer\_same

</td><td>bool

</td><td>Czy utrzymać wielokrotność w zestawach

</td></tr><tr><td>use\_promotion\_price\_for\_threshold

</td><td>bool

</td><td>Czy threshold/próg liczony wg ceny promocyjnej

</td></tr><tr><td>calculate\_using\_cumulative\_units

</td><td>bool

</td><td>Czy przeliczać jednostki po konwerterach/jednostkach zbiorczych

</td></tr><tr><td>multiply\_reward

</td><td>int

</td><td>Czy nagroda mnożona przez ilość pakietów

</td></tr><tr><td>color\_in\_cart

</td><td>string/null

</td><td>Kolor w koszyku

</td></tr><tr><td>start\_using\_default\_price

</td><td>bool

</td><td>Czy liczyć od ceny domyślnej

</td></tr><tr><td>is\_active

</td><td>bool

</td><td>Czy aktywna

</td></tr><tr><td>conditions

</td><td>array

</td><td>Lista warunków aktywujących promocję

</td></tr></tbody></table>

#### **🧠 2. Warunki promocji (conditions)**

Każda promocja może zawierać <span class="s2">**jeden lub wiele warunków**</span>.

Struktura warunku:

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

##### **▶ Pola warunku**

<table id="bkmrk-pole-typ-opis-thresh"><thead><tr><th>**Pole**

</th><th>**Typ**

</th><th>**Opis**

</th></tr></thead><tbody><tr><td>threshold\_min

</td><td>float

</td><td>Minimalny próg osiągnięcia promocji

</td></tr><tr><td>threshold\_max

</td><td>float

</td><td>Maksymalny próg (0 = brak limitu)

</td></tr><tr><td>measure

</td><td>string

</td><td>Typ pomiaru: <span class="s1">"quantity"</span> lub <span class="s1">"value"</span>

</td></tr><tr><td>rewards

</td><td>array/null

</td><td>Lista nagród (ceny, gratisy, rabaty)

</td></tr></tbody></table>

#### **🎁 3. Nagrody (rewards)**

Każda nagroda jest powiązana do konkretnego produktu.

```
{
  "given_price": 8.0,
  "reward_value": 0.0,
  "value_type": "3",
  "quantity": 0.0,
  "product": {
    "id": 817,
    "ean": "817",
    "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
  }
}
```

##### **▶ Pola nagrody**

<table id="bkmrk-pole-typ-opis-given_"><thead><tr><th>**Pole**

</th><th>**Typ**

</th><th>**Opis**

</th></tr></thead><tbody><tr><td>given\_price

</td><td>float

</td><td>Cena promocyjna produktu

</td></tr><tr><td>reward\_value

</td><td>float

</td><td>Wartość rabatu (jeśli dotyczy)

</td></tr><tr><td>value\_type

</td><td>string

</td><td>Typ rabatu (np. stała cena, gratis, procent)

</td></tr><tr><td>quantity

</td><td>float

</td><td>Ilość nagrody (np. liczba gratisów)

</td></tr><tr><td>product

</td><td>object

</td><td>Opis produktu objętego promocją

</td></tr></tbody></table>

#### **📦 4. Struktura produktu w nagrodzie (product)**

<table id="bkmrk-pole-typ-opis-id-int-1"><thead><tr><th>**Pole**

</th><th>**Typ**

</th><th>**Opis**

</th></tr></thead><tbody><tr><td>id

</td><td>int

</td><td>ID produktu

</td></tr><tr><td>ean

</td><td>string

</td><td>Kod EAN

</td></tr><tr><td>name

</td><td>string

</td><td>Pełna nazwa

</td></tr><tr><td>short\_code

</td><td>string

</td><td>Kod skrócony

</td></tr><tr><td>default\_unit\_of\_measure

</td><td>string

</td><td>Jednostka bazowa

</td></tr><tr><td>cumulative\_unit\_of\_measure

</td><td>string

</td><td>Jednostka zbiorcza

</td></tr><tr><td>cumulative\_converter

</td><td>string

</td><td>Przelicznik jednostek

</td></tr><tr><td>can\_be\_split

</td><td>bool

</td><td>Czy można dzielić jednostki

</td></tr><tr><td>cumulative\_unit\_ratio\_splitter

</td><td>string

</td><td>Współczynnik dzielenia

</td></tr><tr><td>unit\_roundup

</td><td>bool

</td><td>Czy zaokrąglać w górę

</td></tr></tbody></table>

#### **🧮 5. Logika liczenia promocji**

##### **5.1. Typ progu – measure**

Dwa tryby:

##### **1) quantity**

Liczymy ilość sztuk / opakowań / jednostek.

##### **2) value**

Liczymy wartość koszyka dla produktów spełniających warunki.

##### **5.2. Przeliczanie jednostek (calculate\_using\_cumulative\_units)**

Jeśli <span class="s2">**true**</span> – ilość do thresholdu liczona jest tak:

```
ilość_w_sztukach * cumulative_converter
```

Przykład:

- <span class="s1">produkt: 6-pack → </span>cumulative\_converter = 6
- klient kupuje 2 opakowania
- do thresholdu liczymy: <span class="s1">**12 szt.**</span>

---

##### **5.3. Multiplikacja nagród (multiply\_reward)**

<span class="s2">Jeśli </span>multiply\_reward &gt; 0<span class="s2">:</span>

- osiągnięcie kolejnych progów zwiększa liczbę nagród

Przykład:

threshold = 10 szt

multiply\_reward = 1

klient kupił 30 szt → <span class="s3">**3x nagroda**</span>

#### **🎯 6. Typowe przypadki** 

##### **📌 Stała cena za produkt**

Promocje typu:

> <span class="s2">reward → </span>value\_type = 3<span class="s2">, </span>given\_price &gt; 0

Przykład: “Stała cena 5 zł przy zakupie min 10 szt”

##### **📌 Gratis**

<span class="s2">Promocja ma </span>quantity &gt; 0<span class="s2"> oraz </span>given\_price = 0<span class="s2">.</span>

##### **📌 Progi wielokrotności**

Promocje:

- Próg wielokrotności - produkt kwota
- Próg wielokrotności - kategoria kwota

Mechanika:

- measure = value
- wiele warunków z tym samym threshold
- wiele nagród równoległych

---

#### **🧱 7. Przykład – schematy strukturalne**

##### **Promocja (Promo)**

```
Promo
 ├── conditions [Condition]
 │     ├── threshold_min
 │     ├── threshold_max
 │     ├── measure (quantity/value)
 │     └── rewards [Reward]
 │            ├── given_price
 │            ├── reward_value
 │            ├── value_type
 │            ├── quantity
 │            └── product (Product)
 └── metadata...
```

---

##### **▶ 8. Użycie** 

### **Algorytm wyliczania promocji:**

1. Pobierz wszystkie aktywne promocje dla klienta
2. Dla każdej promocji:
    
    
    - sprawdź daty start/end
    - oblicz threshold dla danego measure
    - uwzględnij cumulative conversions
3. Jeśli warunki spełnione:
    
    
    - zastosuj nagrody:
        
        
        - nadpisz cenę (<span class="s1">given\_price</span>)
        - dodaj gratisy
        - nadaj rabat procentowy/kwotowy
4. Zapisz informację o zastosowanej promocji w koszyku.

---

#### **📄 9. Użycie po stronie frontend (koszyk)**

Front powinien:

- wyróżnić produkty w promocji (<span class="s1">color\_in\_cart</span>)
- pokazać cenę promocyjną <span class="s1">given\_price</span>
- pokazać opis promocji
- dodać gratisy jako osobne linie (jeśli quantity &gt; 0)
- opcjonalnie pokazać osiągnięty próg

---

#### **📗 10. Podsumowanie**

AMPER to elastyczny model promocji zawierający:

✔ wiele progów

✔ wiele typów nagród

✔ wielokrotność progów

✔ konwersje jednostek

✔ stałe ceny

✔ gratisy

✔ rabaty

✔ pakiety