واجهة HTTP

أي شيء يستطيع إرسال طلب HTTPS يستطيع إرسال الأحداث. استخدم هذه الواجهة للطلبات التي تُؤكَّد بعد أن يغادر المشتري، وللاسترجاعات الصادرة من لوحة الإدارة، ولأي نظام لا متصفح فيه.

العنوان الأساسي: https://edge.flofy.co

المسارات

كلها POST مع Content-Type: application/json. والصيغ المختصرة تتصرّف تمامًا كالطويلة.

المصادقة

مفتاح الكتابة يوضع في ترويسة HTTP Basic، بوصفه اسم المستخدم مع كلمة مرور فارغة. رمّز المفتاح متبوعًا بنقطتين بترميز Base64:

printf 'YOUR_WRITE_KEY:' | base64

Authorization: Basic <that value>

النقطتان في آخره مطلوبتان، وكلمة المرور غير الفارغة تُرفض.

ويمكنك تمرير المفتاح كمعامل استعلام بدلًا من ذلك — ?writeKey=<base64 of the key> — وهذا ما تفعله مكتبة المتصفح، لتبقى الطلبات خالية من طلب CORS التمهيدي. وحين يوجد الاثنان معًا، يفوز معامل الاستعلام.

نموذج طلب

curl -X POST https://edge.flofy.co/v1/track \
  -H "Authorization: Basic $(printf 'YOUR_WRITE_KEY:' | base64)" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "track",
    "event": "Order Completed",
    "userId": "customer_9931",
    "messageId": "8f14e45f-ea0a-4c1f-9f2c-3b7d1a0e5c62",
    "timestamp": "2026-08-25T10:31:00.000Z",
    "properties": {
      "order_id": "ORD-12345",
      "currency": "SAR",
      "value": 523.17,
      "products": [
        { "product_id": "P-4471", "name": "Wireless Headphones", "price": 199.99, "quantity": 1 }
      ]
    }
  }'

الغلاف

messageId هو ما يجعل إعادة المحاولة تُعرَف بوصفها الحدث نفسه لا حدثًا ثانيًا. أنشئه مرة واحدة لكل حدث، وأعد استخدامه إن أعدت المحاولة.

حقول الغلاف بصيغة camelCase — userId وmessageId. وكل ما داخل properties وtraits بصيغة snake_case — order_id وfirst_name. الفصل مقصود: الغلاف يصف الرسالة، والخصائص تصف متجرك.

السياق

المكتبة تملأ هذا الحقل من المتصفح. أما عبر HTTP فترسل ما لديك، وكله اختياري:

{
  "context": {
    "ip": "203.0.113.9",
    "userAgent": "Mozilla/5.0 …",
    "locale": "ar-SA",
    "timezone": "Asia/Riyadh",
    "page": {
      "url": "https://store.example.com/checkout",
      "path": "/checkout",
      "referrer": "https://www.google.com/"
    },
    "campaign": {
      "source": "facebook",
      "medium": "cpc",
      "name": "ramadan-2026"
    }
  }
}

ip وuserAgent هما الحقلان اللذان يستحقان العناء. ميتا وتيك توك وسناب شات تستخدمهما لمطابقة تحويل من جهة الخادم بمشاهدة إعلان، وبدونهما يبقى جزء من طلباتك بلا إسناد. أرسل عنوان المشتري، لا عنوان خادمك.

الدفعات

{
  "batch": [
    {
      "type": "identify",
      "userId": "customer_9931",
      "messageId": "…",
      "timestamp": "…",
      "traits": { "email": "sara@example.com" }
    },
    {
      "type": "track",
      "event": "Order Completed",
      "userId": "customer_9931",
      "messageId": "…",
      "timestamp": "…",
      "properties": { "order_id": "ORD-12345", "currency": "SAR", "value": 523.17 }
    }
  ]
}

كل عنصر حدث كامل، له type وmessageId وtimestamp خاصة به. وتُتحقَّق العناصر كلها قبل قبول أي منها، فعنصر واحد معطوب يرفض الطلب كله — وهذا ما يجعل إعادة إرسال الطلب كوحدة واحدة آمنة.

الحدود

الردود

لا جسم للرد عند النجاح. الرمز 204 يعني أن الطلب سليم البنية، لا أن مفتاح الكتابة يطابق مصدرًا: مفتاح يبدو صالحًا لمصدر غير موجود يُقبل هنا ثم يُسقَط لاحقًا. تأكّد من الأحداث المباشرة في صفحة المصدر داخل فلوفاي.

إذا واجهت مشكلة

اعمل على هذه القائمة بالترتيب:

1. هل الترويسة صحيحة؟ Basic، ثم مسافة، ثم ترميز base64 لـkey: — بالنقطتين.
2. هل type يطابق المسار؟ جسم track يُرسَل إلى /v1/identify لن يفعل ما قصدته.
3. هل الهوية داخل الجسم؟ لا بد أن يكون userId أو anonymousId داخل الـJSON. والترويسة لا تُغني عنه.
4. هل timestamp بصيغة ISO 8601 وبتوقيت UTC؟ 2026-08-25T10:31:00.000Z، لا طابع زمني بصيغة Unix.
5. هل الخصائص بصيغة snake_case؟ order_id لا orderId. الصيغة الخاطئة تُقبل ثم تُهمَل، فيبدو الأمر مشكلة تسليم وهو ليس كذلك.
6. هل اسم الحدث يطابق المرجع؟ راجع مرجع الأحداث.