بوابة مطوّري سيرياسان

المصادقة

كل طلب يحتاج مفتاح API صالحاً. أرسله في ترويسة Authorization: Bearer أو x-api-key. تُخزَّن المفاتيح مُجزّأة (SHA-256) فقط ولا يمكن استرجاعها بعد إنشائها — احفظ المفتاح لحظة إنشائه.

• أنشئ حساب مطوّر ومفتاحاً من صفحة «واجهة المطورين».
• لا تضع المفتاح في كود المتصفح؛ استدعِ الواجهة من خادمك.
• يمكن إلغاء أي مفتاح فوراً، وكل إنشاء أو إلغاء يُسجَّل في سجل التدقيق.

curl "https://syriasan.com/api/v1/resolve/SY-DAM-K7X4" \
  -H "Authorization: Bearer san_live_…"

# equivalent alternative
curl "https://syriasan.com/api/v1/resolve/SY-DAM-K7X4" -H "x-api-key: san_live_…"

وضع الاختبار (Sandbox)

أنشئ حساب مطوّر من نوع «تجريبي» واستخدم مفاتيحه للتطوير. في وضع الاختبار تعمل عمليات القراءة على بيانات حقيقية عامة، بينما تُحاكى عمليات الكتابة: يُتحقَّق من الحقول ويعود ردّ 201 بالرمز SY-XXX-TEST دون حفظ أي شيء.

• كل ردّ يحمل الترويسة X-Syriasan-Mode بقيمة test أو live.
• ردود المحاكاة تتضمن "mode": "test" و"status": "simulated".
• الرمز التجريبي للتجارب: SY-DAM-K7X4.

curl -X POST https://syriasan.com/api/v1/addresses \
  -H "Authorization: Bearer $SYRIASAN_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name_ar":"فرع تجريبي","governorate":"دمشق","governorate_code":"DAM","city":"دمشق","latitude":33.5138,"longitude":36.2765}'

حلّ العنوان — Resolve

GET /resolve/{code} يعيد المدخل الموصى به حسب الغرض (توصيل طرد، طعام، زيارة، إسعاف، شاحنة…) مع الإحداثيات والتعليمات والقيود. هذه هي النقطة التي تستخدمها تطبيقات التوصيل.

curl "https://syriasan.com/api/v1/resolve/SY-DAM-K7X4?purpose=parcel_delivery&wheelchair=true" \
  -H "Authorization: Bearer $SYRIASAN_KEY"

المدخل المعاد هو نقطة الوصول الفعلية وليس مركز المبنى.

التحقق — Validate

POST /validate يتحقق من صيغة الرمز ووجوده، ومن وقوع الإحداثيات داخل سوريا، ويعيد درجة اكتمال للعنوان — مناسب لحقول الدفع والتسجيل.

curl -X POST https://syriasan.com/api/v1/validate \
  -H "Authorization: Bearer $SYRIASAN_KEY" \
  -H "Content-Type: application/json" \
  -d '{"code":"SY-DAM-K7X4","latitude":33.5138,"longitude":36.2765}'

البحث — Search

GET /search يبحث في العناوين العامة فقط بالاسم أو الشارع، مع تصفية بالمحافظة والمدينة وحدّ أقصى 50 نتيجة.

curl "https://syriasan.com/api/v1/search?q=mazzeh&governorate=دمشق&limit=10" \
  -H "Authorization: Bearer $SYRIASAN_KEY"

إنشاء عنوان — Create Address

POST /addresses ينشئ عنواناً عاماً جديداً ويولّد رمزه الذكي تلقائياً. يتطلب صلاحية addresses:write، وينشئ عناوين عامة فقط — لا يمكن إنشاء عناوين سكنية خاصة عبر الواجهة.

curl -X POST https://syriasan.com/api/v1/addresses \
  -H "Authorization: Bearer $SYRIASAN_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name_ar":"مقهى الياسمين","governorate":"دمشق","governorate_code":"DAM","city":"دمشق","street":"شارع الحمرا","latitude":33.5138,"longitude":36.2765,"entrance_name":"المدخل الرئيسي","entrance_instructions":"يمين البناء بعد الصيدلية","phone":"+963…","category":"cafe"}'

رموز QR

GET /qr/{code} يعيد بيانات الرمز بصيغة JSON، أو صورة SVG جاهزة للطباعة عند تمرير format=svg مع مقاس بين 128 و2048 بكسل.

curl "https://syriasan.com/api/v1/qr/SY-DAM-K7X4?format=svg&size=640" \
  -H "Authorization: Bearer $SYRIASAN_KEY"

