نقطة استقبال المستشعر

الطلب¶

يرسل مستشعر أصول حيّز قراءاته إلى نقطة استقباله الخاصة، بمفتاحه الخاص:

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" }]
} }

• accepted — حُفظت.
• duplicates — أرسل هذا المستشعر قراءة في ذلك الوقت من قبل، فلا يتغيّر شيء. المستشعر وat هما مفتاح عدم التكرار، فيمكن دائمًا إعادة إرسال الدفعة بعد انقضاء المهلة.
• refused — كلٌّ بسببه، وبالقناة حين كانت القيمة هي السبب:

السبب	القراءة
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)

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

كتابة المُرسِل¶

• أرسل وقت المستشعر نفسه. اضبط ساعته؛ فالدفعة المتراكمة مقبولة مهما تأخرت، ضمن مدة حفظ المؤسسة، وتقع حيث تقول أوقاتها.
• أعد المحاولة بلا قلق. الدفعة المعادة بعد انقضاء المهلة يُرد على ما وصل منها أولًا بـduplicates.
• أرسل المتراكم الأقدم أولًا، في طلبات حتى 500 — وراعِ حد الدقيقة.
• مفتاح لكل مستشعر. البوابة التي ترسل عن عدة مستشعرات تحمل مفتاح كل واحد منها.
• HTTPS فقط. المستشعر الذي لا يتكلم إلا MQTT يحتاج وسيطًا لديك ومُحوِّلًا صغيرًا إلى نقطة الاستقبال هذه.
• يُحصى كل طلب في الحركة للمستشعر في بوابة حيّز — المقبول، والمستلم من قبل، والمرفوض وسببه — لا في سجل التدقيق.