توثيق المطورين

ابنِ على واجهات O My Syria المتاحة اليوم

استخدم عقد REST المنفّذ وWidget الويب المقيّد بأمان. يوضّح هذا التوثيق ما هو متاح الآن وما يزال مخططًا له.

POST /v1/answers

بداية سريعة

تحقق من API المحلي بطلب واحد

طلب فحص النظام العام هو أصغر طلب آمن للتأكد من جاهزية البوابة المحلية واعتمادياتها المطلوبة.

1شغّل API المحلي واعتمادياته المطلوبة.
2أرسل الطلب من الطرفية.
3توقّع استجابة 200 داخل غلاف data القياسي.

طلب جاهزية عامPOST /v1/answers

curl --request POST "https://omysyria.com/v1/answers" \
  --header "Content-Type: application/json" \
  --header "X-AHS-API-Key: $AHS_SERVER_KEY" \
  --data '{
    "message_id": "msg-001",
    "question": "كيف أسحب رصيدي من المحفظة؟",
    "language": "ar"
  }'

حدود المصادقة

اختر بيانات الاعتماد حسب الـ endpoint

يصرّح كل إجراء في المرجع بمخطط الأمان الفعلي الخاص به. تبقى بيانات الاعتماد محصورة في غرض واحد ولا يجوز استبدال إحداها بالأخرى.

منفّذ

مفتاح API سري للخادم

تستدعي خوادم Backend الموثوقة POST /v1/answers عبر X-AHS-API-Key من دون Origin متصفح. يمكن تقييد المصدر بقائمة IP دقيقة واختيارية. لا تضع هذا السر في كود المتصفح أو الموبايل.

منفّذ

جلسة الإدارة

تستخدم لوحة التحكم ومسارات الإدارة cookie آمنة باسم ahs_session. وتتطلب طلبات المتصفح المغيّرة للحالة ترويسة X-CSRF-Token المقترنة بها. هذه المسارات ليست API بمفتاح خادم.

منفّذ

مفتاح Widget قابل للنشر

تقبل مسارات Widget ترويسة X-AHS-Publishable-Key من origin متصفح مسموح فقط. وتستخدم عمليات المحادثة أيضًا X-AHS-Conversation-Token قصير العمر. المفتاح القابل للنشر مقيّد وظاهر للمتصفح وليس سرًا إداريًا.

الحفظ داخل Backend موثوق فقط

لا ترسل مفتاح الخادم أو مرجع المحادثة إلى المتصفح أو تطبيق الموبايل أو السجلات. تعامل مع conversation_ref كبيانات معتمة، ولا تضع أسئلة العملاء أو إجابات O My Syria في السجلات التشغيلية.

Base URLsHTTPS Encrypted

عناوين الخادم الأساسية (Base URLs)

استخدم عنوان البيئة المناسب عند إرسال طلبات الـ HTTP من خادمك الموثوق.

البيئة الإنتاجية (Production)Production

https://omysyria.com

استخدم مفتاح ahs_sk_live_... المخصص لبيئة الإنتاج.

البيئة التجريبية / المحلية (Test / Local)Test / Dev

http://localhost:8080

للتطوير المحلي والتجربة باستخدام مفاتيح ahs_sk_test_....

REST EndpointsJSON over HTTP

نقاط النهاية المتاحة لربط الرسائل

هذه هي نقاط النهاية المستخدمة لربط المنصات وتطبيقات الموبايل (مثل TakeCar) لإرسال الأسئلة واستقبال إجابات الذكاء الاصطناعي.

POST /v1/answersأساسي

إرسال رسالة واستقبال الإجابة

إرسال سؤال العميل واستلام إجابة الذكاء الاصطناعي المؤصلة مع دعم استمرار سياق المحادثة وتحديد التكرار.

DELETE /v1/server-conversationsإدارة

إنهاء وحذف المحادثة

حذف محتوى المحادثة المحفوظ بواسطة مرجع المحادثة عند إغلاق الجلسة أو طلب العميل.

أمثلة الشيفرات البرمجية ومكتبات التكامل

اختر السيناريو واللغة لنسخ كود الربط الفوري أو كلاس العميل الجاهز (Client Helper).

curl --request POST "https://omysyria.com/v1/answers" \
  --header "Content-Type: application/json" \
  --header "X-AHS-API-Key: ahs_sk_live_••••••••••••" \
  --data '{
    "message_id": "takecar-msg-101",
    "question": "كيف أسحب رصيدي من المحفظة؟",
    "language": "ar"
  }'

شكل الاستجابة (Response Envelope 200 OK)200 OK

{
  "data": {
    "status": "grounded",
    "answer": "يمكنك سحب الرصيد المتاح من خلال فتح صفحة المحفظة في تطبيق TakeCar، ثم اختيار طلب سحب وإدخال البيانات البنكية المطلوبة.",
    "conversation_ref": "ahs_conv_live_9f83a27e01b44298a0c6d9124e8371b29a8f",
    "message_id": "takecar-msg-101",
    "handoff_suggested": false,
    "citations": [
      {
        "citation_id": "cite_01",
        "source_filename": "takecar-driver-operations.md"
      }
    ]
  }
}

