مرجع API
بدء الاستخدام

بدء الاستخدام

يقدّم هذا القسم وصفاً لواجهة Web API الخاصة بالمنصة، المنفَّذة على هيئة حزمة بيانات REST-API للتبادل بصيغة json.

أحكام عامة

صيغة نقل البيانات واجهة Web API منفَّذة على هيئة حزمة بيانات REST-API للتبادل بصيغة json.
إجراء المصادقة تقوم المصادقة على رمز وصول يُحدَّث ديناميكياً، ما يضمن أمن البيانات المستلَمة ويمنع تسرّب الرمز.
صيغة المتغيّرات التي تحتوي على التاريخ والوقت تُعيد واجهة Web API البيانات من نوع «التاريخ والوقت» بترميز UNIX time أو POSIX time بالصيغة UTC: 1613376963. وعند تحويل Unix time إلى تاريخ مقروء، يجب تحديد المنطقة الزمنية.
التقسيم إلى صفحات (pagination) تطبّق واجهة Web API وظيفة التقسيم إلى صفحات لتحميل البيانات صفحةً صفحة. ويُمرَّر ذلك بالمعامل: page="page number" (page=1). أما عدد السجلات المعادة في الطلب فيمكن تحديده بالمعامل per_page، على ألّا يتجاوز 1000 سجل.

عنوان URL الأساسي

تستخدم جميع الأمثلة الواردة في هذه الصفحات عنوان URL الأساسي التالي:

bash

https://api.vadsro.eu/api/v1

المصادقة

تقوم المصادقة على رمز وصول يُحدَّث ديناميكياً. وعملياً يبدو الأمر على النحو التالي:

تُجرى المصادقة الأولية باستخدام بريد إلكتروني وكلمة مرور موجودَين في النظام، ويُستلَم في الاستجابة رمز وصول ديناميكي والسمات المرتبطة به.
تكوين الطلب المستهدَف للحصول على البيانات، مع إضافة الرمز المستلَم في الخطوة السابقة إلى ترويسات طلب HTTP.
إرسال الطلب إلى الخادم. فإذا كان الطلب مكوَّناً على النحو الصحيح، يُعيد الخادم البيانات في متن الاستجابة ورمزاً جديداً في ترويسات الاستجابة، بينما يصبح الرمز القديم غير صالح. وبالرمز الجديد يمكننا تكرار الخطوة السابقة، وهكذا دواليك.
عند الانتهاء من العمل، يمكن إبطال الرمز الأخير قبل تاريخ انتهاء صلاحيته (SignOut).

تستخدم المصادقة الأولية البريد الإلكتروني وكلمة المرور لمستخدم موجود. ولإجراء ذلك، يلزم إرسال طلب POST إلى العنوان:

bash

https://api.vadsro.eu/api/v1/auth/sign_in

مثال على طلب بصيغة Curl:

bash

curl -i --header "Content-Type: application/json" \
     --request POST \
     --data '{"email":"api-user@example.com","password":"Str0ngPas$"}'\
     https://api.vadsro.eu/api/v1/auth/sign_in

ردًّا على ذلك سنتلقّى الرسالة التالية:

bash

HTTP/1.1 200 OK
X-Frame-Options: SAMEORIGIN
X-XSS-Protection: 1; mode=block
X-Content-Type-Options: nosniff
X-Download-Options: noopen
X-Permitted-Cross-Domain-Policies: none
Referrer-Policy: strict-origin-when-cross-origin
Content-Type: application/json; charset=utf-8
access-token: EXAMPLE-ACCESS-TOKEN-1
token-type: Bearer
client: EXAMPLE-CLIENT-ID
expiry: 1615227012
uid: api-user@example.com
ETag: W/"5b9bcc76f7223b72b79d9f2d31ff0fd5"
Cache-Control: max-age=0, private, must-revalidate
X-Request-Id: c18e06b4-e5bd-40b5-875d-7ac958e2fbb5
X-Runtime: 0.391069
Transfer-Encoding: chunked
{"data":{"id":6,"email":"api-user@example.com","provider":"email","uid":"api-user@example.com","name":"API user"}}

في هذه الاستجابة تهمّنا الترويسات التالية:

