Tento návod vás provede minimálním nastavením — od přihlášení po první DR s přiřazenou cenou. Zvládnete to za 10 minut.

Každý krok lze provést přes Dashboard nebo přímo přes API — záleží na vás.

Přehled kroků

1. Přihlášení
2. Vytvoření ceníku + verze + položek
3. Vytvoření pricing rule
4. Odeslání DR
5. Stažení billing souhrnu

Krok 1 — Přihlášení

Dashboard: Přihlaste se na /dashboard svými přihlašovacími údaji.

API:

POST /api/v1/auth/login
Content-Type: application/json

{
  "username": "vas_login",
  "password": "vase_heslo"
}

Odpověď vrátí token. Přidejte ho do každého dalšího požadavku:

Authorization: Bearer <token>

Krok 2 — Ceník, verze a položky

Ceník říká systému, kolik stojí jaký typ záznamu. Struktura jsou tři úrovně: Ceník → Verze → Položky.

2a — Vytvoření ceníku

Dashboard: Sekce Ceníky → tlačítko Přidat ceník.

API:

POST /api/v1/price-lists
Authorization: Bearer <token>
Content-Type: application/json

{
  "name": "Základní ceník",
  "currency": "CZK"
}

Odpověď: { "id": "<id_ceníku>" } — uložte si ho.

2b — Vytvoření verze ceníku

Verze určuje, od kdy ceny platí. Musí být is_active: true, aby se používala.

Dashboard: Otevřete ceník → záložka Verze → Přidat verzi.

API:

POST /api/v1/price-lists/<id_ceníku>/versions
Authorization: Bearer <token>
Content-Type: application/json

{
  "name": "v1",
  "valid_from": "2024-01-01T00:00:00Z",
  "is_active": true
}

Odpověď: { "id": "<id_verze>" } — uložte si ho.

2c — Přidání položky ceníku

Položka říká: „Za kód VOICE_CZ účtuj 1,50 Kč za jednotku."

Dashboard: Otevřete verzi → Přidat položku.

API:

POST /api/v1/price-lists/versions/<id_verze>/items
Authorization: Bearer <token>
Content-Type: application/json

{
  "code": "VOICE_CZ",
  "name": "Hlasové volání CZ",
  "price": 1.50,
  "currency": "CZK",
  "unit": "minuta"
}

Hodnota code musí přesně odpovídat poli code v DR, který odešlete v kroku 4.

Krok 3 — Pricing rule

Pricing rule propojuje ceník se zákazníky. Bez pravidla systém neví, který ceník použít.

Níže uvedené nastavení aplikuje ceník na všechny vaše zákazníky bez rozdílu.

Dashboard: Sekce Pricing rules → Přidat pravidlo, vyberte ceník.

API:

POST /api/v1/pricing-rules
Authorization: Bearer <token>
Content-Type: application/json

{
  "name": "Základní pravidlo",
  "code": "RULE_DEFAULT",
  "price_list_id": "<id_ceníku>",
  "priority": 10,
  "is_active": true
}

Pravidlo bez customer_id ani group_id se vztahuje na všechny zákazníky. Pro cílení na konkrétní skupinu přidejte "group_id": "<id_skupiny>".

Krok 4 — Odeslání DR

Teď odešlete první datový záznam. Pro okamžité ocenění použijte "ondemand": true.

Zákazníky nemusíte předem zakládat. Stačí zadat libovolný identifikátor v poli customer_external_id — zákazník se vytvoří automaticky při prvním záznamu.

POST /api/v1/dr
Authorization: Bearer <token>
Content-Type: application/json

{
  "ondemand": true,
  "records": [
    {
      "code": "VOICE_CZ",
      "quantity": 10,
      "time_from": "2024-06-15T10:00:00Z",
      "customer_external_id": "CUST-001"
    }
  ]
}

Odpověď: { "inserted": 1, "ids": ["<id_dr>"] }

Co se stalo na pozadí:

• Zákazník CUST-001 byl automaticky vytvořen (žádné osobní údaje nejsou potřeba)
• Systém našel pricing rule → verzi ceníku → položku VOICE_CZ
• Vypočítaná cena: 10 × 1,50 = 15,00 Kč
• DR uložen se stavem rated

Krok 5 — Billing souhrn

Podklady pro fakturu za libovolné období získáte jedním voláním.

Dashboard: Sekce Billing → zadejte období → Zobrazit souhrn.

API:

POST /api/v1/dr/billing
Authorization: Bearer <token>
Content-Type: application/json

{
  "time_from": "2024-06-01T00:00:00Z",
  "time_to":   "2024-06-30T23:59:59Z",
  "group_by":  "code"
}

Odpověď:

{
  "items": [
    {
      "code": "VOICE_CZ",
      "quantity": 10,
      "amount_without_vat": 15.00,
      "vat_amount": 0.00,
      "amount": 15.00,
      "currency": "CZK"
    }
  ],
  "summary": {
    "amount_without_vat": 15.00,
    "vat_amount": 0.00,
    "amount": 15.00,
    "currency": "CZK"
  }
}

Co dál?

• Více kódů — přidejte do verze ceníku další položky (SMS_CZ, DATA_EU, …)
• Více zákazníků — používejte různé customer_external_id; zákazníci se vytvoří sami
• Segmentace cen — vytvořte skupiny zákazníků a pravidla s group_id
• Nová verze cen — přidejte verzi s novým valid_from; historická data zůstanou nezměněna
• Triggery — automatické poplatky při překročení limitů

Ceník v Billing Engine je hierarchická struktura složená z verzí a položek.

Struktura ceníku

Každý ceník (price list) může mít více verzí — typicky jedna je aktivní, ostatní archivní. Každá verze obsahuje cenové položky identifikované kódem (např. VOICE_CZ, SMS_CZ).

Výpočet ceny

Při příchodu datového záznamu (DR) systém:

1. Přes pricing rules najde platnou verzi ceníku pro daného zákazníka
2. Vyhledá položku ceníku odpovídající kódu z DR
3. Vypočítá cenu: cena = množství × jednotková_cena

Přiřazení zákazníkům

Ceníky nejsou přiřazovány zákazníkům přímo. Vazba probíhá přes:

• Groups — zákazník patří do skupiny
• Pricing rules — pravidlo říká: pro tuto skupinu použij tento ceník

Tento model umožňuje jeden ceník sdílet mezi mnoha zákazníky a snadno přecházet na nové verze bez nutnosti měnit nastavení každého zákazníka.

Pricing rules (cenová pravidla) určují, který ceník a verze se použijí pro daný datový záznam.

Jak pravidlo funguje

Každé pravidlo definuje:

• Podmínky (conditions) — matching kritéria, např. code = "VOICE_CZ" nebo quantity > 10
• Prioritu — číslo; vyšší priorita = pravidlo se vyhodnocuje dříve
• Cílový ceník — který ceník (a verze) se použije při shodě

Systém projde pravidla od nejvyšší priority a aplikuje první, které odpovídá záznamu.

Operátory podmínek

Podmínky podporují operátory: eq, ne, gt, gte, lt, lte, like, in.

{ "code": { "op": "eq", "value": "VOICE_CZ" },
  "quantity": { "op": "gt", "value": 0 } }

Triggery — speciální typ pravidla

Triggery jsou rozšíření pravidel pro automatické akce. Spouštějí se při:

• Překročení limitu na jednom DR (conditions)
• Splnění agregační podmínky za období — např. SUM(quantity) > 100 (aggregate_conditions)

Trigger může vyvolat notifikaci nebo přidat poplatek do vyúčtování.