API konwersji

API konwersji pozwala raportować konwersje nie-Stripe do Selgeo — rejestracje, przesyłanie formularzy, bezpłatne wersje próbne, uaktualnienia lub dowolne zdarzenia niestandardowe. Wywołujesz go z serwera po wystąpieniu konwersji, a Selgeo przypisuje ją do partnera polecającego na podstawie click_id lub promo_code.

Wersja API: v1

Punkt końcowy: POST /api/v1/conversions

Uwierzytelnianie

Authorization: Bearer sk_test_YOUR_KEY

Nigdy nie ujawniaj kluczy tajnych w kodzie frontendowym

Klucze tajne (sk_*) powinny być używane tylko w kodzie po stronie serwera.

Treść żądania

Pole	Typ	Wymagane	Opis
click_id	string (UUID)	Warunkowe	ID kliknięcia ze snippeta śledzącego. Wymagane jeśli nie podano promo_code.
promo_code	string	Warunkowe	Kod promocyjny do atrybucji. Wymagane jeśli nie podano click_id.
external_transaction_id	string	Tak	Twój unikalny identyfikator tej konwersji. Używany do deduplikacji. Maks. 255 znaków.
event_type	string	Tak	Typ zdarzenia konwersji (np. signup, purchase, upgrade). Maks. 100 znaków.
amount_cents	integer	Nie	Wartość konwersji w centach. Domyślnie: 0.
currency	string	Warunkowe	3-literowy kod waluty ISO 4217. Wymagane gdy amount_cents > 0.
occurred_at	string (ISO 8601)	Nie	Kiedy nastąpiła konwersja. Domyślnie bieżący czas.
prospect_email	string (email)	Nie	Adres email użytkownika dokonującego konwersji. Używany do wykrywania samoodniesień.
metadata	object	Nie	Dowolne niepersonalne pary klucz-wartość do własnego użytku. Nie umieszczaj danych osobowych ani danych szczególnych kategorii. Maks. 4 KB.

Nie umieszczaj danych osobowych w metadata

Nie wysyłaj zbędnych danych osobowych i nigdy nie wysyłaj danych szczególnych kategorii (art. 9 RODO — na przykład danych o zdrowiu, pochodzeniu etnicznym, religii lub poglądach politycznych) w polu metadata. Selgeo nie przetwarza celowo danych szczególnych kategorii i nie jest w stanie ich niezawodnie wykryć w polach o dowolnej treści, dlatego ich niewprowadzanie należy do Twoich obowiązków jako administratora. Pamiętaj, że prospect_email to dane osobowe: podajesz je wyłącznie do wykrywania oszustw polegających na samopoleceniu i są przetwarzane w ramach Twojej odpowiedzialności jako administratora.

Przykładowe żądanie

curl -X POST https://app.selgeo.com/api/v1/conversions \
  -H "Authorization: Bearer sk_test_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "click_id": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
    "external_transaction_id": "signup_12345",
    "event_type": "signup",
    "amount_cents": 0
  }'

Priorytet atrybucji

Gdy podano zarówno click_id jak i promo_code, kod promocyjny ma priorytet.

Kody statusu HTTP

Status	Znaczenie
201	Konwersja pomyślnie utworzona
400	Błąd walidacji
401	Nieprawidłowy lub brakujący klucz API
409	Zduplikowany external_transaction_id
422	Brak sygnału atrybucji lub niezgodność trybu test/live
429	Przekroczono limit szybkości

Testowanie

1. Skonfiguruj program testowy i partnera. Utwórz program w panelu sprzedawcy i zaproś partnera testowego, następnie zaloguj się do portalu partnerskiego jako ten partner i utwórz link polecający (w sekcji Linki).
2. Odwiedź swoją stronę za pomocą linku śledzącego, aby zarejestrować kliknięcie.
3. Odczytaj click_id z konsoli przeglądarki:

   __selgeo.getClickId()

4. Wyślij testową konwersję ze swojego terminala:

   curl -X POST https://app.selgeo.com/api/v1/conversions \
     -H "Authorization: Bearer sk_test_YOUR_KEY" \
     -H "Content-Type: application/json" \
     -d '{
       "click_id": "WKLEJ_TUTAJ_CLICK_ID",
       "external_transaction_id": "test_001",
       "event_type": "signup",
       "amount_cents": 0
     }'

5. Sprawdź odpowiedź — attributed powinno być true, a attribution_source powinno być "link".
6. Zweryfikuj w panelu — konwersja powinna pojawić się w Analytics, przypisana do partnera testowego.

Następne kroki

• Webhooki — otrzymywanie powiadomień gdy konwersje są przypisywane
• Tryb testowy — szczegółowy przewodnik testowania integracji
• Rozwiązywanie problemów — typowe problemy i rozwiązania