Kapitola 5: Datové záznamy

Co je datový záznam?

Datový záznam (Data Record, DR) je základní vstupní jednotka BillingEngine. Reprezentuje jedno využití vaší služby zákazníkem — odeslání SMS, minutu hovoru, megabyte přenesených dat nebo jakoukoliv jinou měřitelnou aktivitu, za kterou chcete zákazníka fakturovat.

Záznamy jsou vstupem do rating engine — procesu, který přiřadí každému záznamu cenu na základě aktivních pravidel oceňování a ceníkových verzí platných v době záznamu.

Struktura datového záznamu

Každý záznam má tato pole:

code je klíčový propojovací prvek — engine ho použije k vyhledání odpovídající položky v aktivní verzi ceníku (price_list_item.code). Pokud ceník daný kód neobsahuje, záznam nelze ohodnotit.

Odeslání záznamů

Záznamy se odesílají jako pole v těle požadavku, ne jako jednotlivé objekty:

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

{
  "records": [
    {
      "customer_external_id": "EXT-CU-0042",
      "code": "SMS",
      "quantity": 1500,
      "time_from": "2026-03-31T14:00:00Z",
      "external_id": "MY-SYSTEM-RECORD-99887"
    },
    {
      "customer_external_id": "EXT-CU-0042",
      "code": "VOICE_MIN",
      "quantity": 48,
      "time_from": "2026-03-31T14:05:00Z"
    }
  ]
}

Maximální velikost dávky je 10 000 záznamů (nebo 5 000 při ondemand: true).

Synchronní vs. asynchronní zpracování

BillingEngine podporuje dva režimy:

Asynchronní (výchozí, ondemand: false): Záznamy se uloží do fronty a ohodnotí na pozadí. Odpověď přijde okamžitě s queueId a seznamem ids:

{
  "message": "Successfully inserted 2 records",
  "queueId": "uuid-fronty",
  "ids": ["uuid-zaznamu-1", "uuid-zaznamu-2"],
  "ondemand": false
}

Stav zpracování pak zjistíte přes:

GET /api/v1/dr/status?month=202603&queue_id=uuid-fronty

Odpověď: { "total": 2, "by_status": { "rated": 1, "unrated": 0, "error": 1 } }

Synchronní (ondemand: true): Záznamy se ohodnotí ihned před vložením. Pokud přidáte include_rated: true, odpověď obsahuje i výsledky ratingu:

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

{
  "ondemand": true,
  "include_rated": true,
  "records": [...]
}

Synchronní režim je vhodný pro ověřování cen, debug nebo menší objemy. Pro produkční import doporučujeme asynchronní režim.

Průběh ratingu

Rating každého záznamu probíhá v těchto krocích:

1. Načtení skupin zákazníka — engine zjistí skupiny zákazníka identifikovaného přes customer_external_id.

2. Výběr applicable pravidel — engine projde všechna aktivní pravidla oceňování partnera a vybere ta, která odpovídají zákazníkovi (nebo jeho skupinám) a jejichž valid_from/valid_to pokrývá time_from záznamu.

3. Výběr verze ceníku — pro každé applicable pravidlo engine najde verzi ceníku platnou v době time_from.

4. Lookup ceníkové položky — hledá položku ceníku se stejným code jako má záznam. Pokud ji nenajde, pravidlo přeskočí.

5. Výpočet ceny — aplikuje tarifikaci a vypočítá cenu:

billed_qty = apply_tarification(quantity, item.tarification)
price = billed_qty × item.price × (1 - discount / 100)

6. Uložení — každé úspěšné pravidlo vytvoří samostatný rated záznam s cenou, měnou, slevou a sazbou DPH.

Engine nepřestane po prvním matching pravidle — vytvoří rated záznamy pro všechna applicable pravidla (typicky cost i retail najednou).

Tarifikace

Tarifikace je telekomový mechanismus pro zaokrouhlování fakturovaného množství. Položka ceníku může mít pole tarification ve formátu "first_block/subsequent_block":

• "60/1" — první blok 60 sekund, pak každá sekunda zvlášť
• "60/60" — vždy zaokrouhluje na násobky 60

Příklad: tarifikace "60/60", quantity 75 → fakturuje se 120 (dvě šedesátky).

Statusy záznamu

Každý odeslaný záznam prochází těmito stavy:

Záznamy ve stavu error nebo unrated lze přehodnotit — buď jednotlivě nebo hromadně:

POST /api/v1/dr/re-rate
Content-Type: application/json

{ "month": "202603", "status": "error" }

Billing endpoint

Na konci fakturačního období slouží billing endpoint k agregaci cen:

POST /api/v1/dr/billing
Content-Type: application/json

{
  "time_from": "2026-03-01T00:00:00Z",
  "time_to": "2026-03-31T23:59:59Z",
  "billing_category": "retail",
  "group_by": "code"
}

Parametr group_by určuje dimenzi agregace: code, type, subtype nebo analytic. Odpověď obsahuje sumy s rozpisem DPH — ideální podklad pro fakturaci.

Billing endpoint nefiltruje podle zákazníka — vrací agregaci přes všechny záznamy partnera v daném období. Pokud potřebujete data pro konkrétního zákazníka, využijte parametr pricing_rule_id nebo pricing_rule_code.

Smazání záznamů

Záznamy lze smazat jednotlivě nebo hromadně dle časového rozsahu či kódu:

DELETE /api/v1/dr
Content-Type: application/json

{
  "time_from": "2026-03-01T00:00:00Z",
  "time_to": "2026-03-31T23:59:59Z",
  "code": "SMS"
}

Doporučené postupy

Vždy nastavte time_from. Záznam bez time_from nelze odeslat — je povinné pole. Předávejte skutečný čas události, ne čas odeslání požadavku.

Používejte external_id. Vlastní identifikátor záznamu ulehčuje dohledávání a ladění. Pokud ho nenastavíte, BillingEngine použije interní UUID.

Preferujte asynchronní režim. Pro produkční objemy (tisíce záznamů) odesílejte asynchronně a sledujte stav přes /dr/status. Synchronní ondemand je vhodný jen pro malé objemy nebo ověřování.

Monitorujte záznamy ve stavu error. Záznamy bez matching pravidla nebo ceníkové položky skončí v error. Nastavte si pravidelnou kontrolu přes /dr/status a opravte konfiguraci ceníku nebo pravidel.

Dávkujte rozumně. Optimální velikost dávky je stovky až nízké tisíce záznamů. Velmi velké dávky mohou zpomalit zpracování.

Závěr

Datové záznamy jsou srdcem BillingEngine — vše ostatní (ceníky, pravidla, skupiny, zákazníci) existuje proto, aby záznamy správně ohodnotilo. Pochopení procesu ratingu, asynchronního zpracování a billing endpointu vám dává úplný obraz fungování systému. V Kapitole 6 se podíváme na triggery — pokročilý mechanismus pro podmínkové chování engine při specifických objemech nebo stavech zákazníka.