التوثيق

مرجع API

هذه هي واجهة REST العامة لطبقة الحقيقة في Gurulu أثناء النسخة التجريبية المغلقة. أما نقاط النهاية الخاصة بالإدارة والعمليات الداخلية ومراقبة المنصة فليست مُدرجة هنا — فهي محصورة ببيانات اعتماد المشغّل وليست جزءًا من عقد العميل.

عنوانان أساسيان:

  • مستوى البيانات — https://ingest.gurulu.io. كل ما يقبل الأحداث.
  • مستوى التحكم — https://api.gurulu.io. كل ما عدا ذلك.

المصادقة

نوعان من بيانات الاعتماد:

  • Bearer JWT. يُصدر لمستخدم مسجّل الدخول عبر رابط سحري (الأساسي) أو OAuth (Google أو GitHub، بـ PKCE S256). يُستخدم لنداءات مستوى التحكم التي يقوم بها إنسان.
  • مفتاح API. بنكهتين. pk_live_* مفتاح عام — آمن لشحنه في كود المتصفح، ويستخدمه SDK المتصفح. وsk_live_* مفتاح سري — لا يُشحن إلى المتصفح أبدًا، ويستخدمه SDK الخادم والمستدعون المباشرون لـ REST.

جميع الاستجابات بصيغة JSON بترميز UTF-8. وتتبع الأخطاء معيار RFC 7807 application/problem+json.

نقاط نهاية المصادقة

POST   /v1/auth/magic-link             اطلب بريد رابط سحري
POST   /v1/auth/magic-link/verify      بدّل رمز الرابط السحري بجلسة
GET    /v1/auth/oauth/:provider        ابدأ OAuth (Google أو GitHub)
POST   /v1/auth/session/refresh        جدّد رمز الوصول
POST   /v1/auth/session/revoke         ألغِ جلسة
POST   /v1/auth/api-keys               أنشئ مفتاح API جديدًا

الاستيعاب — إرسال الأحداث

مستوى البيانات العام. بوابة التحقق تعمل هنا.

POST   /v1/track                       أرسل حدثًا واحدًا
POST   /v1/batch                       أرسل حتى N حدثًا في نداء واحد
POST   /v1/identify                    اربط anonymous_id بـ person_id
POST   /v1/alias                       ادمج هويتين
POST   /v1/webhook/:provider           استقبل webhook من مورّد

يجب أن يجتاز كل حدث في الجسم بوابة التحقق. النتائج الممكنة لكل حدث:

  • accept — مسجّل، سليم البنية، معروف. يمر.
  • warn — مقبول مع مشكلة غير قاتلة (نوع خاصية غير متوقع، مفتاح مهجور).
  • quarantine — محتجز للمراجعة. لا يصل إلى الوجهات اللاحقة.
  • reject — مرفوض. يُعاد في الاستجابة مع السبب.

السجل — العقد

السجل هو مصدر الحقيقة لأسماء الأحداث وأشكالها. ويجب أن تطابق مفاتيح الأحداث النمط ^[a-z0-9_]+$.

GET    /v1/registry/events             اعرض عقود الأحداث
POST   /v1/registry/events             أنشئ عقد حدث جديدًا
GET    /v1/registry/events/:key        اقرأ عقدًا واحدًا
POST   /v1/registry/validate           تحقّق من حمولة مقابل السجل
GET    /v1/registry/code-gen           احصل على توليد كود مُنمّط لبيئة ما
GET    /v1/registry/packs              اعرض حزم البداية القطاعية

يُعيد توليد الكود ارتباطات مُنمّطة لـ TypeScript وPython وSwift. ويغلّف سطر الأوامر (gurulu pull) هذه النقاط ويكتب النتيجة في مستودعك.

الهوية — العمود الفقري

حلّ من سبع خطوات، ثلاثة مستويات ثقة، ودفتر دمج للإضافة فقط. كل دمج قابل للتراجع.

POST   /v1/identity/resolve            حلّ مجموعة معرّفات إلى person_id
GET    /v1/identity/person/:id         اقرأ سجل شخص
GET    /v1/identity/person/:id/timeline   احصل على الخط الزمني لأحداث شخص
POST   /v1/identity/merge              ادمج سجلّين صراحةً
GET    /v1/identity/merge-ledger       اقرأ سجل الدمج للإضافة فقط

