Kapitola 4: Zákazníci

Zákazník v BillingEngine

Zákazník (customer) je centrální entitou, kolem které se točí veškerá fakturace v BillingEngine. Každý datový záznam (DR) musí být přiřazen ke konkrétnímu zákazníkovi — teprve pak engine ví, jaká pravidla a ceníky použít.

Zákazník v BillingEngine reprezentuje vaše koncové zákazníky — firmy, které odebírají vaše služby. Nepleťte tuto entitu s uživateli systému (users), kteří slouží k přihlašování do administrace.

Struktura zákazníka

Zákazník nese tyto atributy:

Vytvoření zákazníka

Nového zákazníka vytvoříte přes REST API:

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

{
  "name": "End Customer a.s.",
  "external_id": "EXT-CU-0042",
  "tax_id": "CZ12345678",
  "vat_id": "CZ12345678",
  "address_street": "Příkladná 1",
  "address_city": "Praha",
  "address_zip": "110 00",
  "address_country": "CZ"
}

Odpověď obsahuje jen id nového zákazníka:

{ "id": "uuid-noveho-zakaznika" }

Přiřazení skupin při vytvoření

Zákazníka lze rovnou zařadit do skupin přes pole group_ids:

{
  "name": "End Customer a.s.",
  "external_id": "EXT-CU-0042",
  "group_ids": ["uuid-skupina-vip", "uuid-skupina-promo"]
}

Tím odpadá nutnost volat skupinový endpoint zvlášť.

External ID: klíč k bezešvé integraci

External ID (external_id) je váš vlastní identifikátor zákazníka z CRM, ERP nebo jiného systému. Je klíčový při odesílání datových záznamů — umožňuje identifikovat zákazníka bez znalosti interního UUID BillingEngine:

// Při odesílání DR stačí váš identifikátor:
{
  "customer_external_id": "EXT-CU-0042",
  "code": "SMS",
  "quantity": 1500,
  "time_from": "2026-03-31T14:00:00Z"
}

Hodnota external_id musí být unikátní mezi všemi vašimi zákazníky.

Správa zákazníků

GET    /api/v1/customers          # Seznam zákazníků (s paginací)
GET    /api/v1/customers/{id}     # Detail zákazníka
PUT    /api/v1/customers/{id}     # Aktualizace zákazníka
DELETE /api/v1/customers/{id}     # Smazání zákazníka
GET    /api/v1/customers/{id}/groups  # Skupiny zákazníka

Aktualizace (PUT) přijímá stejná pole jako vytvoření, včetně group_ids. Smazání zákazníka nevymaže jeho historické datové záznamy — ty zůstávají v databázi pro auditní účely.

Zákazník a skupiny

Zákazníky přiřazujete do skupin buď přímo při vytvoření/aktualizaci přes group_ids, nebo samostatně přes skupinový endpoint:

POST /api/v1/groups/{groupId}/customers
Content-Type: application/json

{ "customer_id": "uuid-zakaznika" }

Přehled skupin zákazníka:

GET /api/v1/customers/{id}/groups

Jeden zákazník může být ve více skupinách najednou.

Životní cyklus zákazníka

1. Registrace — zákazník se vytvoří v BillingEngine (manuálně nebo automatizovaně z CRM)
2. Přiřazení do skupin — zákazník se přidá do odpovídajících segmentů (lze i v kroku 1 přes group_ids)
3. Aktivní fakturace — zákazník generuje datové záznamy, engine je ohodnocuje
4. Billing — na konci období se vygeneruje souhrn přes billing endpoint
5. Změna segmentu — zákazník se přesune do jiné skupiny (zdražení, upgrade)
6. Ukončení smlouvy — zákazníka odeberte ze skupin; zvažte, zda ho smazat nebo ponechat pro historické dotazy

Doporučené postupy

Vždy nastavte external_id. I kdybyste ho aktuálně nepotřebovali, zpětné přidávání ke stovkám zákazníků je nepříjemné. Napojení na DR přes customer_external_id pak funguje okamžitě.

Nepřepisujte external_id. Po prvním nastavení by se neměl měnit — je to identifikátor, na který se odvolávají datové záznamy. Změna vede k narušení integrace.

Vyplňte fakturační údaje. Pole tax_id, vat_id a adresní pole jsou volitelná, ale jejich vyplnění usnadňuje generování faktur a plnění zákonných požadavků.

Smažte zákazníka opatrně. Historické záznamy přežijí, ale ztratíte odkaz na zákaznický objekt. Pokud jen potřebujete zákazníka “deaktivovat”, odeberte ho ze skupin — smazání není nutné.

Závěr

Zákazník je klíčovou entitou propojující datové záznamy s ceníky. External ID umožňuje bezešvou integraci s vašimi stávajícími systémy. V Kapitole 5 se podíváme na datové záznamy — jak je strukturovat, odesílat a jak probíhá celý proces ratingu.