واجهة برمجة التوفر (API)

أنشئ مفتاحًا

أنشئ مفتاحًا من /app/api-keys لمنشأتك. اترك الصلاحية على التوفر فيحمل المفتاح صلاحية availability:write وحدها — لا يمكنه فعل أي شيء آخر. (الخيار الآخر، المضيف، ينشئ مفتاح حجوزات لمنصة المضيف؛ ولا يمكنه المساس بالتوفر.) يُعرض المفتاح الكامل (qk_…) مرة واحدة عند الإنشاء؛ بعدها لا تُعرض إلا بادئته، والإبطال يقطعه فورًا.

تحديث صنف واحد

curl -X PATCH https://app.qaema.ai/v1/items/<item_id>/availability \
  -H "authorization: Bearer qk_…" \
  -H "content-type: application/json" \
  -d '{"available": false, "until": null, "reason": "Out of lamb"}'

available مطلوب؛ وuntil إما طابع زمني بصيغة ISO أو null بمعنى “حتى إشعار آخر” (وهو الافتراضي)؛ وreason اختياري، بحد أقصى 200 حرف. الاستدعاء الناجح يعيد الصنف المحدَّث ومعرّف التغيير.

تحديث عدة أصناف دفعة واحدة

POST /v1/items/availability تأخذ الحقول نفسها إضافة إلى مصفوفتي item_ids و/أو section_ids بدلاً من معرّف في المسار — مفيدة لإخراج قسم كامل معًا. إحدى القائمتين مطلوبة على الأقل، وإلا يُرفض الطلب.

قراءة خريطة النفاد العامة

GET /v1/venues/<slug>/availability.json لا تحتاج مفتاحًا — وهي البيانات نفسها التي تستطلعها القائمة العامة، مخزَّنة مؤقتًا لمدة 30 ثانية. تعيد فقط الأصناف غير المتاحة حاليًا، مفهرسة بمعرّف الصنف، مع until وreason لكل منها؛ والصنف الذي انقضت نافذة نفاده يُستبعد من الاستجابة قبل إرسالها.

رموز الخطأ

المفتاح المفقود أو غير المعروف أو المُبطل يحصل على 401. المفتاح الذي لا يحمل صلاحية availability:write، أو المستخدم ضد صنف أو قسم خارج منشأته، يحصل على 403. الطلب المشوَّه يحصل على 400.

المفاتيح والمنشآت المحذوفة

ينتمي كل مفتاح إلى منشأة واحدة. احذف تلك المنشأة، ويتوقف كل مفتاح صادر لها عن المصادقة — يُرفض تمامًا كالمفتاح المبطل، دون طريقة للتمييز بين الحالتين من الاستجابة.