الصحة — إشارة الجودة

صحة الأحداث: كشف الشذوذ، إزالة التكرار، التغطية، عدم تطابق CAPI.

GET    /v1/health/events               ملخص الصحة عبر مساحة العمل
GET    /v1/health/events/:key          صحة كل حدث
GET    /v1/health/anomalies            الشذوذ المكتشف (الحجم، المخطط، الكمون)
GET    /v1/health/coverage             درجة التغطية لكل سطح
POST   /v1/health/dedup-check          اسأل إن كان سجلّان يبدوان مكرّرين

الإسناد — الرصيد والمنشأ

سياسة يحدّدها العميل، متعدّدة النماذج (أول، آخر، خطّي، تناقص زمني، موضع، مدفوع بالبيانات)، مع أثر منشأ كامل لكل نتيجة.

POST   /v1/attribution/policy                       حدّد / حدّث سياسة الإسناد
POST   /v1/attribution/compute                      أعد حساب الإسناد لمدى زمني
GET    /v1/attribution/touchpoints/:personId        نقاط التماس المعتبرة لشخص
GET    /v1/attribution/explain/:outcomeId           أثر تفسيري لنتيجة بعينها

تُعيد نقطة explain: أي نقاط تماس أُخذت في الحسبان، وأيها استُبعدت، وأي نموذج طُبِّق، وماذا كانت النماذج البديلة ستُسند.

الموافقة — GDPR وKVKK وCCPA

فئات GCM v2. تصدير ونسيان بيانات صاحب البيانات على طابور باتفاقية مستوى خدمة قدرها 60 ثانية.

POST   /v1/consent                     سجّل حالة الموافقة لشخص
GET    /v1/consent/:personId           اقرأ الموافقة الحالية
POST   /v1/consent/dsr/export          ضع طلب تصدير بيانات في الطابور
POST   /v1/consent/dsr/forget          ضع طلب نسيان في الطابور

حِزم التطوير

استخدام REST مباشرة مقبول. لكن معظم الفرق تستخدم حِزم التطوير:

  • @gurulu/web — حزمة متصفح بلا اعتماديات (8.1 كيلوبايت مضغوطة). خمس إشارات التقاط تلقائي، وidentify، وtrack، والموافقة، وتفعيل إعادة التشغيل.
  • @gurulu/node — SDK خادم لـ Node 20+ وBun والحافة. مُتحقِّقو webhook لثلاثة وعشرين مورّدًا. وسائط برمجية لـ Hono وExpress وFastify.
  • @gurulu/cli — gurulu init / pull / push / validate / doctor. يربط السجل بسير عمل Git لديك.
  • @gurulu/mcp-server — MCP لـ Cursor وClaude Code وLovable. الأدوات: list_events وadd_event وvalidate_event. يتوقف محررك الذكي عن تخمين أسماء الأحداث.

الأخطاء

جميع الأخطاء بصيغة application/problem+json وتحمل:

  • type — معرّف URL ثابت لصنف الخطأ.
  • title — وصف بشري قصير.
  • status — رمز حالة HTTP.
  • detail — ما الذي أخطأ في هذا الطلب تحديدًا.
  • instance — معرّف طلب مبهم يمكنك ذكره عند الإبلاغ عن خلل.

رفض بوابة التحقق هو type: "https://gurulu.io/errors/contract-violation". ويسرد جسم الاستجابة الحقول التي أخفقت وسبب ذلك.

الحالة

تبلغ واجهة نقاط النهاية الكاملة نحو 270 مسارًا اليوم؛ وتسرد هذه الصفحة المجموعة الفرعية العامة الموجّهة للعملاء. أما نقاط المشغّل والمنصة فليست جزءًا من عقد العميل وقد تتغير دون إشعار. والقائمة أعلاه ثابتة للنسخة التجريبية المغلقة.

للنموذج المفاهيمي وراء هذه النقاط، انظر كيف يعمل.

العودة إلى التوثيق