Kapitola 6: Triggery

Co jsou triggery?

Triggery jsou pokročilým mechanismem BillingEngine, který automaticky vytváří nové datové záznamy při splnění definovaných podmínek. Zatímco pravidla oceňování rozhodují, jaký ceník použít pro každý záznam, triggery reagují na příchod záznamu a generují nový DR na základě šablony (action_template).

Klíčový princip: trigger nemění ohodnocení existujícího záznamu — vytvoří samostatný nový záznam, který je pak oceněn standardním rating enginem přes pravidla oceňování.

Typické použití triggerů:

• Příplatky za velké dávky — každý SMS záznam s množstvím > 500 ks vygeneruje dodatečný poplatek
• Objemové bonusy — zákazník, který překročil 200 minut hovoru za měsíc, dostane jeden bonus záznam
• Věrnostní programy — zákazník s více než 1 000 záznamy celkem obdrží věrnostní kredit
• Nadlimitní příplatky — zákazník s více než 1 000 SMS za měsíc je automaticky zatížen příplatkem za každou další SMS

Struktura triggeru

Trigger se skládá z těchto polí:

POST /api/v1/triggers
Content-Type: application/json

{
  "name": "Příplatek za velkou SMS dávku",
  "conditions": {
    "code": "SMS",
    "quantity": { "op": "gt", "value": 500 }
  },
  "action_template": {
    "code": "SMS_PRIPLATEK",
    "quantity": 1
  },
  "is_active": true
}

action_template: šablona nového záznamu

action_template definuje, jak bude vypadat nový DR vytvořený při spuštění triggeru. Minimálně musí obsahovat code. Nový záznam automaticky zdědí partner_id, customer_id, time_from a time_to od záznamu, který trigger spustil.

Speciální hodnoty:

• "code": "{original}" — nový záznam přebere code spouštěcího záznamu
• "external_id": "{original}" — nový záznam přebere external_id spouštěcího záznamu

Nový záznam je po vytvoření ihned ohodnocen standardním ratingem — přes vámi nakonfigurovaná pravidla oceňování. Aby byl trigger funkční, musí existovat pravidlo oceňování pro kód použitý v action_template.

Skalární podmínky

Pole conditions je objekt, jehož klíče odpovídají názvům polí datového záznamu a hodnoty jsou buď skalár (rovnost) nebo objekt s operátorem:

{
  "conditions": {
    "code": "SMS",
    "quantity": { "op": "gt", "value": 500 }
  }
}

Při splnění skalárních podmínek se nový záznam vytvoří pro každý vyhovující DR.

Podporované operátory:

Agregační podmínky

Agregační podmínky (aggregate_conditions) umožňují rozhodovat na základě kumulativních hodnot za aktuální měsíc. Pokud jsou splněny, trigger vytvoří jeden nový záznam na zákazníka (nikoliv per DR).

{
  "aggregate_conditions": [
    {
      "func": "sum",
      "field": "quantity",
      "filter": { "code": "VOICE_MIN" },
      "op": "gt",
      "value": 200,
      "group_by": "customer_id"
    }
  ]
}

Struktura agregační podmínky:

• func — agregační funkce: sum, count, avg, min, max
• field — pole záznamu, přes které se agreguje (quantity, id apod.)
• filter — volitelné podmínky na výběr záznamů do agregace
• op — operátor porovnání (gt výchozí, gte, lt, lte, eq)
• value — prahová hodnota
• group_by — dimenze agregace (typicky customer_id)

Kombinace podmínek

Trigger může mít obě sady podmínek najednou. Obě musí být splněny současně (logické AND):

{
  "name": "SMS věrnostní bonus",
  "conditions": {
    "code": "SMS"
  },
  "aggregate_conditions": [
    {
      "func": "count",
      "field": "id",
      "filter": { "code": "SMS" },
      "op": "gt",
      "value": 1000,
      "group_by": "customer_id"
    }
  ],
  "action_template": {
    "code": "SMS_LOYALTY",
    "quantity": 1
  },
  "is_active": true
}

Tento trigger se aktivuje pro zákazníka, který celkem odeslal více než 1 000 SMS A aktuální záznam je SMS. Výsledkem je JEDEN nový SMS_LOYALTY záznam na zákazníka.

Integrace s pravidly oceňování

