Envoyer ventes et données à LinkHarbor

LinkHarbor accepte aussi des données venant de l’extérieur. Pour deux cas, il existe des endpoints dédiés avec leurs propres secrets – vous n’avez pas besoin de clé API pour eux : les callbacks de vente signalent les ventes de votre boutique, pour que vous voyiez dans vos statistiques quel lien a généré du chiffre d’affaires. L’intégration « Custom (API) » amène sur votre page, sous forme de widget, des données en direct de vos propres outils et peut déclencher des notifications push.

#Callbacks de vente : rattacher les ventes

Comment l’ID de clic (lt_click_id), le rattachement et le signalement s’articulent est expliqué dans Attribuer conversions et ventes ; vous trouvez ici tous les champs et réponses pour les développeurs. En bref : lorsque LinkHarbor redirige un clic compté vers une cible http ou https, il ajoute le paramètre lt_click_id ; votre boutique le mémorise et le renvoie après l’achat.

Créer un secret de callback

1. Ouvrez « Callback et API »
2. Dans la carte « Secrets Callback », cliquez sur « + Créer un nouveau secret »
3. Donnez-lui éventuellement un nom, par exemple « Callback boutique », et cliquez sur « Créer le secret »
4. Copiez immédiatement le secret – il n’est affiché qu’une seule fois

Qui

Les propriétaires et les admins, à partir de Creator Pro. Avec Creator Free, il est indiqué « Les secrets de callback sont disponibles à partir de Creator Pro. »

Combien

Jusqu’à 5 secrets par espace de travail, par exemple un par boutique.

« Modifier »

Modifiez le nom et réglez le statut sur « Actif » ou « Inactif ». Avec un secret inactif, l’API refuse les callbacks.

« ↺ Régénérer »

Génère un nouveau secret ; l’ancien cesse immédiatement de fonctionner.

« Dernier callback : »

Indique quand le secret a été utilisé avec succès pour la dernière fois.

Envoyer 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}

Signature facultative

En plus du secret, vous pouvez envoyer l’en-tête X-Callback-Signature. Il contient sha256= et la signature HMAC-SHA256 du corps brut en hexadécimal. La clé n’est pas le secret lui-même mais son hash SHA-256 sous forme binaire. Si vous envoyez l’en-tête, il doit être correct – sinon le callback est refusé.

<?php
$body = json_encode($payload);
$key  = hash('sha256', getenv('LH_CALLBACK_SECRET'), true); // hash binaire du secret
$sig  = 'sha256=' . hash_hmac('sha256', $body, $key);
// En-têtes : X-Callback-Secret et X-Callback-Signature: $sig, corps : $body

Où voir les ventes

Les ventes signalées apparaissent comme conversions dans vos statistiques, voir Attribuer conversions et ventes. Via l’API, vous les lisez avec read:stats sous /v1/stats/…/conversions/breakdown.

#Custom (API) : vos propres données en direct

Avec l’intégration « Custom (API) », tout programme capable d’envoyer des requêtes HTTP – un plugin de serveur de jeu, un bot, un script cron – peut envoyer des données à LinkHarbor. Elles deviennent un widget en direct sur votre page, et des règles push peuvent prévenir vos abonnés.

Connecter

1. Ouvrez « Intégrations » dans l’espace de travail
2. Choisissez « Custom (API) » et saisissez un nom
3. Une fois connecté, la boîte de dialogue affiche l’« URL d’ingestion » et le « Secret » (avec « Afficher le secret »)
4. Enregistrez les deux dans votre outil

Les intégrations sont disponibles à partir de Creator Pro. Seuls les propriétaires et les admins voient l’URL d’ingestion et le secret, y compris plus tard dans la vue détaillée de l’intégration. Déconnecter puis reconnecter crée un nouveau secret. Le fonctionnement général des intégrations est expliqué dans Connecter une intégration.

Envoyer des données

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

Nom d’événement libre, par exemple player.joined. Il est converti en minuscules et c’est à ce nom que réagissent les règles push. Sans event, l’événement s’appelle state.updated.

event_id

Clé facultative qui empêche le double traitement. Si le même event_id est renvoyé, LinkHarbor répond avec duplicate: true et ne fait rien.

data

Valeurs pour les espaces réservés des textes push, par exemple {player}. Jusqu’à 40 clés, valeurs simples uniquement.

state

L’état complet du widget. Il remplace entièrement le précédent. type vaut game_server (carte de serveur de jeu) ou status (carte de statut).

Au lieu d’Authorization: Bearer, vous pouvez aussi envoyer le secret dans l’en-tête X-LinkHarbor-Secret. 120 appels par minute sont autorisés par adresse IP. Vous pouvez aussi signer le corps : l’en-tête X-LinkHarbor-Signature contient sha256= et la signature HMAC-SHA256 du corps brut avec le secret comme clé. Si vous l’envoyez, elle doit être correcte.