Workflow: Loyalty Program — Fidelizare Clienți

Module implicate: Loyalty (Rules · Transactions · Redemption · Membership · Programs) · Invoices · OmniSales · Clients
Cine îl folosește: Marketing · Sales · Customer Success
Durata tipică: Continuu — punctele se acumulează la fiecare plată

Overview

Modulul Loyalty implementează un sistem complet de fidelizare: acumulare automată de puncte la plata facturilor, trei tipuri de bonusuri suplimentare (cont nou, aniversare, manual), răscumpărare în 4 contexte diferite (factură admin, portal client, OmniSales, voucher), și un sistem de niveluri (tiere) cu beneficii diferențiate per nivel.

Condiție obligatorie: Toggle-ul global loyalty_setting trebuie setat la 1 din Setup → Marketing → Loyalty. Fără aceasta, hook-ul after_payment_added nu execută nicio logică de puncte, indiferent de regulile configurate.

Nu există expirare automată a punctelor. Punctele scad doar prin răscumpărare explicită.

Diagrama fluxului

[SETUP — admin, o singură dată]
  │
  ├── Activare globală: loyalty_setting = 1
  ├── Loyalty Rules: tip câștig (card_total / product_category / product)
  │     + benzi de răscumpărare (point_weight per bandă de puncte)
  ├── Membership Rules (Tiere): Bronze / Silver / Gold by point range
  ├── Membership Programs: discounturi per tier (card/categorie/produs)
  └── Loyalty Cards: template vizual (opțional)
  │
  ↓
[ACUMULARE PUNCTE — automat la plată]
  │
  ├── Trigger: after_payment_added → factură status = PAID (2)
  ├── Sistem caută reguli active pentru client (by client_id sau client_group)
  │
  ├── rule_base = 'card_total':
  │     puncte = poin_awarded × floor(total_factură / purchase_value)
  │     (ex: 10 puncte per 100 RON cheltuiți)
  │
  ├── rule_base = 'product_category':
  │     per linie de factură: dacă grupa produsului = rel_id în rule_detail
  │     → puncte = loyalty_point × cantitate
  │
  └── rule_base = 'product':
        per linie de factură: dacă produsul = rel_id în rule_detail
        → puncte = loyalty_point × cantitate
  │
  ├── Insert în loy_transation: type='debit', reference='order_debit'
  └── clients.loy_point += puncte câștigate
  │
  ↓
[BONUSURI SUPLIMENTARE]
  │
  ├── Cont nou (after_client_added hook):
  │     → regula cu MAX(create_account_point) activă azi
  │     → type='credit', reference='manual_credit'
  │
  ├── Aniversare (cron before_cron_run hook):
  │     → caută clienți cu câmpul custom 'Birthday' = azi (lună+zi)
  │     → o singură dată per an (verifică loy_transation.note='bonus_points_for_customers_birthday')
  │     → trimite email template 'loyalty-birthday-bonus-point'
  │
  └── Manual (admin): loyalty/transation_form → tip='credit'
  │
  ↓
[NIVEL (TIER) — calculat dinamic]
  │
  ├── client_rank() → caută loy_mbs_rule unde loy_point ∈ [loyalty_point_from, loyalty_point_to]
  ├── Cel mai înalt tier matching câștigat
  └── client_next_rank() → arată câte puncte mai lipsesc pentru nivelul următor
  │
  ↓
[RĂSCUMPĂRARE — 4 contexte]
  │
  ├── [A] Admin pe factură: câmp redeem în formularul de factură
  ├── [B] Client în portal: pagina facturii → redeem points
  ├── [C] OmniSales/POS: câmp redeem în coșul de comandă
  └── [D] Voucher/Program membership: cod voucher sau discount automat per tier
  │
  ↓
[DISCOUNT APLICAT]
  │
  ├── Puncte convertite la monedă via point_weight (ex: 1 pt = 0.05 RON)
  ├── redeemp_type='full': toate punctele, valoare calculată automat
  ├── redeemp_type='partial': clientul alege câte puncte răscumpără
  ├── Insert în loy_redeem_log: old_point, new_point, redeep_from, redeep_to
  └── clients.loy_point -= puncte răscumpărate

[CLIENT FIDEL ✓ · PUNCTE ACUMULATE ✓]

Pas cu pas

1. Activare și configurare globală (admin)

Unde: /admin/loyalty → Setup → General Settings

Activare obligatorie: loyalty_setting = 1

Fără aceasta, hook-ul after_payment_added este înregistrat dar returnează imediat fără calcul.

2. Loyalty Rules — regulile de câștig și răscumpărare

Unde: /admin/loyalty → Loyalty Rules → New Rule

O singură regulă definește atât câștigul cât și răscumpărarea.

2a. Câmpuri regulă

Pentru card_total:

Pentru product_category și product: adăugați linii în Rule Details — fiecare linie specifică rel_type, rel_id (ID grupă sau produs) și loyalty_point per unitate.

Bonusuri speciale per regulă:

2b. Benzi de răscumpărare (Redemption Tiers)

Adăugați cel puțin o bandă în secțiunea Redemption Details a regulii:

3. Membership Rules — niveluri (tiere)

Unde: /admin/loyalty → Membership → New Membership Rule

Definesc tierele (ex: Bronze, Silver, Gold) pe baza punctelor acumulate:

4. Membership Programs — beneficii per tier

Unde: /admin/loyalty → Membership Programs → New Program

Un program leagă un tier (sau mai multe) de un beneficiu de discount:

Atenție: Când un program de membership cu discount este aplicat la factură, sistemul generează automat o notă de credit (add_credit_mbs_program()) și o aplică la factură. Această notă de credit apare în modulul Credit Notes.

5. Câmpul custom „Birthday" (pentru bonus aniversar)

Unde: /admin/clients → fișa client → câmpul custom Birthday (date_picker)

Câmpul este creat automat de modul cu slug customers_birthday. Bonusul de aniversare se declanșează prin cron (before_cron_run) o singură dată pe an per client.

6. Răscumpărare puncte

6a. Pe factură (admin)

La crearea/editarea unei facturi, apare secțiunea Redeem Points dacă:

• Clientul are puncte suficiente (≥ min_poin_to_redeem)
• Există o regulă activă cu bandă de răscumpărare validă

Staff selectează punctele de răscumpărare → discount calculat automat → scris în loy_redeem_log.

6b. Portal client

Clientul logat vede butonul Redeem Points pe pagina facturii (dacă redeem_portal=1 pe regulă și factura nu e deja plătită complet).

Clientul alege punctele → sistemul modifică direct invoices.total (reduce totalul) și loghează în loy_voucher_inv_log.

6c. OmniSales / POS

Câmpul de răscumpărare apare în coșul OmniSales (dacă redeem_pos=1). Se aplică la crearea comenzii.

6d. Voucher membership

La introducerea unui cod voucher (apply_other_voucher filter), sistemul verifică dacă clientul aparține unui tier cu program activ care are acel cod. Returnează voucher_value și minium_purchase.

7. Vizualizare sold puncte client

Unde: /admin/clients/{id} → coloana loy_point pe fișa clientului

Soldul curent este stocat direct în tblclients.loy_point (DECIMAL). Istoricul complet al tranzacțiilor se vede în Loyalty → Transactions filtrat pe client.

Permisiuni necesare

Gotchas

Referințe module

• Clients — soldul loy_point pe fișa client
• Invoices — răscumpărare pe factură
• OmniSales — răscumpărare POS
• Credit Notes — note de credit generate de membership programs