Programy poleceń

Program poleceń (rfl_…) definiuje dwa zestawy reguł procentowych: dla poleconego (osoba, która otworzyła link z ?ref=… i opłaciła subskrypcję) oraz dla polecającego (właściciel linku, aktywny subskrybent). Tworzenie: Promocje → Programy poleceń → Nowy program poleceń (/dashboard/promotions/referral/create). Edycja: /dashboard/promotions/referral/[referralId]. Program trzeba osobno włączyć na ofercie (zakładka Promocje oferty).

Rabat poleceń jest zawsze procentowy (0-100). Stała kwota brutto nie jest dostępna w programie poleceń (w przeciwieństwie do kuponów).

Nazwa programu

Pole wymagane, 1-120 znaków. Nazwa wewnętrzna widoczna w liście programów i w selektorze oferty. Nie jest pokazywana klientowi na stronie płatności.

Reguły poleconego (refereeRules)

Rabat dla poleconego (%)

Wymagany procent 0-100. Obniża kolejne płatności subskrypcji poleconego zgodnie z czasem trwania. Domyślnie w formularzu: 10%.

Czas trwania rabatu poleconego

Wymagany zakres trwania - w UI dostępne te same tryby co przy kuponach:

  • Jednorazowo (`once`) - rabat rozlicza się na płatności, przy której polecony użył linku; grant oznaczany jako zużyty na tym pay_….
  • Liczba płatności (`repeating_payment_count`) - pierwsze N cykli (1-999), wliczając płatność startową jako pierwszą.
  • Powtarzający się interwał (`repeating_interval`) - okres od startu subskrypcji: presety dzień/tydzień/miesiąc/kwartał/pół roku/rok albo Inna (liczba 1-999 + jednostka D/W/M/Y). Token musi spełniać ^[1-9]\d{0,2}[DWMY]$ (np. 1Y, 3M, 30D). Domyślny interwał w formularzu: 1Y.
  • Bezterminowo (`forever`) - na każdą kolejną płatność subskrypcji poleconego, dopóki wpis jest aktywny. Domyślnie wybrane w formularzu.

Reguły polecającego (referrerRules)

Rabat polecającego (%)

Wymagany procent 0-100 przyznawany właścicielowi linku po udanej konwersji poleconego. Domyślnie w formularzu: 5%.

Czas trwania rabatu polecającego

  • Jednorazowo - grant startuje z consumed: false i stosuje się przy następnej płatności cyklu polecającego po konwersji (nie na płatności poleconego).
  • Liczba płatności / interwał / bezterminowo - analogicznie jak u poleconego, ale względem subskrypcji polecającego i w granicach limitu sumy rabatów.

Maks. rabat polecającego (%)

Wymagane 0-100 (domyślnie 20). Limit sumy aktywnych procentowych grantów polecającego na jednej subskrypcji. Przy kolejnych konwersjach system przycina nowy grant do pozostałego miejsca; gdy pozostało ≤ 0, nagroda jest pomijana bez błędu (ciche pominięcie).

Maks. poleceń na klienta

Opcjonalna liczba całkowita ≥ 1. Oznacza, ile razy ten sam polecający może dostać nagrodę w ramach programu. Puste / null = bez limitu (UI: „Bez limitu”). Po osiągnięciu limitu kolejne granty są pomijane.

Widoczność w portalu subskrypcji

  • Pokaż sekcję poleceń (`showRefer`) - domyślnie włączone. Gdy wyłączone, linki nadal mogą działać technicznie, ale UI „Poleć znajomemu” jest ukryte (show_refer_hidden przy wymaganiu widoczności).
  • Pokaż wybór oferty (`showReferChoice`) - widoczne tylko gdy showRefer jest włączone; domyślnie true. Gdy true, polecający może wybrać inną kwalifikującą się ofertę rekurencyjną jako cel linku; gdy false, link zawsze wskazuje ofertę bieżącej subskrypcji.
  • Nagroda po trialu (`rewardAfterTrial`) - gdy true, nagroda polecającego powstaje dopiero po SUCCESS bez appliedPromotions.trialAccess i z totalAmount > 0. Gdy false (domyślnie w API przy braku pola; w UI formularza domyślnie zaznaczone true), grant może powstać także na płatności trialowej.

Włączenie na ofercie

