Webhooki
Sellf wysyła zdarzenia do skonfigurowanych endpointów HTTPS. Każda dostawa jest zapisywana przed wysłaniem żądania HTTP. Nieudane próby trafiają do kolejki ponowień.
Pełny zwrot płatności za subskrypcję kończy ją od razu i odbiera dostęp. Kolejny płatny okres wymaga nowego zakupu. Wygrany spór przywraca pierwotne uprawnienie, także gdy gość potwierdził adres email w trakcie sporu.
Rotacja sekretu podpisującego
Dział zatytułowany „Rotacja sekretu podpisującego”W Webhooki → Edytuj wybierz Wygeneruj nowy sekret i potwierdź. Możesz też
wywołać POST /api/v1/webhooks/{id}/rotate-secret z sesją administratora lub kluczem
API z uprawnieniem webhooks:write. Treść żądania nie jest wymagana. Odpowiedź po
sukcesie: { "data": { "id": "…", "secret": "whsec_…" } }.
Zmiana i wpis audytu są zatwierdzane atomowo. Nowy sekret jest szyfrowany w bazie
i zwracany tylko w tej odpowiedzi; panel pokazuje go do zamknięcia okna edycji.
Skopiuj go teraz do magazynu sekretów odbiornika. Po rotacji odpowiedzi API listy,
szczegółów i aktualizacji zwracają puste pole secret; wartości nie można ponownie
odczytać. Jeśli ją utracisz, wykonaj kolejną rotację. Istniejące endpointy zachowują
dotychczasowy sekret do jawnego wykonania rotacji.
Stary sekret jest unieważniany natychmiast, bez okresu przejściowego. Uzgodnij
zmianę z odbiornikiem i natychmiast podmień jego sekret weryfikacyjny. W trakcie
zmiany dostawy mogą się nie powieść. Żądania już w drodze mogą nadal mieć poprzedni
podpis; dostawy pobierane po zmianie, także ponowienia i wysyłki testowe, używają
aktualnego sekretu. Rotacja nie zmienia podpisu już wysłanego żądania HTTP. Po
aktualizacji odbiornika wyślij test i w razie potrzeby ponów nieudane dostawy.
Identyfikatory i payloady dostaw pozostają bez zmian: nadal deduplikuj po id.
Jeśli odpowiedź zaginie po zatwierdzeniu operacji, stary sekret i tak przestaje działać. Wygeneruj kolejny sekret i zainstaluj wartość z nowej odpowiedzi. Nie ponawiaj żądań rotacji automatycznie: każde udane wywołanie ponownie zmienia sekret.
Identyfikator dostawy
Dział zatytułowany „Identyfikator dostawy”{ "id": "5cb0a355-840e-4d73-8ab9-34137a763c39", "event": "purchase.completed", "timestamp": "2026-10-02T12:34:56.789Z", "data": {}}Nagłówek X-Sellf-Delivery-Id zawiera ten sam UUID co pole id na najwyższym
poziomie payloadu. Każdy endpoint otrzymuje własny identyfikator dostawy.
Automatyczne oraz ręczne ponowienia używają tego samego identyfikatora i zapisanych
danych zdarzenia. Personalizacja payloadu nie może zmienić ani usunąć pola id.
To dodatkowe pole koperty: event, timestamp, data oraz format podpisu pozostają
bez zmian.
Deduplikuj po tym identyfikatorze (deduplicate on this id). Sellf stosuje semantykę „co najmniej raz”: po timeoutcie lub przerwaniu działania nadawcy ten sam webhook może dotrzeć ponownie, nawet jeśli odbiorca obsłużył wcześniejsze żądanie.
- Sprawdź
X-Sellf-Signaturena oryginalnej treści żądania. - Sprawdź zgodność
X-Sellf-Delivery-Idz podpisanym polemid. - Zapisz identyfikator i wynik obsługi w jednej transakcji bazy odbiorcy.
- Dla wcześniej obsłużonego identyfikatora zwróć 2xx bez ponownego wysyłania e-maila lub powtarzania innych czynności.
Nagłówki X-Sellf-Event i X-Sellf-Signature nadal obowiązują. Podpis ma postać
t=<sekundy_unix>,v1=<HMAC-SHA256> i obejmuje <t>.<oryginalna_treść>, w tym pole
id. Przy ponowieniu podpis jest obliczany ponownie. Pole timestamp w zapisanym
payloadzie pozostaje stałe.
Zakupy i subskrypcje
Dział zatytułowany „Zakupy i subskrypcje”Każda pozycja purchase.completed.licenses[] zawiera expiresAt: datę ISO 8601 UTC
albo null dla licencji bezterminowej. Odbiorca nie musi dekodować tokenu.
Dla zakupów purchase.completed istnieje jedna logiczna dostawa na
zamówienie/zdarzenie/endpoint. Nowy zakup otrzymuje nowy identyfikator dostawy.
Subskrypcje wysyłają invoice.paid; każda faktura stanowi osobne zamówienie.
Błąd wystawiania licencji lub przerwana realizacja mogą zostać uzupełnione przez
kolejne zdarzenie lub weryfikację zakupu. Zapis zakończonej transakcji nie oznacza,
że wszystkie dostawy już się zakończyły.
Zamówienie przelewem opłacone kartą ze strony zamówienia wysyła purchase.completed z
order.settledVia: "stripe" i order.paymentIntentId Stripe (do uzgodnienia płatności i zwrotu);
przelew zaksięgowany przez sprzedawcę ma settledVia: "bank_transfer" i paymentIntentId: null.
customer.firstName / lastName są uzupełniane z kupującego zapisanego w orderDetails.buyer.
purchase.completed zawiera attribution, gdy zamówienie ma zapisane źródło
(Źródła zakupów): kanał, ostatni i pierwszy kontakt, urządzenie,
kraj i typ identyfikatora kliknięcia — nigdy sam identyfikator.
Pełny katalog zdarzeń, przykłady danych VAT i licencji oraz konfiguracja ponowień znajdują się w dokumentacji webhooków po angielsku.
Potwierdzenie zwrotu i opłaconego okresu
Dział zatytułowany „Potwierdzenie zwrotu i opłaconego okresu”Obiekt invoice w purchase.completed i invoice.paid zawiera obok nip pola
taxIdType (pl_nip, eu_vat, other) i taxIdCountry, wyznaczane z kraju firmy;
bez identyfikatora oba mają wartość null. Koszyk z profilem zapisuje też w
orderDetails.buyer pola tax_id_type, tax_id_country i, przy włączonym VIES, tax_id_vies.
invoice.paid wiąże data.invoice.stripeInvoiceId z
data.subscription.stripeSubscriptionId, data.product.id i data.customer.userId.
invoice.orderId i invoice.orderNumber wskazują zamówienie Sellf przypisane do tej
faktury; invoice.stripeInvoiceId pozostaje identyfikatorem Stripe.
Faktura zawiera amountPaid (główna jednostka waluty), currency i paidAt.
subscription.currentPeriodStart oraz subscription.currentPeriodEnd (ISO 8601 UTC)
pochodzą z konkretnej opłaconej pozycji subskrypcyjnej tej faktury. Jeśli nie ma
jednoznacznej pozycji bez proporcjonalnego rozliczenia z prawidłowym okresem,
pola są pomijane. Odbiorca nie powinien wyliczać opłaconego dostępu z daty dostawy
ani z późniejszej aktualizacji subskrypcji.
payment.orderNumber to numer zamówienia Sellf zwracanej płatności (null, gdy nie
jest dostępny); payment.id pozostaje identyfikatorem transakcji Sellf.
refund.issued przekazuje data.refund.stripeRefundId i rzeczywisty status
Stripe: pending, requires_action, succeeded, failed albo canceled.
Potwierdzenie pełnego zwrotu wymaga statusu succeeded, isFullRefund: true
i totalRefunded >= payment.amount przy dodatniej kwocie płatności.
Kwoty są w najmniejszych jednostkach waluty. refund.issued powstaje dokładnie raz
na ID zwrotu, z pełną kwotą tego zwrotu i rzeczywistym statusem. Każda późniejsza
zmiana statusu wysyła osobne refund.updated: stripeRefundId, previousStatus,
status, statusVersion, pełne amount, currency, totalRefunded, isFullRefund
oraz payment.statusAfter. Zmiana statusu nie oznacza kolejnej korekty faktury;
dane VAT dotyczą refund.issued. Rejestr zmian i unikalny klucz dostawy na
endpoint/wersję eliminują identyczne potwierdzenia. Odbiorca powinien zachować
najwyższe statusVersion dla ID zwrotu i pomijać starsze wersje, ponieważ dostawy
i ponowienia mogą nadejść w innej kolejności. Częściowy zwrot ustawia
partially_refunded w DB, API płatności, panelu i payloadzie.
GET /api/v1/payments/{id} zwraca refund.id, refund.status (null, jeśli nie
został zaobserwowany) i łączną kwotę refund.amount.
Dla subscription.canceled i subscription.updated pole endedAt oznacza faktyczne
ended_at Stripe, a canceledAt — moment anulowania lub złożenia takiego żądania.
endsAt oznacza termin dostępu: przy anulowaniu bez zwrotu jest to koniec okresu
potwierdzonego pozycją opłaconej faktury, również gdy Stripe kończy subskrypcję od razu.
Nieopłacone odnowienie nie przedłuża terminu. Bez potwierdzonego okresu natychmiastowe
anulowanie używa ended_at lub canceled_at, a zaplanowane podaje null. Aktualizacje
zakończonej subskrypcji lub zaplanowanego anulowania przekazują ten sam termin
w currentPeriodEnd. Zwrot kończy dostęp od razu; endedAt nadal opisuje moment zakończenia
subskrypcji w Stripe, niezależnie od terminu dostępu.
subscription.updated.previousAttributes zawiera wyłącznie poprzednie wartości znormalizowanych
pól, które się zmieniły: status, cancelAtPeriodEnd, cancelAt, canceledAt, endedAt,
trialEnd, currentPeriodStart, currentPeriodEnd, quantity, stripePriceId (camelCase, daty
ISO 8601 UTC), a changedFields wymienia ich nazwy. Surowe obiekty Stripe (items, plan, faktury)
nie są przekazywane. Zmiana pól spoza tej listy daje puste changedFields.
subscription.renewal_upcoming przychodzi 3 dni przed odnowieniem (invoice.nextPaymentAttempt
albo koniec okresu). Stripe zapowiada nadchodzącą fakturę, gdy tylko odnowienie wejdzie w okno konta,
na wielu kontach zaraz po zakupie, również przy 7-dniowej próbie, dlatego Sellf zapisuje zapowiedź
i wysyła ją w terminie. Subskrypcja anulowana, ustawiona na anulowanie z końcem okresu albo już
nieaktywna nie dostaje zapowiedzi. Gdy do odnowienia zostały najwyżej 3 dni, zapowiedź idzie od razu.
Gdy subskrypcja kończy się bez zwrotu, istniejący dostęp i licencje jej faktur wygasają
z końcem opłaconego okresu, emitując access.expired i license.expired. Zmiana terminu
licencji emituje license.updated. Wydane tokeny zachowują podpis: odbiorca musi odświeżać
CRL, która uwzględnia zamówienia po upływie terminu z rejestru. Pełny lub częściowy zwrot
po anulowaniu odbiera dostęp i odwołuje licencje od razu, również gdy zwrot przychodzi później.
Saldo kredytowe lub oczekujące rozliczenie proporcjonalne samo nie potwierdza zwrotu pieniędzy;
rejestr zwrotów aktualizują webhooki Stripe. Spór nadal zawiesza dostęp od razu.
Subskrypcje zakończone bez zapłaty (unpaid albo incomplete_expired) zachowują
access.revoked / license.revoked z revocationReason: "expired".
Spory płatnicze
Dział zatytułowany „Spory płatnicze”Podpisane dispute.created i dispute.closed działają dla wszystkich produktów,
niezależnie od licencji i license.revoked. Na istniejącym endpoincie Stripe włącz
charge.dispute.created oraz charge.dispute.closed; nowe endpointy Sellf zawierają je automatycznie.
data.dispute zawiera stripeDisputeId, stripeChargeId, rzeczywisty status
Stripe (m.in. needs_response, won, lost), reason, amount w najmniejszych
jednostkach, currency i createdAt (ISO 8601 UTC). data.payment zawiera id
transakcji Sellf, sessionId, paymentIntentId, stripeInvoiceId, subscriptionId,
kwotę i walutę zakupu. data.product.id i data.customer.userId / email wiążą
zdarzenie z produktem i klientem. Dla subskrypcji dochodzi data.subscription.id
oraz stripeSubscriptionId, jeśli jest dostępny.
accessRevoked i accessRestored opisują wynik zapisanej obsługi sporu.
Otwarcie i przegrany spór zawieszają dostęp. Po won płatność wraca do wcześniejszego
stanu (completed lub partially_refunded), a uprawnienie wraca z zachowanym terminem.
accessRestored: true oznacza rzeczywiście przywrócony dostęp; pełny zwrot,
ręczne usunięcie grantu, upływ terminu lub zakończenie subskrypcji blokują odtworzenie.
Gość odzyskuje oryginalny nieodebrany zakup. Zapisany termin obowiązuje również przy
późniejszym odebraniu, także po zmianie czasu dostępu w produkcie. Ponowienie zdarzenia nie przedłuża terminu.
Wygrana usuwa również odwołanie licencji zapisanych jako cofnięte przez ten spór.
licenseRestored i restoredLicenses opisują faktycznie zmienione licencje, z tym samym
tokenem i terminem. Ręczne cofnięcie lub zwrot blokują przywrócenie. Licencje cofnięte
przed wprowadzeniem zapisu pochodzenia nie są przywracane automatycznie. Odbiorca powinien używać flagi
accessRestored oraz payment.statusAfter, a nie samego wyniku won.
dispute.restoredAccess wymienia faktycznie przywrócone uprawnienia: productId,
userId (null dla gościa), grantedAt i expiresAt (null dla dostępu bezterminowego).
Dla gościa dochodzi guestPurchaseId. Odbiorca powinien zastosować tę listę:
ręcznie usunięty grant głównego produktu może pozostać nieobecny, gdy dostęp do dodatku wróci.
license.issued / license.expired / license.updated — Pro
Dział zatytułowany „license.issued / license.expired / license.updated — Pro”license.issued.customer zawiera email oraz userId (null dla gościa).
license.issued przychodzi raz dla każdej licencji zapisanej w Sellfie, niezależnie od
ścieżki: zakup, darmowy produkt, ręczne wydanie w panelu albo POST /api/v1/licenses
(license.issuanceSource: purchase, manual lub api). license.expired przychodzi raz,
gdy aktywna licencja minie expiresAt (sprawdzane co 30 sekund w cyklu zdarzeń);
licencja odwołana nie wygasa drugi raz. license.issued zawiera dodatkowo licenseKey,
czyli podpisany klucz do przekazania kupującemu. Inne zdarzenia cyklu licencji nie zawierają tokenu.
Nie zapisuj klucza w logach aplikacji. Subskrypcja i wysyłka zdarzeń licencji nadal wymagają Pro.
Opcja sendEmail przy ręcznym wydaniu lub wydaniu przez API uwzględnia przełącznik sklepu.
Zobacz Maile do kupujących dla zasad wysyłki.
Licencja wydana dla zamówienia z otwartym albo przegranym sporem zapisuje się jako
odwołana przez ten spór: dostajesz license.issued, a po nim license.revoked
z dispute.stripeDisputeId; purchase.completed.licenses[] jej nie zawiera. Wygrany
spór ją przywraca (license.restored).
license.updated informuje o zmianie terminu wygaśnięcia, również przy anulowaniu bez
zwrotu. Pole license.expiresAt podaje termin z rejestru; podpisany token pozostaje ten sam.
license.revoked / license.restored — Pro
Dział zatytułowany „license.revoked / license.restored — Pro”Pełny zwrot, anulowanie zamówienia i chargeback cofają wszystkie licencje zamówienia, także dodatków order bump i składników zestawu. Każda cofnięta licencja ma własne zdarzenie license.revoked. Dotyczy to również quick-pay i przelewów rozliczonych offline. Częściowy zwrot pozostawia licencje aktywne. Podpisane wartości license.order i ich hashe w CRL pozostają bez zmian.
Każda rzeczywista zmiana stanu odwołania tworzy trwałe powiadomienie. Powtórzenie niezmienionego statusu nie dodaje zdarzenia. Subskrypcja i wysyłka obu typów wymagają funkcji Pro; sam stan licencji zmienia się niezależnie od bieżącego planu sklepu.
Dane obejmują license.id, order, email, tier, domain, issuanceSource,
issuedAt, expiresAt, revokedAt, produkt i crlUrl. license.order to surowy identyfikator
podpisany w tokenie (płatność pi_…, sesja checkoutu, faktura odnowienia in_…, ID zamówienia
offline albo api_…); license.orderId i license.orderNumber wskazują zamówienie Sellf (null przy
ręcznym lub API wydaniu bez zamówienia). Pola te mają wszystkie zdarzenia license.*.
revocationReason (na górze danych i w license.revocationReason) mówi, dlaczego licencja przestała
działać: refund (pełny zwrot), dispute, manual (panel albo DELETE /api/v1/licenses/{id}) ,
subscription_cancelled lub expired (subskrypcja zakończona bez zapłaty); dla aktywnej licencji ma wartość null. Wygaśnięcie to osobne license.expired. Przywrócenie dodaje
license.restoredAt, a powiązany spór — dispute.stripeDisputeId. Token nie jest
wysyłany. Po usunięciu odwołania można używać tego samego tokenu; wygasły pozostaje wygasły.
Po każdym zdarzeniu usuń lokalny cache odpowiedniego zakresu CRL, pobierz aktualną
listę i sprawdź podpis oraz pierwotny termin tokenu. Endpoint CRL zwraca
Cache-Control: no-store. Przywrócenie nie przedłuża terminu. Aby licencja pozostała
cofnięta także po wygraniu sporu, wybierz Pozostaw licencję cofniętą w ustawieniach
wydanych licencji. Cofnięcia ze starszych wersji nie mają zapisanego powiązania ze
sporem i wymagają osobnej decyzji sprzedawcy.
Automatyczne ponowienia
Dział zatytułowany „Automatyczne ponowienia”Sellf zapisuje dostawę przed pierwszą próbą i wysyła ją od razu. Dotyczy to również przycisku Wyślij test: test ma jedną próbę, bez automatycznych ponowień. Historia dostaw domyślnie pokazuje wszystkie statusy. Filtr nieudanych dostaw obejmuje również oczekujące ponowienia i dostawy po wyczerpaniu prób.
Ponowienia nieudanych lub przerwanych zwykłych dostaw wymagają osobnego zadania
uruchamianego co minutę. Samo uruchomienie aplikacji przez PM2 go nie ustawia.
Ustaw SELLF_URL i CRON_SECRET w środowisku harmonogramu, a następnie dodaj:
* * * * * curl -fsS -H "Authorization: Bearer $CRON_SECRET" "$SELLF_URL/api/cron?job=webhook-deliveries-retry" > /dev/nullTo osobne zadanie od affiliate-sync. Kontroluj błędy wywołań w logach
harmonogramu. Brak harmonogramu wstrzymuje ponowienia, ale nie pierwszą próbę
ani zapis logów. Ręczne ponowienie starej dostawy o statusie failed aktualizuje
ten sam wpis, zachowując identyfikator dostawy.
Wygaśnięcie checkoutu Stripe
Dział zatytułowany „Wygaśnięcie checkoutu Stripe”Włącz checkout.session.expired na endpoincie Stripe wysyłającym zdarzenia do
/api/webhooks/stripe, obok zdarzeń zakończenia płatności. Nowe endpointy tworzone
w ustawieniach Sellf mają je automatycznie. Dla istniejącego endpointu dodaj to
zdarzenie w Stripe Dashboard → Workbench → Webhooks → endpoint → Edit events.
Po zmianie koszyka lub opuszczeniu checkoutu przed potwierdzeniem płatności Sellf
wygasza poprzednią Checkout Session i zmienia status jej oczekującej transakcji
na abandoned. Powrót przyciskiem „Wstecz” przywraca pierwszy krok; nowa sesja
powstaje dopiero po wybraniu „Przejdź do płatności”. Przekierowanie podczas
potwierdzania płatności zachowuje aktywną sesję. Naturalne wygaśnięcie uruchamia tę samą
zmianę przez zdarzenie Stripe. Zakończone transakcje pozostają bez zmian,
a powtórne zdarzenia można obsłużyć ponownie. Błąd zapisu zwraca HTTP 500, aby
Stripe ponowił dostawę.
Jeśli przeglądarka zamknie stronę przed otrzymaniem odpowiedzi tworzącej sesję,
nie może później wysłać żądania jej zamknięcia — nawet z opcją keepalive.
Zdarzenie wygaśnięcia musi być włączone, aby rozliczyć takie próby. Gdy strona
nadal działa, kolejka czeka z zamknięciem na zakończenie tworzenia sesji. Sellf
zachowuje też sesje, których PaymentIntent jest przetwarzany, czeka na pobranie
środków lub dodatkowe działanie klienta albo zakończył się powodzeniem.
Kontrakt zamówienia i dostępu
Dział zatytułowany „Kontrakt zamówienia i dostępu”Każdy purchase.completed zawiera data.order.orderId (trwały UUID płatności Sellf) i orderNumber,
zarówno dla Stripe, jak i przelewu. sessionId i paymentIntentId pozostają identyfikatorami
operatora; nie zastępują UUID obsługiwanego przez GET /api/v1/payments/{id}. Szczegóły płatności
zawierają również operatora, numer zamówienia, termin, instrukcje przelewu, dane zamówienia,
pozycje oraz podsumowanie kuponu i faktury dostępne na liście płatności.
purchase.completed oraz order.placed, order.cancelled, order.overdue, order.abandoned
mają data.amountUnit = "minor". Wszystkie zdefiniowane kwoty są w najmniejszych jednostkach waluty:
order.amount/grossTotal/netTotal/taxTotal, price/net/tax/gross produktu, dodatków i składników
pakietu oraz lines[].unit_price/total_price/discounted_total/net_amount/tax_amount/gross_amount.
Cena jednostkowa nadal opisuje jedną sztukę; snapshot VAT i suma zamówienia uwzględniają ilość.
Dla PLN/USD mnożnik wynosi 100, a JPY nie ma części ułamkowej. Ilość i procent VAT nie są kwotami.
Te jednostki webhooków różnią się od zapisanych cen pozycji zwracanych przez API płatności v1.
Zamówienie zawsze podaje taxSnapshotStatus: none, captured, partial, unavailable lub local.
Nieznane netto/VAT mają wartość null, zamiast zmyślonego zera. grossTotal to zapisana kwota
płatności. vatRate jest procentem albo null; unavailable nie oznacza zwolnienia z VAT.
Zdarzenia przelewu order.* zawierają access.policy (on_placement albo after_payment)
i access.grants[]: productId, status, grantedAt, expiresAt. Stany to granted,
pending_confirmation, pending_payment, expired albo revoked. Daty pochodzą z zapisanego dostępu;
dla oczekującego grantu nie zostały jeszcze nadane. null końca nadanego dostępu oznacza dostęp bezterminowy.
| Zdarzenie | Dane potrzebne odbiorcy |
|---|---|
order.abandoned |
Porzucona oczekująca płatność: ID zamówienia i operatora, stary/nowy stan, klient, kwota i VAT. customer.email ma wartość null, gdy kupujący nie podał adresu. |
seats.held |
Rezerwacja miejsc: ID rezerwacji, zamówienia, produktu, terminu/progu cenowego, data i liczba miejsc. |
seats.confirmed |
Potwierdzenie miejsc: te same identyfikatory oraz poprzedni i nowy stan. |
seats.released |
Zwolnienie miejsc: te same dane i powód (order_abandoned, order_cancelled, payment_refunded, hold_expired, reservation_released). |
access.granted |
Nadanie dostępu, również darmowego, po zakupie oraz po przejęciu zakupów gościa. |
access.updated |
Zmiana zapisanych dat lub źródła dostępu, również ręczne przedłużenie. |
access.revoked |
Usunięcie grantu wraz z faktycznym czasem odebrania i revocationReason. |
access.expired |
Upłynięcie zapisanego końca dostępu: jeden komunikat na grant/datę końca, także po odnowieniu. |
Nieopłacone zamówienia przelewem: cykl życia
Dział zatytułowany „Nieopłacone zamówienia przelewem: cykl życia”Każde zdarzenie przelewu order.* ma w data.order dodatkowo: status, payUrl (podpisany link do strony
zamówienia: stan, dane przelewu, przycisk „Wysłałem przelew”, ważny do payUrlExpiresAt), reservation
(timed — rezerwacja czasowa, invoice — faktura wystawiona, czeka na płatność bez wygasania, none),
reminderAt, releaseAt, invoiceHoldAt, transferDeclaredAt, transferDeclaredNote, cancelReason,
cancelReasonText, reopenedAt, a data.customer.locale podaje język kupującego (pl/en). Z tych pól integrator wystawia
u siebie proformę, fakturę lub własny mail (n8n, Listmonk). Każde zdarzenie jest dostarczane raz na zamówienie.
| Zdarzenie | Kiedy | Co odbiorca może zrobić |
|---|---|---|
order.placed |
Złożenie zamówienia na przelew. | Potwierdzenie z payUrl; releaseAt to termin rezerwacji wydarzenia. |
order.payment_reminder |
Minął reminderAt (domyślnie 24 h) bez wpłaty i bez faktury. |
Przypomnienie „zapłać do releaseAt” z linkiem. |
order.transfer_declared |
Kupujący kliknął „Wysłałem przelew” (raz). | Sprawdzenie wyciągu; releaseAt jest już przedłużone (domyślnie o 72 h). |
order.invoice_issued |
Dla nieopłaconego zamówienia wystawiono fakturę (w Sellf albo POST /api/v1/payments/:id/invoice-issued). |
Status „faktura wystawiona, czeka na płatność”: reservation = invoice, releaseAt = null, brak wygasania. |
order.cancelled |
Anulowanie: cancelReason = payment_window_expired (automatycznie po releaseAt) albo admin z tekstem administratora w cancelReasonText. reservation = none, reminderAt/releaseAt mają wartość null. customer.userId jest taki sam jak w seats.released. |
Informacja dla kupującego, korekta faktury; lateTransferPolicy = admin_decision. |
order.overdue |
Minął termin płatności zamówienia bez rezerwacji czasowej. | Ponaglenie. |
order.reopened |
Administrator przyjął przelew, który doszedł po anulowaniu (po cenie z zamówienia, także ponad limit miejsc). | Powiązanie wpłaty: previousStatus = cancelled; zaraz po nim purchase.completed. |
order.participants_updated |
Kupujący uzupełnił listę uczestników po zapłacie (opcja produktu „uzupełnię później”). Wysyłane raz na zamówienie. | orderDetails.participants.people zawiera pełną listę (first_name, last_name, email), orderDetails.quantity.value liczbę; purchase.completed miało pustą listę. |
Rezerwacja czasowa dotyczy wydarzeń i jest ustawiana przez sprzedawcę (Ustawienia → Płatności → Przelew
tradycyjny). Zwykłe produkty nie wygasają. Zaplanuj /api/cron?job=transfer-reservations co 5 minut.
Zdarzenie dostępu podaje customer, product, access.id, grantedAt, expiresAt,
statusBefore/statusAfter, reason i actor (user, api_key albo system; dla systemu ID jest null).
access.granted i access.updated podają też grantSource: skąd pochodzi dostęp, zapisane raz przy
nadaniu (purchase, bundle, bank_transfer, subscription, free, manual albo unknown dla nadań
starszych niż to pole). Używaj grantSource zamiast reason: reason zostaje bez zmian dla istniejących
integracji, ale bywa wywnioskowane (np. free_product z ceny), więc płatny produkt odebrany z kuponem
100% ma grantSource: "free".
Pola główne accessGrantedAt/accessExpiresAt zawierają te same zapisane daty.
access.granted i access.updated podają też accessEndsAt: zapisany koniec dostępu, a dla
subskrypcji koniec bieżącego opłaconego okresu (null przy dostępie bezterminowym). Subskrypcja wysyła
access.updated (reason: "subscription_renewed") raz na odnowiony okres; powtórzone zdarzenia
Stripe dla tego samego okresu nie dają kolejnych aktualizacji.
access.revoked i access.expired podają revocationReason: refund, dispute, manual,
subscription_cancelled albo expired (subskrypcja zakończona bez zapłaty lub naturalny koniec).
reason zachowuje dotychczasowe znaczenie (skąd był dostęp: purchase, subscription…).
sourceOrders zawiera powiązane zapisane zamówienia; sourceOrder jest wypełnione tylko przy jednym
jednoznacznym zamówieniu. Ręczne lub niepowiązane granty mogą nie mieć zamówienia. occurredAt
opisuje zmianę, a timestamp koperty przygotowanie dostawy. Nie należy wyliczać dostępu ze stanu
płatności ani z chwili odebrania webhooka — służą do tego jawny stan i zapisane daty.
Zmiany są zapisywane transakcyjnie i trafiają do podpisanej kolejki ze stabilnym kluczem.
Ponowienie zachowuje ID dostawy — odbiorca deduplikuje po tym ID. Długotrwały proces produkcyjny
obsługuje zmiany i wygaśnięcia co 30 sekund; build i testy nie uruchamiają tego harmonogramu.
W środowisku serverless trzeba zaplanować uwierzytelniony /api/cron?job=business-events.
Dotychczasowe zadanie access-expired korzysta z tego samego producenta. Zadanie ponowień dostaw
webhooków nadal powinno być skonfigurowane na wypadek przejściowych błędów HTTP.
Kolejność dostaw pomiędzy workerami i ponowieniami nie jest gwarantowana. Stan grantu aktualizuj według occurredAt, pomijając starszą zmianę odebraną później.
Podstawienie {{order_id}} preferuje wewnętrzny UUID, gdy jest dostępny; identyfikatory operatora i dotychczasowe klucze dostaw pozostają bez zmian.
Własne pola darmowego checkoutu
Dział zatytułowany „Własne pola darmowego checkoutu”Darmowy checkout waliduje wartości według tych samych definicji produktu co płatny. Przed wysłaniem linka wartości trafiają do prywatnego kontekstu żądania. Link zawiera losowy UUID, a nie domenę ani inne odpowiedzi. Po potwierdzeniu kontekst jest powiązany ze zweryfikowanym adresem klienta i produktem. Pending grant przy innym logowaniu korzysta z tego samego zapisu; nie zależy od edytowalnego user_metadata ani nie umieszcza odpowiedzi w tokenie uwierzytelnienia.
Dostęp zachowuje custom_field_values, a access.* i lead.captured podają znormalizowany
snapshot jako customFieldValues. Zapis trafia do wystawiania licencji, także dla
_sellf_license_domain. Ponowne potwierdzenie zachowuje klucz free_<userId>_<productId>
i dotychczasowy token licencji. Konteksty oczekujące mają ważność 30 dni; przejęte są czyszczone
po jednym dniu, lecz snapshot w grancie pozostaje.
Ręczne wystawianie również respektuje definicję produktu: pole domeny wymagane musi być
wypełnione, opcjonalne może zostać pominięte, a produkt bez takiego pola otrzymuje token bez
claims.domain. Brak wymaganych wartości zwraca HTTP 400 przed podpisaniem.
Faktury, partnerzy, prośby o zwrot i katalog
Dział zatytułowany „Faktury, partnerzy, prośby o zwrot i katalog”Te zdarzenia zapisują się w tej samej transakcji co zmiana (jak zdarzenia dostępu) i idą tą samą
podpisaną kolejką. Każde ma actor, occurredAt i (poza wypłatami) product. Kwoty są w
jednostkach mniejszych (amountUnit = "minor", czyli grosze dla PLN). Ponowione z kolejki zdarzenie
ma ten sam klucz dostawy, więc odbiorca dostaje je raz; mimo to deduplikuj po id koperty.
| Zdarzenie | Kiedy | Pola do decyzji odbiorcy |
|---|---|---|
invoicing.issued |
Dostawca (Fakturownia) wystawił fakturę sprzedaży. | invoice.id/number/providerInvoiceId/viewUrl/attempt/paymentSynced, order (ID, numer, kwota, waluta), customer. |
invoicing.failed |
Próba wystawienia się nie udała. Raz na próbę. | invoice.attempt, invoice.error (komunikat dostawcy), invoice.willRetry (false po 5. próbie). |
invoicing.corrected |
Wystawioną fakturę oznaczono jako skorygowaną. | invoice.number, statusBefore/statusAfter, order. |
commission.accrued |
Partner zarobił prowizję od opłaconego zamówienia. | partner (memberId, code, displayName, status), commission.amount/currency/baseAmount/eligibleAt/paidAt/livemode, order. |
commission.reversed |
Zwrot cofnął (część) prowizji. | commission.amount jest ujemne; te same identyfikatory. |
payout.reserved |
Właściciel zatwierdził prowizje do wypłaty (rezerwacja). | payout.id/amount/currency/cutoff/payeeReference/commissionIds, partner. product = null. |
payout.paid |
Wypłatę oznaczono jako zapłaconą. | payout.bankReference/invoiceReference/bankAmount/paidAt. |
payout.cancelled |
Zarezerwowaną wypłatę anulowano; prowizje wracają do salda. | payout.statusBefore = "reserved". |
refund.requested |
Kupujący złożył prośbę o zwrot. | refundRequest.id/requestedAmount/currency/reason, order, customer. |
refund.request_approved / refund.request_rejected / refund.request_cancelled |
Prośbę rozpatrzono albo wycofano. | refundRequest.statusBefore/statusAfter/adminResponse/processedAt. Sam zwrot pieniędzy to refund.issued. |
product.published / product.unpublished |
Zmienił się is_active albo utworzono/usunięto aktywny produkt. |
product (id, slug, isActive, availableFrom/Until, productType), availability.before/after, deleted. |
product.price_changed |
Zmieniła się cena, cena promocyjna, koniec promocji, cena cykliczna albo waluta. | price.before/after: price, salePrice, salePriceUntil, recurringPrice, currency w jednostkach mniejszych. |
product.sold_out |
Miejsca wstrzymane (niewygasłe) i potwierdzone osiągnęły pojemność terminu wydarzenia. | session.id/label/startsAt/capacity/taken/remaining, reservation, która go wypełniła. Zwolnione później miejsca zgłasza seats.released. |
actor to zalogowany administrator (user) albo klucz API (api_key) przy zmianach z panelu lub API v1, a system przy zmianach automatycznych (synchronizacja, zadania cykliczne; działania kupującego zgłaszają user). Prośba o zwrot cofnięta do pending po nieudanym zwrocie w Stripe jest ogłaszana ponownie jako refund.requested ze statusBefore = "approved".
Prowizja partnera staje się wypłacalna, gdy minie eligibleAt; Sellf nie wysyła osobnego zdarzenia
na ten moment, punktem zatwierdzenia jest payout.reserved. Okna publikacji (availableFrom/Until)
są w treści, ale sam upływ czasu nie generuje zdarzenia.
Zgłoszenia PlayerStack
Dział zatytułowany „Zgłoszenia PlayerStack”Formularze potwierdzane mailem i zgoda marketingowa.
Dane do maili kupujących
Dział zatytułowany „Dane do maili kupujących”Zobacz Maile do kupujących. Kwoty są w najmniejszych jednostkach waluty.
| Zdarzenie | Dane do zbudowania maila |
|---|---|
order.placed, order.payment_reminder |
customer.email/locale, order.transfer (odbiorca, konto, bank, tytuł), order.amount/currency, order.paymentDeadline, order.payUrl, terminy rezerwacji i pozycje zamówienia. |
order.cancelled |
Identyfikator zamówienia, order.cancelReason i order.cancelReasonText. |
purchase.completed |
Kupujący, produkty, kwota, zamówienie i order.settledVia; potwierdzenie płatności Stripe lub przelewu. customer.locale i buyerMail.event_date/event_online_url odpowiadają danym maila Supabase; adres wydarzenia tylko przy aktywnym dostępie. |
order.participants_needed |
Email i język kupującego, produkt (id/nazwa/slug), zamówienie (id/numer/kwota/waluta/status), orderDetails, reminder.stage (1: po 24 h; 2: dwa dni przed wydarzeniem), reminder.participantsUrl (osobisty link). Stały identyfikator dostawy na zamówienie i etap. Standardowe zasady rejestracji webhooków, bez dodatkowej bramki Pro. |
license.issued |
licenseKey, kupujący, produkt, wariant, ważność i zamówienie. Dotychczasowa bramka Pro pozostaje. |
Link uczestników i klucz licencji przekazuj wyłącznie właściwemu kupującemu. Sprawdzaj podpis webhooka i nie zapisuj tych danych w logach aplikacji. Kolejka szyfruje treść wydania licencji i powiadomienia o uczestnikach kluczem APP_ENCRYPTION_KEY instancji; widok logów pokazuje zaszyfrowany zapis.
Język kupującego i potwierdzone leady
Dział zatytułowany „Język kupującego i potwierdzone leady”data.customer.locale jest zawsze obecne (pl lub en) w purchase.completed, license.issued, order.placed, order.payment_reminder, order.cancelled, order.participants_needed, refund.issued, lead.captured, waitlist.signup, access.expired oraz zdarzeniach subskrypcji zawierających kupującego. Język pochodzi z danego zamówienia, transakcji, subskrypcji lub leada, a nie z innego zakupu pod tym samym adresem email. Starsze dane bez zapisanego języka korzystają z języka sklepu: shop_config.custom_settings.default_locale (pl lub en, ustawiane przez API konfiguracji sklepu). Przy braku ustawienia obowiązuje domyślny język aplikacji. Żądanie zapisu na listę oczekujących przyjmuje opcjonalne locale o tych samych wartościach. Ponowienie dostawy zachowuje pierwotny język. Wybór pól w konfiguracji endpointu może celowo pomijać pola kupującego. Potwierdzenie leada produktu emituje jedno lead.captured: identyfikator leada, źródło, zgoda i daty potwierdzenia trafiają do tego samego zdarzenia co szczegóły produktu, daty dostępu, własne pola oraz wydana licencja. Ponowne potwierdzenie tego samego leada zachowuje klucz dostawy. Zapis na samą listę zachowuje pola leada i zgody bez dostępu do produktu.