Kapitola 1: Ceníkové seznamy

Co je ceníkový seznam?

Ceníkové seznamy (price lists) tvoří základ každé fakturační operace v BillingEngine. Jsou to strukturované katalogy cen, díky nimž víte přesně, kolik stojí každý typ služby — a to i zpětně v čase. Bez správně nastaveného ceníku nemůže engine ohodnotit jediný datový záznam.

Ceníkový seznam je pojmenovaný kontejner, jenž sdružuje verze a jejich ceníkové položky. Sám o sobě neobsahuje žádné konkrétní sazby — ty jsou uloženy v jeho verzích. Tato architektura umožňuje měnit ceny bez narušení historické konzistence.

Hierarchie vypadá takto:

• Ceníkový seznam — zastřešující objekt s názvem, měnou a popisem
  • Verze — sada cen platná od daného data (valid_from)
    • Položky — konkrétní sazby per code

Díky této třívrstevné struktuře si BillingEngine pamatuje, která sazba platila v okamžiku zpracování každého záznamu. Historické záznamy tak zůstávají konzistentní i po zdražení.

Vytvoření ceníkového seznamu

Nový ceník vytvoříte přes REST API jednoduchým POST požadavkem:

POST /api/v1/price-lists
Content-Type: application/json

{
  "name": "Standardní B2B tarif",
  "currency": "CZK",
  "description": "Ceník pro firemní zákazníky"
}

Odpověď obsahuje id, které budete potřebovat pro vytváření verzí a přiřazení v pravidlech oceňování. Pole currency nastavuje výchozí měnu ceníku (výchozí hodnota je CZK). Ceník si pojmenujte tak, aby bylo za rok jasné, co obsahuje — "Standardní B2B tarif 2026" je lepší než "tarif_v3".

Verze ceníku

Každý ceník může mít více verzí. Engine automaticky vybere tu, jejíž valid_from je nejpozdější a zároveň nepřesahuje čas zpracovávaného záznamu. Verze nepotřebují datum ukončení — engine vždy přepne na novější verzi ke dni jejího valid_from.

POST /api/v1/price-lists/{id}/versions
Content-Type: application/json

{
  "version": "Q1 2026",
  "valid_from": "2026-01-01",
  "description": "Sazby platné od 1. 1. 2026"
}

Pole version je identifikátor verze (například "Q1 2026" nebo "v2.0"). Pokud vytvoříte verzi s pozdějším valid_from, engine na ni přejde automaticky ke dni platnosti bez jakékoli ruční intervence.

Důležité: Zajistěte, aby ceník měl vždy alespoň jednu verzi s valid_from nepřesahujícím nejstarší datový záznam, který chcete ohodnotit. Pokud žádná verze nepokrývá čas záznamu, engine záznam označí jako chybný.

Ceníkové položky

Ceníkové položky definují skutečné sazby. Každá položka se váže na konkrétní kód (code) a definuje cenu (price):

POST /api/v1/price-lists/versions/{versionId}/items
Content-Type: application/json

{
  "code": "SMS",
  "price": 0.85,
  "unit": "ks",
  "vat_rate": 21
}

Při zpracování datového záznamu engine vyhledá položku s odpovídajícím code a vypočítá cenu jako quantity × price × (1 - discount / 100). Pokud položka pro daný kód neexistuje, záznam nelze ohodnotit a je označen jako chybný.

Typický ceník pro telekomunikačního operátora vypadá takto:

Měna je nastavena na úrovni celého ceníku (pole currency při vytváření).

Propojení s zákazníky přes pravidla

Ceník samotný se zákazníkům nepřiřazuje přímo — to zprostředkovávají pravidla oceňování (pricing rules). Pravidlo říká: “Pro zákazníky ve skupině X použij ceník Y.” Toto oddělení umožňuje sdílet jeden ceník mezi více skupinami zákazníků a aktualizovat ceny na jednom místě bez nutnosti měnit každé pravidlo zvlášť.

Podrobněji se pravidlům věnuje Kapitola 2.

Verzování jako garance auditovatelnosti

Finanční systémy musí být auditovatelné. Zákazník nesmí přijít s reklamací a zjistit, že historická data nesedí. BillingEngine řeší tento problém tím, že každý zpracovaný datový záznam obsahuje odkaz na přesnou verzi ceníku, která byla použita při výpočtu. Tento odkaz je neměnný — záznam jej nese od okamžiku vytvoření a nelze jej zpětně přepsat.

Takže i když dnes zvýšíte cenu SMS z 0,85 Kč na 1,10 Kč vytvořením nové verze s pozdějším valid_from, všechny záznamy zpracované před změnou zůstanou ohodnoceny původní sazbou. Vaše retrospektivní reporty budou vždy správné, faktury přesné a reklamace ověřitelné.

Správa ceníků v průběhu roku

Typický životní cyklus ceníku ve výrobním prostředí:

1. Leden — vytvoříte ceník “Standardní tarif 2026” s verzí valid_from: "2026-01-01"
2. Únor — obchodní tým schválí zdražení od dubna
3. Březen — vytvoříte novou verzi s valid_from: "2026-04-01" a novými sazbami
4. Duben — engine automaticky přepne na novou verzi bez jakékoliv ruční intervence
5. Každý měsíc — billing endpoint vrací správné sumy bez ohledu na změny cen

Celý přechod probíhá bez výpadku a bez nutnosti znovu zpracovávat historická data.

Doporučené postupy

Pojmenovávejte verze srozumitelně. "Q2 2026 — zdražení SMS +15 %" je lepší než "verze4". Názvy by měly dávat smysl za tři roky, když budete řešit reklamaci.

Nepřepisujte aktivní verze. Pokud chcete změnit ceny, vytvořte novou verzi s pozdějším valid_from. Editace aktivní verze může narušit konzistenci historických výpočtů.

Testujte v sandboxu. Před nasazením nové verze ověřte pomocí testovacích datových záznamů, že engine vrací správné ceny.

Dokumentujte důvody změn. Pole description u verze slouží přesně k tomuto účelu. Napište, proč ke změně cen došlo — zdražení dodavatele, nová smlouva, inflační doložka.

Hlídejte pokrytí datumů. Ujistěte se, že první verze ceníku má valid_from nepřesahující nejstarší záznamy, které budete importovat. Záznamy bez platné verze ceníku skončí v chybovém stavu.

Závěr

Ceníkové seznamy jsou základním stavebním kamenem BillingEngine. Pochopení jejich třívrstevné struktury — seznam, verze, položky — a principu verzování je klíčové pro správné nastavení celého systému. V Kapitole 2 se podíváme na pravidla oceňování, která propojují ceníky se zákazníky a definují, kdy se který ceník použije.