الترويسة	الوصف
`access_token`	تُستخدم قيمة هذه الترويسة بوصفها كلمة المرور لكل طلب. وتتغيّر القيمة مع كل طلب.
`client`	هذه الترويسة فريدة للاتصال الحالي. وهي تتيح تشغيل عدّة جلسات نشطة في الوقت نفسه.
`expiry`	وقت انتهاء صلاحية هذا الرمز. القيمة الافتراضية أسبوعان من لحظة استلامه. أو SignOut لإنهاء الصلاحية مبكراً. وهي غير مطلوبة للطلب التالي.
`uid`	قيمة فريدة تعرّف المستخدم. وهي في حالتنا البريد الإلكتروني.
`token-type`	نوع الرمز المستخدَم.

مثال على طلب يستخدم الرمز الوارد في الاستجابة السابقة:

bash

curl -i --header "access-token: EXAMPLE-ACCESS-TOKEN-1" \
 --header "token-type: Bearer" \
 --header "client: EXAMPLE-CLIENT-ID" \
 --header "uid: api-user@example.com" \
 --request GET \
 --header "Content-Type: application/json" \
 --data '{"page":"2"}' \
 https://api.vadsro.eu/api/v1/stations

ردًّا على ذلك سنتلقّى الرسالة التالية:

bash

HTTP/1.1 200 OK
X-Frame-Options: SAMEORIGIN
X-XSS-Protection: 1; mode=block
X-Content-Type-Options: nosniff
X-Download-Options: noopen
X-Permitted-Cross-Domain-Policies: none
Referrer-Policy: strict-origin-when-cross-origin
Content-Type: application/json; charset=utf-8
access-token: EXAMPLE-ACCESS-TOKEN-2
token-type: Bearer
client: EXAMPLE-CLIENT-ID
expiry: 1615311367
uid: api-user@example.com
ETag: W/"ba0df406b647bd92f0bf3a18916714c1"
Cache-Control: max-age=0, private, must-revalidate
X-Request-Id: 35a26441-ae78-48fa-8b2e-e92d2605133b
X-Runtime: 0.167748
Transfer-Encoding: chunked
{"data": [
{"id":1,"name":"860000000000001","equipment_brand_name":"Corrector BK","phone":"","equipment_id":1},...
 ],
"total_pages":7,
"current_page":2
}

ولإنهاء العمل يمكنك استخدام إجراء SignOut، أو حفظ الترويسات اللازمة من الطلب الأخير واستخدامها في المرة التالية إن لم تكن مدة صلاحية الرمز قد انتهت.

إنهاء الجلسة:

bash

curl -i --header "access-token: EXAMPLE-ACCESS-TOKEN-2" \
 --header "token-type: Bearer" \
 --header "client: EXAMPLE-CLIENT-ID" \
 --header "uid: api-user@example.com" \
 --request DELETE \
 https://api.vadsro.eu/api/v1/auth/sign_out
HTTP/1.1 200 OK
X-Frame-Options: SAMEORIGIN
X-XSS-Protection: 1; mode=block
X-Content-Type-Options: nosniff
X-Download-Options: noopen
X-Permitted-Cross-Domain-Policies: none
Referrer-Policy: strict-origin-when-cross-origin
Content-Type: application/json; charset=utf-8
ETag: W/"c955e57777ec0d73639dca6748560d00"
Cache-Control: max-age=0, private, must-revalidate
X-Request-Id: b4b69ac3-5cba-4e6e-b6a0-f6577298c166
X-Runtime: 0.141467
Transfer-Encoding: chunked
{"success":true}

الخطوات التالية

والآن بعد أن أصبحت قادراً على إجراء المصادقة، استكشف الموارد الأساسية لواجهة API:

مزوّدو الموارد والمستهلكون

استعراض التسلسل الهرمي للمزوّدين والمستهلكين الذين يخدمهم كل مزوّد.

وحدات القياس

استعراض قائمة وحدات القياس وقراءة خصائصها الفيزيائية.

أرشيفات القراءات

استرجاع قراءات القنوات حسب نوع الأرشيف والفترة الزمنية.

الأحداث والرسائل

قراءة أرشيفات أحداث الأجهزة ومرجع رموز الرسائل.

آخر تحديث في 8 أغسطس 2026

هل كانت هذه الصفحة مفيدة؟