Wysyłanie sprzedaży i własnych danych do LinkHarbor

LinkHarbor przyjmuje też dane z zewnątrz. Dla dwóch przypadków istnieją osobne endpointy z własnymi sekretami – nie potrzebujesz do nich klucza API: callbacki sprzedaży zgłaszają sprzedaże z Twojego sklepu, dzięki czemu widzisz w statystykach, który link przyniósł przychód. Integracja „Custom (API)” przenosi dane na żywo z Twoich własnych narzędzi na Twoją stronę jako widżet i może wywoływać powiadomienia push.

#Callbacki sprzedaży: przypisywanie sprzedaży

Jak współdziałają ID kliknięcia (lt_click_id), przypisywanie i raportowanie, wyjaśnia artykuł Przypisywanie konwersji i sprzedaży; tutaj znajdziesz wszystkie pola i odpowiedzi dla programistów. W skrócie: gdy LinkHarbor przekierowuje policzone kliknięcie do celu http lub https, dołącza parametr lt_click_id; Twój sklep go zapamiętuje i odsyła po zakupie.

Tworzenie sekretu callbacku

1. Otwórz „Callback i API”
2. W karcie „Sekrety callbacków” kliknij „+ Utwórz nowy sekret”
3. Opcjonalnie nadaj nazwę, na przykład „Callback sklepu”, i kliknij „Utwórz sekret”
4. Od razu skopiuj sekret – jest pokazywany tylko raz

Kto

Właściciele i admini, od planu Creator Pro. W Creator Free widać komunikat „Sekrety callbacków są dostępne od planu Creator Pro.”

Ile

Do 5 sekretów na workspace, na przykład jeden na sklep.

„Edytuj”

Zmiana nazwy i ustawienie statusu „Aktywny” lub „Nieaktywny”. Przy nieaktywnym sekrecie API odrzuca callbacki.

„↺ Zmień”

Generuje nowy sekret; stary od razu przestaje działać.

„Ostatni callback:”

Pokazuje, kiedy sekret był ostatnio użyty z powodzeniem.

Wysyłanie callbacku

curl -X POST https://dock.at-harbor.com/v1/callbacks/sale \
  -H "Content-Type: application/json" \
  -H "X-Callback-Secret: $LH_CALLBACK_SECRET" \
  -d '{
    "click_id": "3f1c2a9e-8d4b-4a51-9f0e-6b7c1d2e3f40",
    "order_id": "A-10023",
    "amount": "49.90",
    "currency": "EUR",
    "occurred_at": "2026-11-01T10:15:00Z"
  }'
# → {"ok":true,"conversion_id":123}

Opcjonalny podpis

Oprócz sekretu możesz wysłać nagłówek X-Callback-Signature. Zawiera on sha256= i podpis HMAC-SHA256 surowej treści w hex. Kluczem nie jest sam sekret, lecz jego hash SHA-256 w postaci binarnej. Jeśli wyślesz ten nagłówek, musi być poprawny – w przeciwnym razie callback zostanie odrzucony.

<?php
$body = json_encode($payload);
$key  = hash('sha256', getenv('LH_CALLBACK_SECRET'), true); // binarny hash sekretu
$sig  = 'sha256=' . hash_hmac('sha256', $body, $key);
// Nagłówki: X-Callback-Secret i X-Callback-Signature: $sig, treść: $body

Gdzie widać sprzedaże

Zgłoszone sprzedaże pojawiają się jako konwersje w Twoich statystykach, zobacz Przypisywanie konwersji i sprzedaży. Przez API odczytujesz je z read:stats pod /v1/stats/…/conversions/breakdown.

#Custom (API): Twoje własne dane na żywo

Dzięki integracji „Custom (API)” każdy program, który potrafi wysyłać żądania HTTP – wtyczka serwera gry, bot, skrypt cron – może wysyłać dane do LinkHarbor. Stają się one widżetem na żywo na Twojej stronie, a reguły push mogą powiadamiać Twoich obserwujących.

Łączenie

1. Otwórz „Integracje” w workspace
2. Wybierz „Custom (API)” i wpisz nazwę
3. Po połączeniu okno pokazuje „URL ingest” i „Secret” (z opcją „Pokaż secret”)
4. Zapisz obie wartości w swoim narzędziu

Integracje są dostępne od planu Creator Pro. URL ingest i sekret widzą tylko właściciele i admini, także później w widoku szczegółów integracji. Rozłączenie i ponowne połączenie tworzy nowy sekret. Jak ogólnie łączyć integracje, wyjaśnia artykuł Łączenie integracji.

Wysyłanie danych

curl -X POST "$INGEST_URL" \
  -H "Authorization: Bearer $INGEST_SECRET" \
  -H "Content-Type: application/json" \
  -d '{
    "event": "player.joined",
    "event_id": "join-2026-11-01T20:01:02Z-steve",
    "data": { "player": "Steve" },
    "state": {
      "type": "game_server",
      "name": "Survival SMP",
      "online": true,
      "players_online": 3,
      "players_max": 20
    }
  }'
# → {"ok":true,"event_id":4711,"duplicate":false,"event_type":"player.joined"}

event

Dowolna nazwa zdarzenia, na przykład player.joined. Jest zamieniana na małe litery i to na nią reagują reguły push. Bez event zdarzenie nazywa się state.updated.

event_id

Opcjonalny klucz, który zapobiega podwójnemu przetworzeniu. Jeśli ten sam event_id zostanie wysłany ponownie, LinkHarbor odpowiada duplicate: true i nic nie robi.

data

Wartości dla symboli zastępczych w tekstach push, na przykład {player}. Do 40 kluczy, tylko proste wartości.

state

Pełny stan widżetu. Całkowicie zastępuje poprzedni. type to game_server (karta serwera gry) lub status (karta statusu).

Zamiast Authorization: Bearer możesz też wysłać sekret w nagłówku X-LinkHarbor-Secret. Z jednego adresu IP dozwolonych jest 120 wywołań na minutę. Opcjonalnie podpisujesz treść: nagłówek X-LinkHarbor-Signature zawiera sha256= i podpis HMAC-SHA256 surowej treści z sekretem jako kluczem. Jeśli go wyślesz, musi być poprawny.