Gửi doanh số và dữ liệu tùy chỉnh đến LinkHarbor

LinkHarbor cũng nhận dữ liệu từ bên ngoài. Với hai trường hợp có các endpoint riêng với secret riêng – bạn không cần khóa API cho chúng: sale callback báo doanh số từ cửa hàng, để bạn thấy trong thống kê liên kết nào mang lại doanh thu. Tích hợp “Custom (API)” đưa dữ liệu trực tiếp từ công cụ của bạn lên trang dưới dạng widget và có thể kích hoạt thông báo đẩy.

#Sale callback: gán doanh số

Click ID (lt_click_id), việc gán và báo cáo phối hợp với nhau thế nào được giải thích trong Gán chuyển đổi và doanh số; ở đây bạn tìm thấy mọi trường và phản hồi dành cho nhà phát triển. Tóm lại: khi LinkHarbor chuyển hướng một lượt nhấp được đếm đến đích http hoặc https, nó gắn tham số lt_click_id; cửa hàng của bạn ghi nhớ và gửi lại sau khi mua.

Tạo mã bí mật callback

1. Mở “Callback & API”
2. Trong thẻ “Mã bí mật callback”, nhấp “+ Tạo mã bí mật mới”
3. Nếu muốn, đặt tên, ví dụ “Callback cửa hàng”, rồi nhấp “Tạo mã bí mật”
4. Sao chép mã bí mật ngay – nó chỉ hiển thị một lần

Ai

Chủ sở hữu và quản trị viên, từ gói Creator Pro. Ở Creator Free ghi “Mã bí mật callback có từ gói Creator Pro.”

Bao nhiêu

Tối đa 5 mã bí mật cho mỗi không gian làm việc, ví dụ mỗi cửa hàng một mã.

“Chỉnh sửa”

Đổi tên và đặt trạng thái thành “Hoạt động” hoặc “Không hoạt động”. Với mã bí mật không hoạt động, API từ chối callback.

“↺ Xoay vòng”

Tạo mã bí mật mới; mã cũ ngừng hoạt động ngay lập tức.

“Callback gần nhất:”

Cho biết lần cuối mã bí mật được dùng thành công.

Gửi 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}

Chữ ký tùy chọn

Ngoài mã bí mật, bạn có thể gửi header X-Callback-Signature. Header chứa sha256= và chữ ký HMAC-SHA256 của phần thân thô dạng hex. Khóa không phải chính mã bí mật mà là hash SHA-256 của nó ở dạng nhị phân. Nếu bạn gửi header, nó phải đúng – nếu không callback bị từ chối.

<?php
$body = json_encode($payload);
$key  = hash('sha256', getenv('LH_CALLBACK_SECRET'), true); // hash nhị phân của secret
$sig  = 'sha256=' . hash_hmac('sha256', $body, $key);
// Header: X-Callback-Secret và X-Callback-Signature: $sig, phần thân: $body

Xem doanh số ở đâu

Doanh số được báo về xuất hiện dưới dạng chuyển đổi trong thống kê, xem Gán chuyển đổi và doanh số. Qua API, bạn đọc chúng bằng read:stats dưới /v1/stats/…/conversions/breakdown.

#Custom (API): dữ liệu trực tiếp của riêng bạn

Với tích hợp “Custom (API)”, mọi chương trình gửi được yêu cầu HTTP – plugin máy chủ game, bot, script cron – đều có thể gửi dữ liệu đến LinkHarbor. Dữ liệu trở thành widget trực tiếp trên trang của bạn, và quy tắc thông báo đẩy có thể báo cho người theo dõi.

Kết nối

1. Mở “Tích hợp” trong không gian làm việc
2. Chọn “Custom (API)” và nhập tên
3. Sau khi kết nối, hộp thoại hiển thị “URL ingest” và “Secret” (với “Hiện secret”)
4. Lưu cả hai trong công cụ của bạn

Tích hợp có từ gói Creator Pro. Chỉ chủ sở hữu và quản trị viên mới thấy URL ingest và secret, kể cả sau này trong trang chi tiết của tích hợp. Ngắt kết nối rồi kết nối lại sẽ tạo secret mới. Cách kết nối tích hợp nói chung được giải thích trong Kết nối tích hợp.

Gửi dữ liệu

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

Tên sự kiện tự do, ví dụ player.joined. Tên được chuyển thành chữ thường và là tên mà quy tắc thông báo đẩy phản ứng theo. Không có event, sự kiện được gọi là state.updated.

event_id

Khóa tùy chọn ngăn xử lý hai lần. Nếu cùng event_id được gửi lại, LinkHarbor phản hồi duplicate: true và không làm gì.

data

Giá trị cho các phần giữ chỗ trong văn bản thông báo đẩy, ví dụ {player}. Tối đa 40 khóa, chỉ giá trị đơn giản.

state

Trạng thái đầy đủ của widget. Nó thay thế hoàn toàn trạng thái trước. type là game_server (thẻ máy chủ game) hoặc status (thẻ trạng thái).

Thay vì Authorization: Bearer, bạn cũng có thể gửi secret trong header X-LinkHarbor-Secret. Cho phép 120 lệnh gọi mỗi phút cho mỗi địa chỉ IP. Nếu muốn, bạn ký phần thân: header X-LinkHarbor-Signature chứa sha256= và chữ ký HMAC-SHA256 của phần thân thô với secret làm khóa. Nếu bạn gửi nó, nó phải đúng.