التوثيق البرمجي الشامل - Hawas TMS REST API Documentation

المقدمة والبداية السريعة (Quickstart)

توفر منصة حواس TMS واجهة برمجية RESTful كاملة تعتمد على بروتوكول HTTP وتستخدم نسق JSON في تبادل البيانات، مما يسمح لأنظمتك بإنشاء الرموز الذكية وتعديل الروابط المستهدفة في أي وقت برمجياً دون الحاجة للدخول إلى واجهة المستخدم.

عنوان الخادم الأساسي (Base URL):

https://hawas-qr.com/api/v1

للبيئة المحلية التجريبية: http://localhost:5050/api/v1

المصادقة وتأمين الطلبات (Authentication)

تتطلب جميع نقاط النهاية البرمجية تضمين مفتاح الـ API الخاص بحسابك في ترويسة الطلب (Header):

HTTP Request Header

X-API-Key: hw_live_your_actual_api_key_here

أو عبر رمز الدخول التوثيقي Bearer Token عند الربط عبر واجهات الويب:

JWT Bearer Authorization

Authorization: Bearer <jwt_access_token>

أمان المفتاح: لا تشارك مفتاح API السري في أكواد الجافاسكريبت المفتوحة من جانب العميل (Frontend). احفظه دائماً في متغيرات البيئة من جانب الخادم (Backend Environment Variables).

GET /tags

جلب قائمة الرموز والبطاقات الذكية التابعة للمستخدم المصادق عليه، مع دعم البحث والصفحات.

معايير الاستعلام (Query Parameters):

المعيار	النوع	الوصف
`page`	integer	رقم الصفحة (الافتراضي: 1)
`pageSize`	integer	عدد العناصر في الصفحة (الافتراضي: 50)
`search`	string	نص البحث في العنوان أو المعرف الافتراضي

نموذج الاستجابة (200 OK)

{
  "success": true,
  "data": {
    "tags": [
      {
        "Id": 101,
        "VirtualId": "t-adam-001",
        "Title": "تمثال الصقر - متحف آدم حنين",
        "MapURL": "https://adamhenein.org/exhibits/falcon",
        "CountOfUse": 45,
        "Active": true,
        "CreatedOnUtc": "2026-03-20T10:00:00.000Z"
      }
    ],
    "pagination": { "page": 1, "pageSize": 50, "total": 1 }
  }
}

POST /tags

إنشاء رمز ديناميكي جديد أو تسجيل بطاقة ذكية ضمن باقة الحساب الحالية مع فحص الحصة المتاحة.

حمولة الطلب (Request Body JSON):

الحقل	النوع	إلزامي؟	الوصف
`Title`	string	نعم	اسم الرمز أو عنوان القطعة المعروضة
`MapURL`	string	نعم	الرابط المستهدف الأولي (URL كامل يبدأ بـ http/https)
`VirtualId`	string	اختياري	معرف مخصص (إن لم يُرسل يتم توليده تلقائياً مثل `t-xxxx`)
`Description`	string	اختياري	شرح تفصيلي للرمز أو المعروضة

مثال على الطلب (cURL)

curl -X POST "https://hawas-qr.com/api/v1/tags" \
  -H "X-API-Key: hw_live_adam_henein_museum_2026_vip" \
  -H "Content-Type: application/json" \
  -d '{
    "Title": "تمثال البومة - برونز",
    "MapURL": "https://adamhenein.org/exhibits/owl",
    "VirtualId": "t-adam-owl"
  }'

PUT /tags/:virtualId

القلب النابض لنظام Hawas TMS: تغيير الرابط المستهدف (MapURL) فورياً في أجزاء من الثانية دون أي تغيير على الرمز المطبوع أو بطاقة الـ NFC الحقيقية.

مثال على التحديث (cURL)