Celý ceníkový mechanismus pro triggery funguje přes standardní pravidla oceňování:

1. Vytvořte ceník s položkou pro kód použitý v action_template (např. SMS_PRIPLATEK)
2. Vytvořte pravidlo oceňování odkazující na tento ceník
3. Trigger při spuštění vytvoří DR s daným kódem — pravidlo ho automaticky ohodnotí

Příklad: trigger generuje záznamy SMS_PRIPLATEK → pravidlo s billing_category: "retail" odkazuje na ceník s položkou code: "SMS_PRIPLATEK" a cenou 2.50 CZK → zákazník dostane příplatek za každý aktivovaný trigger.

Příklady z praxe

Příklad 1: Příplatek za nadlimitní SMS

Operátor má základní tarif pro prvních 1 000 SMS za měsíc. Za každou SMS nad tímto limitem zákazník platí vyšší sazbu.

{
  "name": "Příplatek za nadlimitní SMS",
  "conditions": {
    "code": "SMS"
  },
  "aggregate_conditions": [
    {
      "func": "count",
      "field": "id",
      "filter": { "code": "SMS" },
      "op": "gte",
      "value": 1000,
      "group_by": "customer_id"
    }
  ],
  "action_template": {
    "code": "SMS_NADLIMIT",
    "quantity": 1
  },
  "is_active": true
}

Po dosažení 1 000 SMS za měsíc engine pro každou další SMS vygeneruje záznam SMS_NADLIMIT, který je oceněn vyšší sazbou.

Příklad 2: Měsíční hlasový bonus

Zákazníci, kteří v měsíci provolají více než 200 minut, obdrží jeden bonus záznam se zápornou cenou (sleva).

{
  "name": "Hlasový objem — měsíční bonus",
  "conditions": {
    "code": "VOICE_MIN"
  },
  "aggregate_conditions": [
    {
      "func": "sum",
      "field": "quantity",
      "filter": { "code": "VOICE_MIN" },
      "op": "gt",
      "value": 200,
      "group_by": "customer_id"
    }
  ],
  "action_template": {
    "code": "VOICE_BONUS",
    "quantity": 1
  },
  "is_active": true
}

Příklad 3: Věrnostní program

Zákazník, který za měsíc přesáhl 1 000 datových záznamů, obdrží věrnostní kredit.

{
  "name": "Věrnostní program — 1000+ záznamů",
  "conditions": {},
  "aggregate_conditions": [
    {
      "func": "count",
      "field": "id",
      "op": "gt",
      "value": 1000,
      "group_by": "customer_id"
    }
  ],
  "action_template": {
    "code": "LOYALTY_KREDIT",
    "quantity": 1
  },
  "is_active": true
}

Triggery vs. pravidla oceňování

Pravidla oceňování a triggery se vzájemně doplňují — pravidla ohodnocují původní záznamy, triggery přidávají doplňkové záznamy pro speciální scénáře.

Doporučené postupy

Vždy vytvořte pravidlo pro kód action_template. Trigger generuje nový DR — bez odpovídajícího pravidla oceňování skončí nový záznam v chybovém stavu.

Pojmenovávejte kódy action_template jasně. SMS_NADLIMIT, VOICE_BONUS, LOYALTY_KREDIT jsou srozumitelná jména. Jasný kód usnadňuje konfiguraci ceníku i ladění.

Testujte na historických datech. Agregační podmínky závisí na historii zákazníka — při nasazení nového triggeru ověřte, jak se chová pro zákazníky s různými objemy.

Monitorujte záznamy s příznakěm source=trigger. Záznamy vytvořené triggery mají příznak source: "trigger". Sledujte jejich počet — neočekávaně vysoký výskyt signalizuje špatně nastavený práh.

Kombinujte s pravidly oceňování. Trigger + pravidlo = kompletní cenová logika. Standardní ceny přes pravidla, bonusy a příplatky přes triggery.

Závěr

Triggery jsou posledním dílem skládačky BillingEngine. Kombinací skalárních podmínek pro aktuální záznam a agregačních podmínek pro historická data umožňují modelovat libovolně komplexní cenové strategie — od jednoduchých příplatků po sofistikované věrnostní programy. Tímto se uzavírá přehled základních entit BillingEngine. Pro konkrétní integrační scénáře doporučujeme prostudovat dokumentaci API a testovací prostředí.