إرسال المبيعات والبيانات المخصصة

يقبل LinkHarbor أيضًا بيانات من الخارج. ولحالتين توجد نقاط نهاية مخصّصة بأسرار خاصة بها، فلا تحتاج إلى مفتاح API لهما: تبلّغ Callbacks البيع عن المبيعات من متجرك، فترى في إحصائياتك أي رابط جلب إيرادات. ويجلب تكامل Custom (API) بيانات حيّة من أدواتك الخاصة إلى صفحتك كودجة، ويمكنه إطلاق إشعارات فورية.

#Callbacks البيع: ربط المبيعات

كيف يتكامل معرّف النقرة (lt_click_id) والربط والتقارير مشروح في نسب التحويلات والمبيعات؛ وهنا تجد كل الحقول والاستجابات للمطوّرين. باختصار: عندما يعيد LinkHarbor توجيه نقرة محسوبة إلى هدف http أو https، يضيف المعامل lt_click_id؛ فيحتفظ به متجرك ويرسله مرة أخرى بعد الشراء.

إنشاء سر Callback

1. افتح «Callback وواجهة API»
2. في بطاقة «أسرار Callback» انقر «+ إنشاء سر جديد»
3. أعطه اسمًا اختياريًا، مثل Callback المتجر، وانقر «إنشاء السر»
4. انسخ السر فورًا، فهو يُعرض مرة واحدة فقط

من

المالكون والمسؤولون، ابتداءً من Creator Pro. وفي Creator Free تظهر العبارة «أسرار Callback متاحة ابتداءً من Creator Pro.»

كم

حتى 5 أسرار لكل مساحة عمل، مثلًا سر لكل متجر.

«تعديل»

غيّر الاسم واضبط الحالة على «نشط» أو «غير نشط». ومع السر غير النشط ترفض الـ API عمليات Callback.

«↺ تدوير»

يُنشئ سرًا جديدًا؛ ويتوقف القديم عن العمل فورًا.

«آخر Callback:»

يعرض متى استُخدم السر آخر مرة بنجاح.

إرسال 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}

توقيع اختياري

إضافة إلى السر، يمكنك إرسال الترويسة X-Callback-Signature. وهي تحتوي على sha256= وتوقيع HMAC-SHA256 للجسم الخام بالنظام الست عشري. والمفتاح ليس السر نفسه، بل تجزئة SHA-256 له بالصيغة الثنائية. وإذا أرسلت الترويسة، فيجب أن تكون صحيحة، وإلا رُفض الـ Callback.

<?php
$body = json_encode($payload);
$key  = hash('sha256', getenv('LH_CALLBACK_SECRET'), true); // binary hash of the secret
$sig  = 'sha256=' . hash_hmac('sha256', $body, $key);
// Headers: X-Callback-Secret and X-Callback-Signature: $sig, body: $body

أين ترى المبيعات

تظهر المبيعات المبلَّغ عنها كتحويلات في إحصائياتك، انظر نسب التحويلات والمبيعات. وعبر الـ API تقرؤها بالنطاق read:stats تحت /v1/stats/…/conversions/breakdown.

#Custom (API): بياناتك الحيّة الخاصة

مع تكامل Custom (API) يستطيع أي برنامج قادر على إرسال طلبات HTTP، كإضافة لخادم ألعاب أو بوت أو سكربت cron، أن يرسل بيانات إلى LinkHarbor. وتتحول هذه البيانات إلى ودجة حيّة على صفحتك، ويمكن لقواعد الإشعارات الفورية إخطار متابعيك.

الربط

1. افتح «التكاملات» في مساحة العمل
2. اختر Custom (API) وأدخل اسمًا
3. بعد الربط تعرض النافذة «رابط الاستقبال» و«السر» (مع «إظهار السر»)
4. احفظ الاثنين في أداتك

التكاملات متاحة ابتداءً من Creator Pro. ولا يرى رابط الاستقبال والسر إلا المالكون والمسؤولون، بما في ذلك لاحقًا في عرض تفاصيل التكامل. والفصل ثم إعادة الربط يُنشئ سرًا جديدًا. وكيفية ربط التكاملات عمومًا مشروحة في ربط التكاملات وتجديدها وفصلها.

إرسال البيانات

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. يُحوَّل إلى أحرف صغيرة، وهو الاسم الذي تتفاعل معه قواعد الإشعارات الفورية. ودون event يُسمّى الحدث state.updated.

event_id

مفتاح اختياري يمنع المعالجة المزدوجة. إذا أُرسل event_id نفسه مرة أخرى، يستجيب LinkHarbor بـ duplicate: true ولا يفعل شيئًا.

data

قيم للعناصر النائبة في نصوص الإشعارات الفورية، مثل {player}. حتى 40 مفتاحًا، وبقيم بسيطة فقط.

state

الحالة الكاملة للودجة. وهي تستبدل الحالة السابقة بالكامل. وقيمة type هي game_server (بطاقة خادم ألعاب) أو status (بطاقة حالة).

بدلًا من Authorization: Bearer يمكنك أيضًا إرسال السر في الترويسة X-LinkHarbor-Secret. ويُسمح بـ 120 استدعاءً في الدقيقة لكل عنوان IP. واختياريًا توقّع الجسم: تحتوي الترويسة X-LinkHarbor-Signature على sha256= وتوقيع HMAC-SHA256 للجسم الخام مع السر مفتاحًا. وإذا أرسلتها، فيجب أن تكون صحيحة.