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 pary klucz-wartość. Maks. 4 KB.

Przykładowe żądanie

curl -X POST https://api.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

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