كيف يرسل المستشعر قراءاته: العنوان ومفتاحه، والمحتوى، والرد على كل قراءة، والرموز التي قد يلقاها الطلب.
يرسل مستشعر أصول حيز قراءاته إلى نقطة استقباله الخاصة، بمفتاحه الخاص:
POST https://haiyz.net/api/sensors/<sensor id>/readings
Authorization: Bearer hyzsn_…
Content-Type: application/json
تعرض صفحة المستشعر في بوابة حيز عنوانه، وآخر أربعة أحرف من مفتاحه، وأول طلب مبنيًّا من قنواته. ويُنشأ المفتاح هناك (أو في مركز التحكم › التراخيص والتطبيقات › المستشعرات) ويُعرض مرة واحدة. وهو يفتح نقطة الاستقبال هذه ولا شيء غيرها، وليس جلسة.
curl -X POST "https://haiyz.net/api/sensors/$SENSOR_ID/readings" \
-H "Authorization: Bearer $SENSOR_KEY" \
-H "Content-Type: application/json" \
-d '{"readings":[{"at":"2026-10-01T09:00:00Z","values":{"t1":41.5,"p1":3.1}}]}'
{ "readings": [
{ "at": "2026-10-01T09:00:00Z", "values": { "t1": 41.5, "p1": 3.1 } },
{ "at": "2026-10-01T09:01:00+03:00", "values": { "t1": 41.7 }, "location": [46.71, 24.69] }
] }
| الحقل | هو |
|---|---|
readings |
من قراءة إلى 500، ضمن حد 1 MB لمحتوى الطلب في الواجهة البرمجية |
at |
وقت القراءة — وقت المستشعر نفسه — بصيغة ISO 8601 مع فرق التوقيت (Z أو +03:00)؛ ويُرفض الرقم بالملي ثانية |
values |
قنوات المستشعر وقيمها: رقم لقياس رقم، وعدد صحيح لـعدد صحيح، وtrue أو false لـنعم / لا |
location |
اختياري: [خط الطول، خط العرض] بالدرجات. ينقل نقطة الأصل في الطبقة الحيّة، ويقرؤه فحص المنطقة في القاعدة |
القراءة تحتاج قيمة أو موقعًا، وتُرفض التي بلا أي منهما.
200، بغلاف المنصة، وفي data حساب كل قراءة:
{ "ok": true, "code": "SENSOR_READINGS_RESULT", "data": {
"accepted": ["2026-10-01T09:00:00.000Z"],
"duplicates": [],
"refused": [{ "at": "2026-10-01T09:01:00.000Z", "reason": "SENSOR_READING_UNKNOWN_CHANNEL", "channel": "t9" }]
} }
at هما مفتاح عدم
التكرار، فيمكن دائمًا إعادة إرسال الدفعة بعد انقضاء المهلة.| السبب | القراءة |
|---|---|
SENSOR_READING_AT_INVALID |
بلا at، أو بوقت بلا فرق توقيت |
SENSOR_READING_IN_FUTURE |
متقدمة بأكثر من 10 دقائق — راجع ساعة المستشعر |
SENSOR_READING_TOO_OLD |
أقدم مما تحفظه المؤسسة من القراءات |
SENSOR_READING_UNKNOWN_CHANNEL |
تسمّي قناة لا يربطها المستشعر |
SENSOR_READING_BAD_VALUE |
فيها قيمة ليست من نوع قياسها، أو لا تقول شيئًا |
SENSOR_READING_LOCATION |
فيها location ليس [خط الطول، خط العرض] |
SENSOR_READING_DUPLICATE_IN_BATCH |
تشارك قراءةً أخرى في الطلب نفسه وقتها |
SENSOR_READINGS_DAILY_LIMIT |
جاءت بعد نفاد قراءات المؤسسة لليوم |
| الحالة | الرمز | السبب |
|---|---|---|
| 401 | SENSOR_KEY_INVALID |
رد واحد لكل حالة خاطئة: لا مفتاح، أو مفتاح خاطئ، أو مفتاح ملغى، أو مستشعر غير معروف |
| 403 | SENSOR_DISABLED |
المستشعر موقوف |
| 403 | SENSOR_HELD |
أوقفت حيز المستشعر |
| 403 | ASSETS_HELD |
أوقفت حيز أصول حيز للمؤسسة |
| 403 | ASSETS_SUSPENDED |
المؤسسة غير نشطة |
| 403 | LICENSE_FEATURE_MISSING |
نسخة مستضافة ذاتيًا لا يشمل ترخيصها أصول حيز |
| 400 | SENSOR_READINGS_BATCH_INVALID |
لا قراءة، أو أكثر من 500 |
| 429 | SENSOR_RATE_LIMITED |
طلبات هذه الدقيقة أكثر مما يحق للمستشعر (60 في Haiyz Cloud) |
| 429 | SENSOR_READINGS_DAILY_LIMIT |
نفدت قراءات المؤسسة لليوم (بتوقيت UTC) |
ويحمل كل رد رسالته بالعربية والإنجليزية بجانب رمزه، والغلاف موثّق مرة واحدة في مرجع الواجهة البرمجية.
النظام الذي يرسل عن موقع كامل — تصدير من نظام سكادا، أو مؤرشف قراءات، أو متحكم موقع — يحمل بيانات اعتماد
واحدة لا واحدة لكل مستشعر. البوابة في بوابة حيز (أصول حيز › البوابات) هي ذلك المفتاح الواحد،
hyzgw_…، وكل مستشعر مربوط بها يرسل عبرها:
POST https://haiyz.net/api/gateways/<gateway id>/readings
Authorization: Bearer hyzgw_…
Content-Type: application/json
{
"readings": [
{ "sensor": "66f1…", "at": "2026-10-09T08:00:00+03:00", "values": { "temperature_c": 41.2 } },
{ "asset": "6f1c0e5e-…", "at": "2026-10-09T08:00:00+03:00", "values": { "pressure_bar": 3.1 } }
]
}
تسمّي كل قراءة المستشعر بمعرّفه، أو الأصل بمعرّف الأصل — واحدًا منهما. وتسمية الأصل تعمل حين يكون على الأصل
مستشعر واحد بالضبط مربوط بهذه البوابة، فلا يحتاج النظام الذي يعرف معرّفات الأصول أن يتعلم معرّفات المستشعرات.
والمستشعر غير المربوط بالبوابة مجهول لديها (GATEWAY_SENSOR_UNKNOWN)، والموقوف أو الذي أوقفته حيز يُرفض
بالاسم — ويمضي باقي الطلب. وتتسع الطلبة الواحدة لخمسة آلاف قراءة.
وبعد تجميع القراءات حسب المستشعر، يُحكم على حصة كل مستشعر كما تحكم عليها نقطة استقباله هو: القنوات
نفسها، وقواعد الوقت نفسها، وduplicates نفسها، والحدود اليومية نفسها. والرد بالشكل نفسه، مع اسم المستشعر في كل
صف وعدٍّ لكل مستشعر. ويُرفض الطلب كاملًا بـ401 GATEWAY_KEY_INVALID لمفتاح مفقود أو خاطئ أو ملغى، وبـ403 GATEWAY_DISABLED أو GATEWAY_HELD لبوابة موقوفة، وبـ429 GATEWAY_RATE_LIMITED بعد تجاوز طلبات البوابة في
الدقيقة. ويجوز للمستشعر المربوط ببوابة أن يحتفظ بمفتاح خاص به؛ وكلاهما يعمل.
