Отправка продаж и своих данных в LinkHarbor

LinkHarbor принимает и данные извне. Для двух случаев есть отдельные эндпоинты со своими секретами — API-ключ для них не нужен: колбэки о продажах сообщают о продажах в вашем магазине, чтобы в статистике было видно, какая ссылка принесла выручку. Интеграция «Custom (API)» выводит живые данные из ваших собственных инструментов на страницу в виде виджета и может запускать push-уведомления.

#Колбэки о продажах: сопоставление продаж

Как связаны ID клика (lt_click_id), сопоставление и отчёты, объясняется в статье Учёт конверсий и продаж; здесь собраны все поля и ответы для разработчиков. Вкратце: когда LinkHarbor перенаправляет учтённый клик на цель с http или https, он добавляет параметр lt_click_id; ваш магазин запоминает его и отправляет обратно после покупки.

Создание секрета колбэка

1. Откройте «Callback и API»
2. В карточке «Секреты колбэков» нажмите «+ Создать секрет»
3. При желании задайте название, например «Колбэк магазина», и нажмите «Создать секрет»
4. Сразу скопируйте секрет — он показывается только один раз

Кто

Владельцы и админы, начиная с Creator Pro. В Creator Free написано «Секреты колбэков доступны начиная с Creator Pro.»

Сколько

До 5 секретов на рабочее пространство, например по одному на магазин.

«Изменить»

Измените название и установите статус «Активен» или «Неактивен». С неактивным секретом API отклоняет колбэки.

«↺ Перевыпустить»

Создаёт новый секрет; старый сразу перестаёт действовать.

«Последний колбэк:»

Показывает, когда секрет последний раз успешно использовался.

Отправка колбэка

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}

Необязательная подпись

Помимо секрета можно отправлять заголовок X-Callback-Signature. Он содержит sha256= и подпись HMAC-SHA256 исходного тела в hex. Ключ — не сам секрет, а его хеш SHA-256 в двоичном виде. Если вы отправляете заголовок, он должен быть правильным — иначе колбэк отклоняется.

<?php
$body = json_encode($payload);
$key  = hash('sha256', getenv('LH_CALLBACK_SECRET'), true); // двоичный хеш секрета
$sig  = 'sha256=' . hash_hmac('sha256', $body, $key);
// Заголовки: X-Callback-Secret и X-Callback-Signature: $sig, тело: $body

Где видны продажи

Переданные продажи отображаются в статистике как конверсии, см. Учёт конверсий и продаж. Через API их можно прочитать с read:stats в /v1/stats/…/conversions/breakdown.

#Custom (API): ваши собственные живые данные

С интеграцией «Custom (API)» любая программа, умеющая отправлять HTTP-запросы, — плагин игрового сервера, бот, cron-скрипт — может передавать данные в LinkHarbor. Из них получается живой виджет на вашей странице, а правила push могут уведомлять ваших подписчиков.

Подключение

1. Откройте в рабочем пространстве «Интеграции»
2. Выберите «Custom (API)» и введите название
3. После подключения в диалоге видны «Ingest-URL» и «Секрет» (с кнопкой «Показать секрет»)
4. Сохраните оба значения в своём инструменте

Интеграции доступны начиная с Creator Pro. Ingest-URL и секрет видят только владельцы и админы, в том числе позже в подробном представлении интеграции. При отключении и повторном подключении создаётся новый секрет. Как подключать интеграции в целом, объясняется в статье Подключение интеграции.

Отправка данных

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

Произвольное название события, например player.joined. Оно приводится к нижнему регистру, и именно на него реагируют правила push. Без event событие называется state.updated.

event_id

Необязательный ключ, который защищает от двойной обработки. Если тот же event_id приходит снова, LinkHarbor отвечает duplicate: true и ничего не делает.

data

Значения для плейсхолдеров в текстах push, например {player}. До 40 ключей, только простые значения.

state

Полное состояние виджета. Оно целиком заменяет предыдущее. type — game_server (карточка игрового сервера) или status (карточка статуса).

Вместо Authorization: Bearer секрет можно также передавать в заголовке X-LinkHarbor-Secret. С одного IP-адреса допускается 120 вызовов в минуту. При желании подписывайте тело: заголовок X-LinkHarbor-Signature содержит sha256= и подпись HMAC-SHA256 исходного тела с секретом в качестве ключа. Если вы его отправляете, он должен быть правильным.