دورة حياة المحادثة وسياق الحوار

كيف يتذكر الذكاء الاصطناعي سياق الأسئلة السابقة عبر المعرف المشفّر conversation_ref.

الرسالة الأولى (Turn 1)

ترسل question مع message_id فريد وبدون conversation_ref. يعيد O My Syria الإجابة مع conversation_ref.

حفظ المرجع بالـ Backend

يحفظ خادمك مرجع conversation_ref بجانب جلسة المستخدم في قاعدة بياناتك الخاصة.

متابعة المحادثة (Turn 2+)

أرسل السؤال التالي مع conversation_ref ومعرّف message_id جديد ليحمّل O My Syria سياق الحوار السابق بدقة.

التحويل للبشر أو الإغلاق

إذا كانت handoff_suggested: true وجّه العميل لموظف دعم، أو احذف المحادثة عند انتهائها عبر DELETE.

المواصفات الفنية للمعاملات وحقول البيانات

جدول تفصيلي للقيود وأنواع الحقول والأنماط المقبولة (Regex / Types / Max Size).

1. ترويسات الطلب (Request Headers)

Header	النوع والحالة	الوصف والقيود
X-AHS-API-Key	إلزامي	مفتاح الخادم السري (Server Secret Key) ويبدأ بـ ahs_sk_live_... أو ahs_sk_test_.... لا ترسله أبداً في متصفح أو كود موبايل.
Content-Type	application/json	نوع محتوى الجسم المُرسل ويجب أن يكون application/json.
X-AHS-Conversation-Ref	إلزامي لـ DELETE فقط	يُرسل في ترويسة طلب DELETE /v1/server-conversations لتحديد المحادثة المراد حذفها.

2. معاملات جسم الطلب (Request Body Parameters - POST /v1/answers)

Field	النوع	الحالة	الوصف والقيود البرمجية
question	string	إلزامي	نص سؤال أو رسالة العميل (الحد الأقصى: 8KB UTF-8 نص). مثال: "كيف أسحب رصيدي من المحفظة؟".
message_id	string	موصى به	معرّف فريد لكل رسالة من نظامك (النمط: ^[A-Za-z0-9][A-Za-z0-9._:-]{0,127}$، الطول: 1-128 حرف). يضمن عدم تكرار الاستدعاء عند إعادة المحاولة ويحفظ تسلسل الحوار.
conversation_ref	string	اختياري	مرجع المحادثة المعتم الناتج من أول إجابة ناجحة (النمط: ^ahs_conv_live_[A-Za-z0-9_-]{43}$). يُرسل لمتابعة الحوار السابق.
language	string	اختياري	لغة المعالجة ("ar" للعربية أو "en" للإنجليزية). القيمة الافتراضية "ar".

3. حقول الاستجابة (Response Fields - data object)

Field	النوع	المعنى والقيم المحتملة
status	string	groundedinsufficient_contextout_of_scopesafety_flagged حالة الإجابة: grounded تعني إجابة مؤصلة بيقين، insufficient_context تعني المعرفة غير كافية، out_of_scope خارج النطاق.
answer	string	نص الإجابة الذكية الموجهة للعميل والمبنية على وثائق وسياسات منصتك.
conversation_ref	string	مرجع المحادثة المعتم. احفظه في خادمك بجانب جلسة العميل لإرساله في الأسئلة القادمة.
message_id	string	معرّف الرسالة المرسل في الطلب للتطابق والتأكيد.
handoff_suggested	boolean	تكون true إذا كان السؤال يتطلب تحويلاً فورياً إلى موظف دعم بشري.
citations	array	قائمة أسماء الملفات والمصادر المعرفية التي استندت إليها الإجابة [{ citation_id, source_filename }].

رموز الأخطاء والاستجابات (Error Codes)

تعتمد جميع الاستجابات غير الناجحة على غلاف الأخطاء الموحد ErrorEnvelope.

401 Unauthorized

invalid_api_key

مفتاح API السري مفقود أو غير صالح أو تم إلغاؤه.

422 Unprocessable

invalid_input

حقول الطلب غير مطابقة للمخطط أو الحجم الأقصى (السؤال فارغ أو يتجاوز 8KB).

422 Unprocessable

invalid_message_id

صيغة message_id غير مطابقة للنمط المقبول.

404 Not Found

conversation_not_found

مرجع المحادثة غير موجود أو منتهي الصلاحية (بعد 30 يوماً أو بعد حذفه).

409 Conflict

request_in_progress

الرسالة قيد المعالجة حالياً. تحقق من ترويسة Retry-After وأعد المحاولة.

409 Conflict

idempotency_conflict

تم استخدام نفس message_id سابقاً مع نص سؤال مختلف.

429 Rate Limited

rate_limited

تجاوز حد الطلبات المسموح (200 طلب/دقيقة للمفتاح، 60 طلب/دقيقة للـ IP).

503 Unavailable

grounded_answer_unavailable

خدمة التوليد أو قاعدة المعرفة غير متاحة مؤقتاً.