واجهة سيرياسان البرمجية — الإصدار v1

واجهة REST رسمية لشركاء التوصيل والمتاجر وتطبيقات الخرائط. كل طلب يحتاج مفتاحاً صالحاً، ويُحتسب ضمن حدّ المعدل، ويُسجَّل في تقرير الاستهلاك.

إدارة مفاتيح API

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

أرسل المفتاح في Authorization: Bearer san_live_… أو x-api-key.
تُخزَّن المفاتيح مُجزّأة (SHA-256) فقط — لا يمكن استرجاع المفتاح بعد إنشائه.
لكل حساب حدّ افتراضي للمعدل بالدقيقة، وتعود الترويسات X-RateLimit-Limit وX-RateLimit-Remaining، وعند التجاوز يعود 429.
الصلاحيات تُمنح لكل حساب ولكل مفتاح؛ نقص الصلاحية يعيد 403.
يمكن إلغاء أي مفتاح فوراً، وكل إنشاء أو إلغاء يُسجَّل في سجل التدقيق.

الخصوصية غير قابلة للتفاوض: العناوين السكنية الخاصة لا تُكشف أبداً عبر هذه الواجهة — تعيد 403 private بلا أي تفاصيل. لمشاركة عنوان خاص مؤقتاً استخدم رابط المشاركة المؤقت الذي ينشئه صاحب العنوان.

POST/api/v1/addressesaddresses:write

إنشاء عنوان ذكي عام جديد وتوليد رمزه تلقائياً.

curl -X POST https://syriasan.com/api/v1/addresses \
  -H "Authorization: Bearer san_live_…" \
  -H "Content-Type: application/json" \
  -d '{"name_ar":"فرع المزة","governorate":"دمشق","governorate_code":"DAM",
       "city":"دمشق","street":"أوتوستراد المزة","latitude":33.5138,"longitude":36.2765,
       "entrance_name":"المدخل الرئيسي","entrance_instructions":"يمين المبنى"}'

GET/api/v1/addresses/{code}addresses:read

بيانات العنوان العام الكاملة: الموقع، المدخل، النشاط التجاري، روابط الصفحة وQR.

curl https://syriasan.com/api/v1/addresses/SY-DAM-K7X4 \
  -H "x-api-key: san_live_…"

GET/api/v1/resolve/{code}resolve

حلّ حسب الغرض (توصيل، زيارة، إسعاف…) مع المدخل الموصى به والتقييدات.

curl "https://syriasan.com/api/v1/resolve/SY-DAM-K7X4?purpose=parcel_delivery&wheelchair=true" \
  -H "x-api-key: san_live_…"

GET/api/v1/searchsearch

بحث في العناوين العامة بالاسم أو المحافظة أو المدينة.

curl "https://syriasan.com/api/v1/search?q=برج&governorate=دمشق&limit=10" \
  -H "x-api-key: san_live_…"

POST/api/v1/validatevalidate

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

curl -X POST https://syriasan.com/api/v1/validate \
  -H "x-api-key: san_live_…" -H "Content-Type: application/json" \
  -d '{"code":"SY-DAM-K7X4","latitude":33.51,"longitude":36.27}'

POST/api/v1/geocodegeocode

تحويل نص إلى إحداثيات: نتائج سيرياسان أولاً ثم OpenStreetMap داخل سوريا.

curl -X POST https://syriasan.com/api/v1/geocode \
  -H "x-api-key: san_live_…" -H "Content-Type: application/json" \
  -d '{"query":"المزة أوتوستراد","lang":"ar"}'

POST/api/v1/reverse-geocodegeocode

أقرب العناوين الذكية العامة لنقطة، مع وصف المكان من OpenStreetMap.

curl -X POST https://syriasan.com/api/v1/reverse-geocode \
  -H "x-api-key: san_live_…" -H "Content-Type: application/json" \
  -d '{"latitude":33.5138,"longitude":36.2765,"radius_m":300}'

GET/api/v1/qr/{code}qr

رمز QR للعنوان: JSON افتراضياً أو صورة SVG عبر format=svg.

curl "https://syriasan.com/api/v1/qr/SY-DAM-K7X4?format=svg&size=640" \
  -H "x-api-key: san_live_…"

GET/api/v1/routeroute

مسار حتى المدخل المناسب — وليس مركز المبنى — بالسيارة أو مشياً أو بالدراجة.

curl "https://syriasan.com/api/v1/route?from=33.50,36.29&to=SY-DAM-K7X4&mode=driving" \
  -H "x-api-key: san_live_…"

GET/api/v1/capabilitiesaddresses:read

عقد تكامل محايد يعلن القطاعات والقدرات وسياقات المداخل وحدود الخصوصية، دون ادعاء وجود موصلات حية.

curl https://syriasan.com/api/v1/capabilities \
  -H "x-api-key: san_live_…"

POST/api/v1/eventsevents:write

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

curl -X POST https://syriasan.com/api/v1/events \
  -H "x-api-key: san_live_…" -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"}'

POST/api/v1/keys/revokekeys:manage

إلغاء أحد مفاتيح حسابك فوراً باستخدام بادئة المفتاح.

curl -X POST https://syriasan.com/api/v1/keys/revoke \
  -H "x-api-key: san_live_…" -H "Content-Type: application/json" \
  -d '{"key_prefix":"san_live_9fA2xQ1"}'

العنوان البديل /api/public/v1/… يعمل بنفس الطريقة تماماً.