Inviare vendite e dati propri a LinkHarbor

LinkHarbor accetta anche dati dall’esterno. Per due casi esistono endpoint dedicati con secret propri – non ti serve una chiave API: i callback di vendita segnalano le vendite del tuo shop, così vedi nelle statistiche quale link ha portato fatturato. L’integrazione «Custom (API)» porta sulla tua pagina, sotto forma di widget, dati live dai tuoi strumenti e può attivare notifiche push.

#Callback di vendita: associare le vendite

Come si combinano ID del clic (lt_click_id), associazione e report è spiegato in Attribuire conversioni e vendite; qui trovi tutti i campi e le risposte per gli sviluppatori. In breve: quando LinkHarbor reindirizza un clic conteggiato a una destinazione http o https, aggiunge il parametro lt_click_id; il tuo shop lo memorizza e lo rimanda dopo l’acquisto.

Creare un secret di callback

1. Apri «Callback e API»
2. Nella scheda «Secret di callback» clicca su «+ Crea nuovo secret»
3. Se vuoi, dagli un nome, per esempio «Callback negozio», e clicca su «Crea secret»
4. Copia subito il secret – viene mostrato una sola volta

Chi

Proprietari e admin, da Creator Pro. In Creator Free compare «I secret di callback sono disponibili a partire da Creator Pro.»

Quanti

Fino a 5 secret per workspace, per esempio uno per shop.

«Modifica»

Cambia il nome e imposta lo stato su «Attivo» o «Inattivo». Con un secret inattivo, l’API rifiuta i callback.

«↺ Rigenera»

Genera un nuovo secret; quello vecchio smette subito di funzionare.

«Ultimo callback:»

Mostra quando il secret è stato usato l’ultima volta con successo.

Inviare un callback

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}

Firma facoltativa

Oltre al secret puoi inviare l’header X-Callback-Signature. Contiene sha256= e la firma HMAC-SHA256 del corpo grezzo in esadecimale. La chiave non è il secret stesso, ma il suo hash SHA-256 in forma binaria. Se invii l’header, deve essere corretto – altrimenti il callback viene rifiutato.

<?php
$body = json_encode($payload);
$key  = hash('sha256', getenv('LH_CALLBACK_SECRET'), true); // hash binario del secret
$sig  = 'sha256=' . hash_hmac('sha256', $body, $key);
// Header: X-Callback-Secret e X-Callback-Signature: $sig, corpo: $body

Dove vedi le vendite

Le vendite segnalate compaiono come conversioni nelle tue statistiche, vedi Attribuire conversioni e vendite. Tramite l’API le leggi con read:stats sotto /v1/stats/…/conversions/breakdown.

#Custom (API): i tuoi dati live

Con l’integrazione «Custom (API)» qualsiasi programma in grado di inviare richieste HTTP – un plugin per game server, un bot, uno script cron – può inviare dati a LinkHarbor. Diventano un widget live sulla tua pagina, e le regole push possono avvisare i tuoi follower.

Collegare

1. Apri «Integrazioni» nel workspace
2. Scegli «Custom (API)» e inserisci un nome
3. Dopo il collegamento, la finestra di dialogo mostra l’«URL di ingest» e il «Secret» (con «Mostra secret»)
4. Salva entrambi nel tuo strumento

Le integrazioni sono disponibili da Creator Pro. Solo proprietari e admin vedono URL di ingest e secret, anche in seguito nella vista di dettaglio dell’integrazione. Scollegando e ricollegando si crea un nuovo secret. Come collegare le integrazioni in generale è spiegato in Connettere un’integrazione.

Inviare dati

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

Nome libero dell’evento, per esempio player.joined. Viene convertito in minuscolo ed è il nome a cui reagiscono le regole push. Senza event, l’evento si chiama state.updated.

event_id

Chiave facoltativa che evita la doppia elaborazione. Se lo stesso event_id viene inviato di nuovo, LinkHarbor risponde con duplicate: true e non fa nulla.

data

Valori per i segnaposto nei testi push, per esempio {player}. Fino a 40 chiavi, solo valori semplici.

state

Lo stato completo del widget. Sostituisce interamente quello precedente. type è game_server (scheda game server) o status (scheda di stato).

Invece di Authorization: Bearer puoi inviare il secret anche nell’header X-LinkHarbor-Secret. Sono consentite 120 chiamate al minuto per indirizzo IP. Facoltativamente firmi il corpo: l’header X-LinkHarbor-Signature contiene sha256= e la firma HMAC-SHA256 del corpo grezzo con il secret come chiave. Se lo invii, deve essere corretto.