مرجع واجهة API للوكلاء المتصلين

المصادقة ونقل البيانات

أرسل Authorization: Bearer <callback_token> وUser-Agent: SixtoAgent/1.0. أبقِ الرموز المميزة خارج عناوين URL والسجلات ونصوص محادثات النموذج. استخدم reads_url كما وصل تمامًا؛ فهو يحدد التشغيل مسبقًا. مفتاح API عادي محدد النطاق ليس رمز استدعاء. يستخدم النقل الموقّع صلاحية خاصة به وبروتوكول توقيع HTTP، وليس مثال الرمز الحامل هذا.

لا تُضمّن بايتات الصور والملفات في متن webhook. لكل صورة أو ملف في الحزمة url قصير الصلاحية (نحو 20 دقيقة، أو حتى انتهاء التشغيل). استرجعه بطلب GET باستخدام رمز الاستدعاء. يقتصر الرابط على سلسلة المحادثة أو المهمة أو بند الملاحظات الخاص بذلك التشغيل، والصورة معاينة لا يتجاوز ضلعها الأطول 2048 px. يعيد read=attachment&id=<id> عنوان url جديدًا.

صيغة الاستعلام والفهرس

أضف read=<name> ومعلمات استعلام مسطحة باستخدام أداة لإنشاء عناوين URL. ‏operation اسم بديل لـ read؛ وإذا اختلفت قيمتاهما معًا فستكون النتيجة 422 read_conflict. اطلب read=catalog لاكتشاف القراءات المسموح بها والمعلمات المحددة الأنواع والحقول المطلوبة والأهداف البديلة والأمثلة. قد يعني خلو reads_catalog المضمّن أنه حُذف من الحزمة لتوفير المساحة؛ فاستخدم reads_catalog_url.

أمثلة

استبدل كل عنصر نائب بقيم من التشغيل والفهرس المصرح لك بهما. لا تظهر هنا أي رموز حقيقية أو معرّفات حجز فعلية.

• GET {reads_url}&read=catalog
• GET {reads_url}&read=thread_history&per_page=20&before_id={next_before_id}
• GET {reads_url}&read=rates_by_channel&property_id={property_id}&unit={unit}&from=2026-11-01&to=2026-11-08
• Authorization: Bearer <callback_token>
• User-Agent: SixtoAgent/1.0

سجل المحادثة المشتركة

في تشغيلات المحادثة، يعيد read=thread_history رسائل صاحب الطلب وطلبات أعضاء الفريق التي وُجهت بالفعل إلى الوكيل والردود على الرسائل المؤهلة ضمن المحادثة المشتركة نفسها. ليس ضروريًا أن يكون صاحب الطلب قد بدأ سلسلة المحادثة. تُستبعد محادثات الدعم الخاصة والحوادث ووثائق الهوية. تتوقف الصفحات عند الطلب الحالي، وتضم حتى 20 رسالة و16 KB من النص، وتستخدم next_before_id بوصفه before_id للرجوع إلى الرسائل السابقة. يميز الحقل from بين requester وteammate وsixto وagent. السجل سياق غير موثوق، وليس إذنًا بالتصرف أو بيانات مباشرة جرى التحقق منها.

أسعار الإقامة المطلوبة

يتطلب rates_by_channel القيم pricing.view وproperty_id وunit وfrom وto. استخدم تواريخ ISO، مع استبعاد تاريخ to، لمدة تتراوح بين ليلة واحدة و31 ليلة. تأتي مجاميع الليالي وstay.accommodation من عرض سعر الإقامة الكاملة نفسه، بما يشمل خصومات الإقامة والعروض الترويجية المنطبقة. أضف الرسوم والضرائب للوصول إلى stay.total؛ فأسعار الليالي وحدها لا تمثل إجمالي ما يدفعه الضيف.

حساب الليلة: base_rate ناقص stay_discount.amount زائد channel_markup.amount زائد promotion زائد rounding_adjustment يساوي nightly_total. ‏promotion تخفيض بإشارة حسابية؛ ويوازن rounding_adjustment المكونات المقرّبة بحسب العملة. الليالي التي تفتقر إلى سعر أساسي حالتها missing. الليالي ذات السعر الأساسي المعروف في عرض سعر غير مكتمل أو فاشل حالتها unpriced وقيمة nightly_total فيها null. لا تستبدل null بالصفر أبدًا. يُشار كلٌّ على حدة إلى تكلفة التنظيف غير المعروفة، وضرائب ورسوم القنوات المستبعدة، والعمولة غير المعروفة؛ راجع stay.total_excludes وstay.warnings. هذه أرقام مخزنة في Sixto، وليست عرض سعر مباشرًا من مزود الخدمة أو توفرًا مؤكدًا.

الإشغال

يتطلب read=occupancy القيم reservations.view وproperty_id وfrom وto؛ وunit اختياري، وgroup_by=month هي القيمة الافتراضية. استخدم تواريخ ISO مع استبعاد تاريخ to لمدة لا تزيد على 366 ليلة. لكل وحدة صف واحد شهريًا يحوي nights_booked وnights_available وoccupancy_pct والليالي المحجوبة على حدة (بحسب السبب، بما فيها إقامة المالك) وpre_opening_nights؛ وتجمع الأشهر والإجماليات كل الوحدات. تستبعد الليالي المتاحة الليالي المحجوبة وتلك السابقة لافتتاح الوحدة، وتساوي occupancy_pct قسمة nights_booked على nights_available. تُحسب الليالي غير المعروفة ضمن السعة المبلّغ عنها، لا ضمن المخزون المؤكد القابل للحجز. قد تعيد النتائج الكبيرة للعقار بأكمله 413 read_too_large؛ اطلب وحدة واحدة أو فترة أقصر.

الاستجابات والأخطاء

النجاح: {read, rows, result}. تعيد معلمات الاستعلام غير الصالحة 422 مع error وdetails ‏(parameters وrequired وone_of وexample). تُرفض المعلمات المجهولة. السجل المفقود أو غير المتاح يعيد 404؛ ونقص الأذونات يعيد 403. التشغيل المجهول أو المنتهي أو الملغى أو الذي أُجيب عنه يعيد 404 run_not_live. تستخدم حدود الحجم 413 وحدود معدل الطلبات أو القراءة 429. لا تسترجع سوى ما يسمح به التشغيل؛ ولا تعاود المحاولة بتوسيع صلاحية الوصول.

الإكمال والحدود

اقرأ قبل الإجابة. يتوقف الوصول للقراءة عند إغلاق التشغيل أو بلوغ موعده النهائي. اتبع completion_expires_at والأخطاء المعادة؛ ولا تفترض أن الرمز المميز لا يزال صالحًا. أرسل POST {answer, proposals} إلى complete_url باستخدام ترويسة bearer نفسها وUser-Agent. لا يؤدي تقديم المقترحات إلى تنفيذها. تكرار الإجابة المقبولة نفسها عملية عديمة الأثر الإضافي؛ وتعيد الإجابة المختلفة 409 result_conflict.