W Oferta → Promocje włącz Zezwól na linki polecające i wybierz dokładnie jeden Program poleceń (ACTIVE). Przełącznik jest nieaktywny, jeśli oferta nie ma włączonej subskrypcji. REST: PUT /promotions/referrals/{qrId} z { enabled, referralId } (przy enabled: true referralId jest wymagane).

  • Oferta musi być rekurencyjna.
  • Program musi być ACTIVE i należeć do tej samej organizacji.
  • Opcjonalne eligibleQrIds w API (nieobecne w UI tworzenia) ogranicza program do wskazanych ofert; puste = wszystkie oferty organizacji.

Jak powstaje i działa link

  • Aktywny subskrybent (status ACTIVE lub TRIAL) otwiera kartę poleceń w szczegółach subskrypcji / portalu.
  • System tworzy lub zwraca istniejący ReferralLink dla pary (program, customer) - kod 10 znaków uppercase, unikalny w organizacji; równolegle zakładany jest wewnętrzny kod kuponu o nielimitowanych użyciach.
  • URL zawiera `?ref=KOD`. Preferowane opakowanie przez Source Link, ale sam parametr ref wystarcza do atrybucji.
  • Atrybucja w przeglądarce trafia do sessionStorage (zevio_referral_attribution) w kontekście qrId.
  • Self-referral (własny link) kończy się błędem errors.referral.self_referral.

Przebieg konwersji (kolejność systemu)

  • 1. Polecony finalizuje płatność SUCCESS na ofercie z włączonymi linkami i pasującym programem.
  • 2. redeemAfterPayment przyznaje grant poleconego (side: referral), zwiększa conversionCount linku, ustawia subscription.referralLinkId, emituje promotion.redeemed.
  • 3. tryGrantPendingReferralRewardsForPayment próbuje przyznać nagrodę polecającemu (z uwzględnieniem rewardAfterTrial, limitu sumy % i limitu liczby poleceń).
  • 4. Przy sukcesie grantu polecającego emitowane jest referral.converted z referralLinkId, referrerSubscriptionId, refereeSubscriptionId, refereePaymentId, grantKey, redemptionId.

Składanie z trialem, zniżką oferty i kuponami

  • W podglądzie checkoutu kod/link procentowy staje się generalDiscount i zastępuje zniżkę ogólną oferty; trial oferty jest zwykle zachowany przy rabacie procentowym.
  • Na rozliczeniu cykli aktywne wpisy procentowe sumują się (cap 100%). Aktywny rabat fixed_gross z kuponu wygrywa sam i wypiera bazowe promocje oferty.
  • Nowy kupon na istniejącej subskrypcji oznacza wcześniejsze wpisy kuponowe jako replacedAt; wpisów referral nie zastępuje.
  • Kodu referral nie da się dodać przez edycję zawartości subskrypcji (applyCouponCodeToSubscription) - tylko przez checkout z ref.

Statusy programu, archiwizacja, usuwanie

  • PATCH statusu: tylko ACTIVE lub INACTIVE (nie ARCHIVED).
  • Archiwizacja: POST .../archive → ARCHIVED. Ponowna archiwizacja → errors.referral.program_archived. Przywracania brak.
  • GET / PATCH zarchiwizowanego programu → errors.referral.program_not_found.
  • Usuwanie możliwe tylko gdy linkCount = 0 i conversionCount = 0; w przeciwnym razie errors.referral.program_in_use (409).
  • Istniejące linki po archiwizacji nie powinny obsługiwać nowych płatności (program niedostępny / inactive).

Panel szczegółów programu

Na stronie programu widzisz: reguły, limity, flagi widoczności, listę linków (kod, polecający, liczba konwersji), eksport oraz akcje Archiwizuj / Usuń. Statystyki konwersji rosną przy redeem poleconego.

Warunki wygenerowania linku (ineligibility)

  • subscription_not_active - subskrypcja poza ACTIVE/TRIAL.
  • referral_not_enabled / referral_program_unavailable - oferta bez code redemption lub program nieaktywny / nieprzypisany.
  • show_refer_hidden - UI ukryte przy showRefer=false gdy wymagana widoczność.
  • not_recurring - oferta bez subskrypcji.

Klucze błędów

  • errors.referral.program_not_found | program_inactive | program_archived | program_in_use
  • errors.referral.self_referral | subscription_required
  • errors.promotion.not_recurring | code_redemption_disabled | qr_not_eligible
  • errors.referral.cap_reached / max_referrals_reached - zdefiniowane w katalogu błędów; w runtime limity są zwykle egzekwowane przez ciche pominięcie grantu.

Identyfikatory

  • Program: rfl_ + 12 znaków alfanumerycznych.
  • Link: rlink_ + 12.
  • Redemption: pred_….
  • Grant key polecającego: referrer_sub_{refereeSubscriptionId} (legacy: referrer_{paymentId}).