يفتح المسح صفحة العنوان العامة /a/CODE، ولا يكشف أبداً بيانات خاصة.

التوجيه — Navigation

GET /route يحسب المسار من نقطة انطلاق حتى المدخل المناسب للعنوان، بالسيارة أو مشياً أو بالدراجة، ويعيد المسافة والزمن وهندسة المسار.

curl "https://syriasan.com/api/v1/route?from=33.5020,36.2900&to=SY-DAM-K7X4&mode=driving" \
  -H "Authorization: Bearer $SYRIASAN_KEY"

الوجهة دائماً المدخل المختار، لا مركز المبنى. عند تعذّر خدمة المسارات يعود مسار تقريبي مع degraded: true.

Webhooks

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

• POST /webhooks — إنشاء اشتراك (url + events).
• GET /webhooks — عرض الاشتراكات وعدّادات التسليم والإخفاق.
• POST /webhooks/test — إرسال تسليم تجريبي.
• POST /webhooks/delete — حذف اشتراك.
• كل تسليم يحمل X-Syriasan-Event وX-Syriasan-Timestamp وX-Syriasan-Signature.

curl -X POST https://syriasan.com/api/v1/webhooks \
  -H "Authorization: Bearer $SYRIASAN_KEY" \
  -H "Content-Type: application/json" \
  -d '{"url":"https://example.com/hooks/syriasan","events":["address.resolved","address.delivery_viewed"]}'

التوقيع يُحسب على النص «الطابع الزمني.الجسم الخام» بخوارزمية HMAC-SHA256. ارفض أي طابع زمني أقدم من خمس دقائق.

طبقة التكامل المحايدة

تعرض /capabilities عقد القدرات وسياقات الوصول، بينما يسجل /events دورة استخدام العنوان بمعرّف رحلة ومفتاح منع تكرار. لا توجد موصلات أو بيانات اعتماد وهمية؛ يضاف كل مزود مستقبلاً كمحوّل مستقل.

• القطاعات: التوصيل، التجارة الإلكترونية، المال، التأمين، المرافق، الصحة، الضيافة، الحكومة، البلديات، الطوارئ واللوجستيات.
• الأحداث: address_used وnavigation_started وdestination_reached.
• كل حدث خارجي يقبل رمزاً عاماً فقط؛ لا تقبل الواجهة وحدة سكنية أو اسماً أو هاتفاً أو ملاحظات خاصة.

curl -X POST https://syriasan.com/api/v1/events \
  -H "Authorization: Bearer $SYRIASAN_KEY" \
  -H "Content-Type: application/json" \
  -d '{"code":"SY-DAM-K7X4","event":"destination_reached","correlation_id":"550e8400-e29b-41d4-a716-446655440000","idempotency_key":"order-784-arrived","routing_context":"parcel"}'

يتطلب /events صلاحية events:write. تكرار المفتاح لن ينشئ حدثاً ثانياً.

الأخطاء

كل خطأ يعود بصيغة JSON موحّدة: {"error":"رمز_الخطأ","message":"شرح"} مع رمز HTTP مناسب.

• 400 invalid_request — حقول ناقصة أو غير صالحة.
• 401 missing_api_key / invalid_api_key / revoked_api_key / expired_api_key.
• 403 insufficient_scope — المفتاح لا يملك الصلاحية المطلوبة.
• 403 private — العنوان سكني خاص ولن يُكشف.
• 403 inactive_client — حساب المطوّر موقوف.
• 404 not_found / unknown_endpoint.
• 422 out_of_bounds / no_coordinates — إحداثيات خارج سوريا أو مدخل بلا إحداثيات.
• 429 rate_limited — تجاوز حدّ المعدل.

حدود المعدل

لكل حساب مطوّر حدّ طلبات بالدقيقة (٦٠ افتراضياً، قابل للرفع). كل ردّ يحمل X-RateLimit-Limit وX-RateLimit-Remaining، وعند التجاوز يعود 429 مع Retry-After: 60.

• راقب الترويسات وطبّق إعادة محاولة تصاعدية عند 429.
• خزّن نتائج الحلّ مؤقتاً لبضع دقائق لتقليل الاستهلاك.
• كل طلب يُسجَّل في تقرير الاستهلاك مع النقطة والحالة وزمن الاستجابة.

الخصوصية

الخصوصية غير قابلة للتفاوض. العناوين السكنية خاصة افتراضياً ولا تظهر في الواجهة إطلاقاً: يعود 403 private دون أي تسلسل أو إحداثيات أو بيانات مالك.

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