Dokument sprzedaży SMS-em (rezerwacja bez konta)
👤 Instrukcja dla klienta i recepcji
Klient, który rezerwuje kort przez publiczny kalendarz i nie zakłada konta, podaje tylko numer telefonu. Nie ma skrzynki, na którą Fakturownia mogłaby wysłać e-paragon — dlatego po zaksięgowaniu płatności online dostaje SMS z linkiem do dokumentu:
Twój dokument sprzedaży z AcePark: https://…
Link otwiera:
- e-paragon (paragony.pl) — gdy wystawiony został paragon fiskalny,
- fakturę (publiczny link Fakturowni, bez logowania) — gdy klient ma zadeklarowaną fakturę.
Kiedy SMS nie wychodzi:
| Sytuacja | Co się dzieje zamiast tego |
|---|---|
| Klient ma konto lub podał prawdziwy adres e-mail | dokument idzie e-mailem, tak jak dotychczas |
| Płatność rozliczona w klubie (gotówka / karta) | klient dostaje wydruk paragonu na miejscu |
| Brak numeru telefonu przy rekordzie klienta | nic nie wychodzi, w logach zostaje ostrzeżenie |
| Dokument nie ma jeszcze linku (opóźniona fiskalizacja) | nic nie wychodzi; wysyłka ponowi się przy kolejnym przetworzeniu płatności |
Dokument od razu na stronie po płatności
Na stronie „Płatność zakończona!" (/pay/success) pojawia się kafelek Dokument sprzedaży z przyciskiem otwierającym e-paragon albo fakturę. Klient nie musi czekać na SMS-a — może otworzyć dokument od razu.
Przelewy24 odsyła klienta na tę stronę czasem szybciej, niż dojdzie notyfikacja wystawiająca dokument, więc kafelek przez ~25 sekund pyta o niego w tle („Przygotowujemy Twój dokument…"). Jeśli w tym czasie dokument się nie pojawi, kafelek mówi, gdzie on trafi — SMS-em albo mailem, zależnie od tego, czy klient ma skrzynkę.
Ponowne wysłanie dokumentu
Przycisk „Wyślij ponownie e-paragon" w liście płatności działa jak dotychczas, ale dla klienta bez skrzynki wysyła SMS z linkiem, a nie e-mail. Pracownik nie musi nic wybierać — kanał dobiera się sam po adresie klienta.
Treść SMS-a
Treść jest edytowalna w Ustawieniach → Powiadomienia, typ „Link do dokumentu sprzedaży (SMS)" (payment_document_link). Dostępna zmienna: {{documentUrl}}. Kanały e-mail i push są dla tego typu wyłączone.
🛠 Dokumentacja techniczna
Skąd bierze się problem
Publiczny kalendarz zakłada gościowi rekord player z adresem mintowanym z numeru telefonu (guest+48…@public.acepark.pl, patrz lib/actions/public-booking-shared.ts). Ten sam mechanizm ma klient lokalny zakładany na recepcji. Fakturownia wysyła dokument na adres z dokumentu — czyli w nicość.
Przepływ
Moduł lib/document-sms.ts
| Funkcja | Rola |
|---|---|
shouldSendDocumentBySms | adres to placeholder (isPlaceholderEmail) i płatność online (p24 / transfer) |
documentGroupKey | jeden klucz na dokument, żeby pakiet płatności z jednym paragonem wysłał jeden SMS |
resolveDocumentUrl | faktura → publiczny link z tokenem; paragon → wyłącznie e_receipt_view_url z paragony.pl |
deliverDocumentLinkBySms | jeden klient, jeden dokument — używane też przez ręczne „wyślij ponownie" |
sendDocumentLinksBySms | wsad z processPaymentStatusChange: grupuje, wysyła, stempluje |
Numer telefonu pochodzi z getPlaceholderContact (lib/local-user-contact.ts) — dla gościa z kalendarza z rekordu player, dla klienta lokalnego z local_user.
Dla paragonu wysyłany jest tylko link fiskalny z paragony.pl (toEReceiptViewUrl). Strona dokumentu w Fakturowni to co innego niż e-paragon i wysłanie jej zamiast niego już raz wprowadziło klientów w błąd.
Endpoint dla strony podziękowania
GET /api/public/payment/document?token=… — publiczny (wpisany w publicRoutes w middleware.ts przez prefiks /api/public/payment), limit 20 zapytań na minutę. Token linku płatności jest poświadczeniem, tym samym, którym klient płacił; endpoint oddaje wyłącznie adres dokumentu i tylko dla płatności ze statusem opłaconym. Adres liczy ten sam resolveDocumentUrl, co wysyłka SMS-owa.
Komponent components/payments/PaymentDocumentCard.tsx odpytuje go 6 razy co 4 sekundy. Kanał w komunikacie zapasowym wylicza strona serwerowo z isPlaceholderEmail(link.player_email).
Idempotencja
Kolumna payment.document_sms_sent_at (migracja 0256) jest stemplowana dopiero po tym, jak JustSend przyjmie wiadomość. Nieudana wysyłka zostawia kolumnę pustą i ponowi się przy kolejnym przetworzeniu płatności (np. przez /api/invoices/regenerate-missing). Udana nie powtórzy się nigdy — również przy ponowionej notyfikacji z Przelewy24.
Wyłączone wysyłki e-mail
Żeby nie wysyłać na adresy, których nikt nie czyta:
lib/actions/invoice-generation.ts→deliverInvoiceByEmailpomijasendInvoiceByEmaildla placeholderów,lib/actions/receipt-management.ts→mailEReceiptpomijasend_by_email.jsondla placeholderów, adeliverEReceipt(ręczne ponowienie) przełącza się na SMS.
Powiadomienie
payment_document_link — kategoria payment, kanał SMS, klucz danych documentUrl. Definicja w lib/notification-config.ts, teksty w messages/pl.json / messages/en.json, wiersze w notification_types / notification_texts zakłada migracja 0256.