curl -X PUT "https://hawas-qr.com/api/v1/tags/t-adam-001" \
  -H "X-API-Key: hw_live_adam_henein_museum_2026_vip" \
  -H "Content-Type: application/json" \
  -d '{
    "MapURL": "https://adamhenein.org/exhibits/falcon-new-interactive-guide"
  }'

GET /qr/:virtualId

توليد ودفق صورة الـ QR المباشرة التابعة للرمز بصيغة PNG أو فيكتور SVG مع دعم الألوان وهوية حواس الذهبية.

خيارات الصورة (Query Parameters):

المعيار	النوع	الافتراضي	الوصف
`format`	string	`png`	صيغة الصورة (`png` أو `svg`)
`width`	integer	`512`	أبعاد الصورة بالبكسل
`color`	hex string	`#c38846`	لون نقاط الباركود (ذهبي حواس افتراضياً)
`bg`	hex string	`#ffffff`	لون الخلفية

مخصص للمتاحف والمؤسسات الثقافية

تكامل متحف آدم حنين (Adam Henein Museum VIP Guide)

تم إعداد حساب مخصص لمتحف الفنان الراحل آدم حنين مع إمكانيات غير محدودة لتوليد الرموز ومسحها، متصلاً مباشرة ببطاقات المعروضات التفاعلية وألواح النحت واللوحات الجدارية لأكثر من 5,300 قطعة فنية.

دليل المطور الخاص ببوابة متحف آدم حنين (Museum Portal Guide)

دليل تفصيلي جاهز لإرساله لمطوري بوابة المتحف يشمل كافة واجهات الربط، نماذج PHP/WordPress وJS وPython، ونظام الاستبدال الجماعي للنطاقات (Bulk Domain Migration).

فتح دليل المطورين الشامل

أمثلة من الرموز المعرفة في قاعدة بيانات المتحف (من أصل 5,328 رمز):

• m-00001 : تمثال الصقر (رابط التوجيه: https://adamheneinmuseum.com/m-00001)
• m-00002 : تمثال الشاعر (رابط التوجيه: https://adamheneinmuseum.com/m-00002)
• m-00003 : لوحة الصلاة (رابط التوجيه: https://adamheneinmuseum.com/m-00003)

نماذج بلغات البرمجة وتطبيقات الموبايل

Android Native (Kotlin & OkHttp) - قراءة بطاقة NFC وتحديث وجهتها

Kotlin (Android OkHttp)

val client = OkHttpClient()
val jsonMediaType = "application/json; charset=utf-8".toMediaType()

val jsonPayload = """{"MapURL": "https://adamhenein.org/audio-guide/sculpture-3"}"""
val body = jsonPayload.toRequestBody(jsonMediaType)

val request = Request.Builder()
    .url("https://hawas-qr.com/api/v1/tags/t-adam-001")
    .put(body)
    .addHeader("X-API-Key", "hw_live_adam_henein_museum_2026_vip")
    .build()

client.newCall(request).enqueue(object : Callback {
    override fun onFailure(call: Call, e: IOException) {
        Log.e("TMS", "Failed: ${e.message}")
    }
    override fun onResponse(call: Call, response: Response) {
        Log.d("TMS", "Updated successfully: ${response.body?.string()}")
    }
})

Python - جلب إحصائيات المعرض تلقائياً

Python 3 (Requests)

import requests

API_KEY = "hw_live_adam_henein_museum_2026_vip"
BASE_URL = "https://hawas-qr.com/api/v1"

headers = {
    "X-API-Key": API_KEY,
    "Content-Type": "application/json"
}

# جلب بيانات وتحليلات الرمز
response = requests.get(f"{BASE_URL}/tags/t-adam-001/analytics", headers=headers)
data = response.json()

if data.get("success"):
    stats = data["data"]
    print(f"Total Scans: {stats['totalScans']}")
    print(f"Last 30 Days: {stats['last30DaysScans']}")

التوثيق البرمجي لنظام حواس لإدارة الرموز الذكية