المطورون
واجهة REST عامة للأندية والشركاء المعتمدين: قراءات بنطاقات محددة، وحجوزات عبر الواجهة، وWebhooks موقّعة بـ HMAC.
المصادقة
يُنشأ كل مفتاح من لوحة النادي، ضمن الإدارة → واجهة API وويب هوك، ويُرسل في ترويسة Bearer.
curl -H "Authorization: Bearer mp_…" \
https://api.meetandplay.mx/api/v1/clubs/{clubId}/bookingsيظهر المفتاح الكامل مرة واحدة فقط. احفظه في مكان آمن.
نقاط الوصول
يحدد كل مفتاح النطاقات التي أُنشئ بها؛ ويُرفض أي طلب بلا النطاق المطلوب.
- GET
/clubs/{clubId}/courtsكتالوج ملاعب النادي.
- GET
/clubs/{clubId}/availabilityالمواعيد المشغولة لكل ملعب، حتى 14 يومًا.
- GET
/clubs/{clubId}/bookingsحجوزات النادي، الأحدث أولًا.
- GET
/clubs/{clubId}/customersدليل عملاء النادي، وهي بيانات شخصية، ضمن نطاق خاص بها.
- POST
/clubs/{clubId}/bookingsينشئ حجزًا، مثل مكتب النادي نفسه.
- POST
/clubs/{clubId}/bookings/{bookingId}/cancelيلغي حجزًا؛ ويسترد الدفعة أو يبطلها بحسب سياسة النادي.
ويب هوك
استقبل أحداثًا موقّعة بـ HMAC-SHA256 على عنوانك الخاص: إنشاء حجز أو تأكيده أو إلغاؤه، ونجاح دفعة، واكتمال مباراة. تُعاد كل محاولة إرسال مع تأخير متزايد؛ وبعد عدة محاولات فاشلة تصل إلى طابور الرسائل الفاشلة، ويمكن إعادة إرسالها من لوحة النادي.
مصادقة Webhook
إضافة إلى توقيع HMAC (x-map-signature)، يمكن لكل webhook إرسال ترويسة Authorization، إما Basic (اسم مستخدم وكلمة مرور) أو Bearer (رمز). اضبطها في لوحة النادي، ضمن الإدارة → واجهة API وويب هوك، في مصادقة كل webhook. تُخزَّن بيانات الاعتماد مشفّرة ولا تظهر مرة أخرى.
POST https://…/webhooks x-map-signature: t=1767225600,v1=… x-map-delivery: 0199… Authorization: Bearer …
- تُرسل مع كل عملية إرسال، بما فيها إعادة المحاولة وإعادة الإرسال من طابور الرسائل الفاشلة، باستخدام بيانات الاعتماد الحالية وقت الإرسال: إن غيّرتها أو أزلتها، ينطبق التغيير أيضًا على عمليات الإرسال الموجودة في الطابور. وإن تعذّر على الخادم فك تشفير بيانات الاعتماد، فلن يُرسل الطلب دونها أبدًا؛ بل يذهب إلى طابور الرسائل الفاشلة. وإن غيّرت العنوان أو حذفت webhook، تُلغى عمليات الإرسال الموجودة في الطابور للعنوان القديم أو تُنقل إلى طابور الرسائل الفاشلة: فلا تُرسل بيانات الاعتماد أبدًا إلى عنوان لم يعد مسجّلًا لديك.
- ما زلنا نوصي بالتحقق من توقيع HMAC: فترويسة Authorization تقول من يتصل، لكن التوقيع وحده يثبت أن المحتوى لم يُعدَّل، ويتيح لك طابعه الزمني (t=) رفض عمليات الإرسال المعادة.
- لا تُتبع عمليات إعادة التوجيه: تُحتسب استجابة 3xx عملية إرسال فاشلة وتُعاد محاولتها، فلا تنتقل بيانات الاعتماد إلى عنوان آخر. سجّل العنوان النهائي لمستقبلك.
حدود المعدل
لكل مفتاح حد للطلبات في الدقيقة. تعني استجابة 429 أنك بلغته؛ أبطئ وأعد المحاولة.
الشركاء المعتمدون
يتصل الشريك المعتمد بنقرة واحدة من لوحة النادي، دون نسخ المفاتيح ولصقها يدويًا.
هل أنت مستعد لربط ناديك؟
سجّل الدخول إلى لوحة النادي وأنشئ مفتاحك الأول ضمن الإدارة → واجهة API وويب هوك.