واجهة vFound البرمجية وWebhooks
اربط مجموعة vFound بالأنظمة التي تستخدمها بالفعل: إدارة الممتلكات، ومكاتب الخدمة، وأنظمة الموارد البشرية والطلاب، وماسحات غرفة البريد، ومستودعات البيانات، أو تطبيقاتك الخاصة. اقرأ السجلات وعدّلها في كل منتج، وأبقِ قائمة الأشخاص لديك متزامنة، واحصل على webhook موقّع خلال ثوانٍ عند حدوث شيء، ودع مساعدي الذكاء الاصطناعي يساعدون عند مكتب الاستقبال.
تريد إعدادًا موجّهًا؟ راجع أدلة التكامل في vFound الخاصة بـ Cloudbeds وOfficeRnD Flex وMicrosoft Entra وSlack وMicrosoft Teams وGoogle Chat والتقويمات وZapier وعملاء MCP.
المصادقة
لكل منشأة واجهة API. ينشئ المالك أو المدير حتى 10 مفاتيح في الإعدادات، للمطورين، ويختار ما يسمح به كل مفتاح. يظهر المفتاح الكامل مرة واحدة. أرسله كرمز Bearer:
curl https://vfound.io/api/v1/items \
-H "Authorization: Bearer vf_live_xxxxxxxxxx_…"
| النطاق | ما يتيحه | نقاط النهاية |
|---|---|---|
items:read | قراءة الأغراض المعثور عليها والفئات وعمليات النقل بين المنشآت | GET /items, /items/{id}, /categories, /item-transfers |
items:write | إضافة الأغراض المعثور عليها وتحديثها، وإرسالها أو استلامها بين المنشآت | POST /items, PATCH /items/{id}, POST /item-transfers مع الإلغاء والاستلام |
claims:write | تسجيل مراجعات الملكية البشرية والقرارات وموافقة التسليم والاستلام | POST /claims/{id}/verification, /claims/{id}/decision, /claims/{id}/release-approval, /claims/{id}/handover |
lost_reports:write | إنشاء بلاغات الضيوف لمركز اتصال | POST /lost-reports |
claims:read | قراءة طلبات الاسترداد مع بيانات التواصل الخاصة بمقدّم الطلب | GET /claims, /claims/{id} |
lost_reports:read | قراءة بلاغات الفقد الخاصة بالضيوف | GET /lost-reports |
analytics:read | قراءة ملخص التحليلات | GET /analytics |
parcels:read | قراءة الطرود مع اسم كل مستلم وبريده الإلكتروني | GET /parcels, /parcels/{id} |
parcels:write | التسجيل والتسليم والإرجاع والتذكير | POST /parcels وإجراءاتها |
checkroom:read | قراءة التذاكر والمحطات والفعاليات وطابور الخروج والتقارير | GET ضمن /checkroom |
checkroom:write | تسجيل الاستلام والتسليم وتحديد الجاهزية وإدارة المحطات أو الفعاليات | POST وPUT ضمن /checkroom |
loans:read | قراءة المعدات ومن لديه كل منها | GET /loans, /loans/items وعنصر واحد من كل منهما |
loans:write | إضافة المعدات وصرفها وتمديد موعد إعادتها واستلامها | POST وPATCH ضمن /loans |
visitors:read | قراءة الزيارات | GET /visitors, /visitors/{id} |
visitors:write | الدعوة وتسجيل الحضور والخروج والإلغاء وإرسال تصريح | POST /visitors وإجراءاتها |
visitors:screening | تأكيد أن تطابق الفحص الخاص بالزائر قد روجع: أرسل screening_reviewed، أو وافق على زيارة يوقفها تطابق. معطّل افتراضيًا؛ ما يفعله المفتاح يُسجَّل باسم المفتاح، مع اسمه | POST /visitors, /visitors/{id}/sign-in, /visitors/{id}/approve |
people:read | قراءة قائمة الأشخاص | GET /people, /people/{id} |
people:write | إضافة الأشخاص وتحديثهم ومزامنتهم وإزالتهم | POST وPATCH وDELETE ضمن /people |
stays:read | قراءة سياق إقامة الفندق الخاص وسجل تصحيحه | GET /stays, /stays/{stay} |
stays:write | إضافة سياق الإقامة أو تحديثه من نظام الفندق بصورة idempotent | POST /stays |
school:read | قراءة حالات تأخر التلاميذ ومغادرتهم المبكرة من مكتب المدرسة | GET /school/movements |
school:write | إضافة التلاميذ أو تحديثهم من نظام معلومات المدرسة | PUT /school/pupils |
queue:read | قراءة طوابير الانتظار والتذاكر والأوقات المحجوزة والرسائل وأرقام الاستبيان وتقرير الطابور | GET ضمن /queue |
queue:write | إضافة أشخاص إلى طابور، واستدعاؤهم، وإنهاء تذاكرهم، وحجز الأوقات وإلغائها، والكتابة إلى الأشخاص في الطابور | POST ضمن /queue |
webhooks:manage | الاشتراك في عناوين webhook الخاصة بالمفتاح نفسه وإلغاء الاشتراك فيها، للأحداث التي يستطيع المفتاح قراءة بياناتها | GET وPOST وDELETE /webhooks |
تحتاج الأغراض وطلبات الاسترداد وبلاغات الفقد والتحليلات إلى vFound Lost & Found؛ وتحتاج الطرود إلى vFound Parcels؛ وتحتاج التذاكر إلى vFound Checkroom؛ وتحتاج المعدات إلى vFound Equipment؛ وتحتاج الزيارات إلى vFound Visitors؛ وتحتاج قائمة الأشخاص إلى Parcels أو Visitors أو Equipment؛ وتحتاج إقامات الفندق إلى Lost & Found أو Parcels؛ ويحتاج مكتب المدرسة إلى Visitors مع تفعيل مكتب المدرسة (يجيب بـ 404 ما دام معطّلًا)؛ وتحتاج طوابير الانتظار والتذاكر إلى vFound Queue. المنتج غير المفتوح للمنشأة يجيب بـ 403.
يعمل المفتاح باسم الشخص الذي أنشأه ويتوقف عن العمل إذا لم يعد ذلك الشخص يدير المنشأة، ما لم يذكر الطلب أحد أعضاء الفريق في X-Acting-User (راجع التصرف نيابةً عن عضو في الفريق). التغييرات التي تتم بمفتاح تمر بالقواعد نفسها ورسائل البريد الإلكتروني نفسها ومسار التدقيق نفسه كما عند مكتب الاستقبال، ويسجّل كل إدخال في التدقيق المفتاح الذي أجرى التغيير. يستطيع كل مفتاح إرسال 120 طلبًا في الدقيقة. العنوان الأساسي: https://vfound.io/api/v1. تُرجع القوائم 25 سجلًا في الصفحة (حتى 100 باستخدام per_page) وتقبل page؛ ويمكن لمعظمها التصفية أيضًا بـ updated_since (ISO 8601) وsearch، كما هو مبيّن أدناه.
مفاتيح الاختبار
المفتاح المنشأ كمفتاح اختبار يبدأ بـ vf_test_ ولا يمكنه حمل سوى queue:read وqueue:write. يعمل على طابور اختبار واحد مسمّى، Test line (sandbox) (الطابور 1، الشباك 1)، ولا يعمل على غيره: عناوين Queue نفسها التي يستخدمها المفتاح الفعلي للطوابير والأوقات والتذاكر و/queue/join واستدعاء التالي والاستدعاء والخدمة وعدم الحضور والإزالة تجيب من طابور الاختبار؛ وكل عنوان آخر يجيب بـ 403 مع code: test_key. لا يقرأ مفتاح الاختبار أبدًا أي طابور أو تذكرة حقيقية ولا يغيّرها، ولا يرسل أي بريد إلكتروني أو رسالة نصية أو تنبيه متصفح أو webhook. يتجاهل مفتاح الاختبار Idempotency-Key: الطلب نفسه المرسل مرتين يُنفَّذ مرتين. تحمل الإجابات "sandbox": true والترويسة X-Vfound-Sandbox: 1. يحتوي طابور الاختبار على ما يصل إلى 100 تذكرة لكل مفتاح، دون عنوان بريد إلكتروني، وتُحذف مع المفتاح وبعد سبعة أيام. استخدم أسماء مختلقة.
إعادة المحاولة بأمان
أرسل الترويسة Idempotency-Key (أي قيمة فريدة حتى 191 حرفًا مرئيًا، مثل UUID) مع طلب POST أو PATCH أو DELETE. إذا انقطع الاتصال وأرسلت الطلب نفسه بالمفتاح نفسه خلال 24 ساعة، لا يكرر vFound التغيير: بل يجيب بالاستجابة الأولى مع الترويسة Idempotent-Replayed: true. يُرفض المفتاح نفسه مع طلب مختلف (422، idempotency_key_reused)؛ والمفتاح الذي ما زال طلبه الأول قيد التنفيذ يجيب بـ 409 (idempotency_in_progress). بعد محو البيانات الشخصية لمن عثر على الغرض أو لمقدّم طلب الاسترداد، تُرجع الاستجابات المخزّنة لتلك المنشأة 410 دون البيانات التي مُحيت؛ حدّث السجل بدلًا من إعادة محاولة الكتابة القديمة بمفتاح جديد. أخطاء الخادم لا تُحفظ، لذلك تؤدي إعادة المحاولة بعد أحدها إلى تنفيذ الطلب من جديد. والإجابة التي تحمل شيئًا يظهر مرة واحدة فقط، مثل السر الموقِّع من POST /webhooks أو رمز اقتران الكشك، لا تُخزَّن أبدًا هي أيضًا: تنفّذ إعادة المحاولة الطلب من جديد، لذا افحص GET /webhooks قبل أن تشترك بالعنوان نفسه مرتين.
التصرف نيابةً عن عضو في الفريق
يمكن لتطبيق يستخدمه فريقك عند مكتب الاستقبال، مثل تطبيق محطة أو مستودع، أن يحدد عضو الفريق الذي يتصرف نيابةً عنه. أرسل X-Acting-User مع البريد الإلكتروني الذي يسجّل به الشخص دخوله أو معرّف المستخدم الخاص به. يجب أن يكون عضوًا نشطًا في منشأة المفتاح في هذه اللحظة. عندها يُنفَّذ الطلب باسمه: يذكر سجل الغرض وسجل طلب الاسترداد ذلك الشخص بدلًا من منشئ المفتاح، ويذكر مسار التدقيق ذلك الشخص والمفتاح والمدير الذي أنشأ المفتاح. لا يستطيعون فعل إلا ما يسمح به كلٌّ من نطاقات المفتاح ودورهم في المنشأة: يقرأ المشاهد فقط، ويستطيع الموظفون أيضًا تغيير الأغراض وطلبات الاسترداد وبلاغات الفقد والطرود وتذاكر Checkroom والمعدات والزيارات وإقامات الفندق، ويستطيع المالكون والمديرون استخدام كل نطاق يملكه المفتاح. الاسم الذي ليس عضوًا نشطًا في المنشأة يُرفض بـ 403 وacting_user_refused، بالرسالة نفسها سواء كان العنوان موجودًا أم لا؛ والنطاق الذي لا يسمح به دور الشخص يُرفض بـ 403 وacting_user_role. تُحفظ إعادة المحاولة الآمنة لكل شخص على حدة، فلا تُعاد أبدًا الإجابة المحفوظة لشخص على شخص آخر. تعمل الترويسة مع مفاتيح المنشأة فقط، لا مع مساعد متصل بتسجيل الدخول، فهو يتصرف أصلًا باسم من ربطه. يتحقق vFound من أن الشخص المذكور عضو نشط؛ ولا يطلب منه تسجيل الدخول، لذا اذكر الأشخاص فقط من تطبيق يسجّل فريقك الدخول إليه. وبدون الترويسة يعمل المفتاح تمامًا كما كان من قبل.
OpenAPI
يوصف كامل الـ API وكل حدث وكل كائن في ملف OpenAPI 3.1: vfound.io/openapi/v1.json. استورده في Postman أو Insomnia أو مولّد الشيفرة الخاص بك. يحافظ اختبار على تطابقه مع الـ API، فلا يذكر أبدًا نقطة نهاية غير موجودة ولا يفوّت نقطة موجودة.
اتصالات الأنظمة التشغيلية الجاهزة
يضبط المالكون والمديرون هذه الاتصالات للقراءة فقط بمزوّدي الخدمة في الإعدادات، الاتصالات، الأنظمة التشغيلية. وهي منفصلة عن REST API العامة: ينشئ العميل بيانات اعتماد المزوّد ويتحكم بها، ويجب أن يجتاز الاتصال اختبارًا قبل التفعيل، والإخفاقات المتكررة توقف ذلك الاتصال وحده، ويبقى العمل اليدوي متاحًا.
| النظام | ما يقرؤه vFound | مجالات vFound |
|---|---|---|
| Cloudbeds | سياق الحجز والغرفة في حدّه الأدنى عبر مفتاح منشأة يتحكم به العميل ومقيّد بـ read:reservation. جزء من vFound Enterprise. | الإقامات الخاصة لـ Lost & Found وParcels |
| OfficeRnD Flex | معرّف العضو واسمه وبريده الإلكتروني وحالته النشطة عبر flex.community.members.read، مع مرشّح اختياري للموقع. | قائمة الأشخاص المشتركة لـ Parcels وEquipment وVisitors |
| Microsoft Entra ID | معرّف المستخدم والاسم المعروض والبريد الإلكتروني والحالة النشطة عبر تحديثات Microsoft Graph delta وUser.Read.All بموافقة المسؤول. | قائمة الأشخاص المشتركة لـ Parcels وEquipment وVisitors |
هذه اتصالات API يضبطها العميل، وليست ادعاءات اعتماد من المزوّدين. اختبار الاتصال وتفعيله ومزامنته جزء من vFound Enterprise. وبوجه خاص، اتصال Entra ليس تطبيقًا في Microsoft Marketplace.
الأغراض
| الطلب | ما يفعله | النطاق |
|---|---|---|
| GET/items | الأغراض، الأحدث تغييرًا أولًا. المرشّحات: status، search (كلمات في العنوان أو الوصف أو العلامة التجارية أو اللون أو الوسوم)، updated_since (ISO 8601)، page، per_page (حتى 100). | items:read |
| GET/items/{id} | غرض واحد بمعرّفه. | items:read |
| GET/categories | أسماء الفئات التي يمكن أن يستخدمها الغرض. | items:read |
| POST/items | أضف غرضًا معثورًا عليه. يُنشر في صفحة ضيوفك، ويشغّل التنبيهات والمطابقة، ويظهر في مسار التدقيق لديك كأنه أُضيف يدويًا. | items:write |
| PATCH/items/{id} | غيّر التفاصيل أو الحالة. | items:write |
| GET/item-transfers | الأغراض المعثور عليها التي أرسلتها هذه المنشأة إلى منشأة أخرى من مجموعة العميل نفسها أو تستلمها منها، والتي في الطريق أولًا. ويسرد أيضًا المنشآت التي يمكنك الإرسال إليها (destinations) وصناديق التخزين في هذه المنشأة (bins). المرشّحات: status (in_transit أو received أو cancelled)، direction (incoming أو outgoing). | items:read |
| POST/item-transfers | أرسل غرضًا ينتظر مالكه إلى منشأة أخرى في المجموعة: item_id وdestination_business_id وnote اختياريًا. للمفاتيح التي ينشئها مالك أو مدير فقط. يغادر الغرض صفحة ضيوف المنشأة المرسِلة (إذا كانت تلك المنشأة تعرض أغراضها المعثور عليها) ولا يمكن تغييره إلى أن يصل. الغرض الذي عليه أي طلب استرداد يبقى مكانه. | items:write |
| POST/item-transfers/{id}/cancel | تستعيد المنشأة المرسِلة الغرض قبل أن يُستلم. | items:write |
| POST/item-transfers/{id}/receive | تؤكد المنشأة المستلِمة وصوله، مع bin_id (مطلوب عندما تكون في المنشأة صناديق تخزين) أو location. يصبح الغرض عندها تابعًا لهذه المنشأة بصوره وسجله وتواريخه، ويُطابَق مع بلاغات الفقد في هذه المنشأة كأنه غرض سُجّل حديثًا. | items:write |
أدوات مكتب Lost & Found وCheckroom
إعدادات البريد الإلكتروني الجديدة تكون معطّلة افتراضيًا. أعداد المسح وفروق الإغلاق للمراجعة فقط. يستخدم P90 المئين 90 بأقرب رتبة لفواصل الطوابع الزمنية الصالحة؛ والعينات الغائبة تُرجع null. تحذّر سعة القطع المادية لكنها لا تمنع تسجيل الاستلام أبدًا. راجع وصف OpenAPI لحقول الطلب. تتطلب قوالب الإعداد والإعدادات مالكًا أو مديرًا.
| الطريقة والمسار | ما يفعله | النطاق |
|---|---|---|
| GET /lost-found/context-schema | اقرأ تعريفات حقول السياق الخاص ذات الإصدارات، دون قيم السجلات. يكفي أي نطاق قراءة من المذكورين. | items:read أو lost_reports:read |
| GET /lost-found/desk-settings | اقرأ إعدادات المكتب الاختيارية. | lost_reports:read |
| PUT /lost-found/desk-settings | استبدل إعدادات المكتب؛ للمالك أو المدير فقط. إعدادات البريد الجديدة تكون معطّلة افتراضيًا. | lost_reports:write |
| GET /checkroom/desk-settings | اقرأ إعدادات المكتب الاختيارية. | checkroom:read |
| PUT /checkroom/desk-settings | استبدل إعدادات المكتب؛ للمالك أو المدير فقط. إعدادات البريد الجديدة تكون معطّلة افتراضيًا. | checkroom:write |
| GET /lost-found/counts | اسرد آخر 30 جلسة جرد بالمسح. | items:read |
| POST /lost-found/counts | التقط لقطة لمعرّفات الأغراض المحتفظ بها لجرد للتقرير فقط؛ دون تغيير في العهدة. | items:write |
| GET /lost-found/counts/{id} | اقرأ جردًا مع أرقام المفقود وغير المتوقع وما لم يعد هنا. | items:read |
| POST /lost-found/counts/{id}/scan | سجّل مسح رمز QR أو ملصق غرض قصير؛ الأغراض المعروفة المكررة تُحتسب مرة واحدة. | items:write |
| POST /lost-found/counts/{id}/finish | أنهِ جردًا دون تغيير الأغراض. | items:write |
| GET /lost-found/queues | اسرد طوابير العمل المحفوظة لمنشئ المفتاح الحالي في هذه المنشأة. | lost_reports:read |
| PUT /lost-found/queues/{id} | استبدل طابورك المحفوظ؛ الأغراض وطلبات الاسترداد الأساسية لا تتغير. | lost_reports:write |
| DELETE /lost-found/queues/{id} | احذف طابورك المحفوظ؛ الأغراض وطلبات الاسترداد الأساسية لا تتغير. | lost_reports:write |
| POST /lost-found/queues | احفظ إعدادًا مسبقًا باسم لطابور عمل لمنشئ المفتاح الحالي. | lost_reports:write |
| GET /lost-found/queues/{id} | اقرأ السجلات الحالية الكامنة وراء طابور محفوظ. تفتح عمليات النقل الواردة عرض النقل الحالي المقيّد بالصلاحيات. | lost_reports:read, items:read, claims:read |
| POST /lost-found/intake-review | أرجع تنبيهات حتمية للاكتمال والخصوصية؛ دون ذكاء اصطناعي ودون تعديلات. | items:read |
| GET /checkroom/templates | اسرد قوالب الإعداد الخاصة بالضبط فقط؛ للمدير فقط. | checkroom:read |
| PUT /checkroom/templates/{id} | استبدل قالب إعداد بصفتك مديرًا؛ الفعاليات والمحطات والتذاكر الأساسية لا تتغير. | checkroom:write |
| DELETE /checkroom/templates/{id} | احذف قالب إعداد بصفتك مديرًا؛ الفعاليات والمحطات والتذاكر الأساسية لا تتغير. | checkroom:write |
| POST /checkroom/templates | احفظ إعداد محطات فعالية دون ضيوف أو تذاكر؛ للمدير فقط. | checkroom:write |
| POST /checkroom/templates/{id}/apply | أنشئ فعالية ومحطات جديدة؛ وأي تعارض في نطاقات الأرقام النشطة يرفض العملية كلها. | checkroom:write |
مركز اتصال Lost & Found والعهدة
يمكن للتكاملات التي يشغّلها بشر إنشاء بلاغ ضيف وتسجيل مراجعة ملكية والبت في طلب استرداد وتسجيل الاستلام الفعلي. يجب اختيار نطاقات الكتابة الجديدة صراحةً؛ والمفاتيح الموجودة لا تحصل عليها تلقائيًا. لا تُعرض أي من عمليات الكتابة هذه المتعلقة بطلبات الاسترداد أو التصرف بالأغراض كأداة MCP أو Ask vFound. تتحمل جهة التكامل لديك مسؤولية تحديد المشغّل البشري وتفويضه: يذكر التدقيق المدير الذي أنشأ المفتاح، وعندما يرسل التكامل X-Acting-User، يذكر أيضًا عضو الفريق الذي سمّاه، والذي لا يصادق عليه vFound.
| الطريقة والمسار | ما يفعله | النطاق |
|---|---|---|
| POST /lost-reports | استقبال مركز الاتصال: first_name وlast_name وemail وtitle وdescription؛ واختياريًا phone وcategory id وcolour_brand وplace_lost وdate_lost وlanguage. يرسل تأكيد الضيف المعتاد والرابط الخاص ويبدأ المراقبة لمدة 90 يومًا. لا تُستنتج الموافقة على التواصل الهاتفي أبدًا. تسري حدود البلاغات المفتوحة الحالية. | lost_reports:write |
| PUT /lost-reports/{id} | عدّل ما فُقد باستخدام البصمة التي يرجعها GET /lost-reports. العنوان والوصف مطلوبان. إغفال الرحلة يحفظ التفاصيل المحفوظة؛ وجمع السياق المعطّل يرفض تغييرات السياق. تغييرات التواصل تتطلب مسار التواصل الموثّق المنفصل. | lost_reports:write |
| GET /lost-reports/{id}/matches | ما يصل إلى 24 مرشحًا حيًا من النص والفئة، لكل منها match.label وreason وsource. أحكام الذكاء الاصطناعي المخزّنة الحديثة تستخدم cached_ai؛ وإلا فاقتراح بالكلمات المفتاحية يوسَم بـ possible. لا استدعاء جديد للنموذج ولا قرار بشأن الملكية. | lost_reports:read و items:read |
| GET /items/{id}/matches | معرّف البلاغ المطابق وعنوانه دون بيانات التواصل بمقدّم البلاغ؛ حتى 24 تطابقًا من أحدث 1,000 بلاغ مفتوح. تسميات المصدر نفسها ودون استدعاء جديد للنموذج. | items:read و lost_reports:read |
| POST /claims/{id}/verification | سجّل verified (قيمة منطقية) وmethod (distinctive_details أو purchase_proof أو staff_review). إقرار بشري، وليس مصادقة آلية على مستند؛ دون نسخة من مستند ودون أدلة بنص حر. يجب أن تنجح أحدث مراجعة قبل القبول عبر API. | claims:write |
| POST /claims/{id}/decision | status: open أو accepted أو rejected أو expired أو ready_for_pickup أو ready_for_shipment أو shipped أو handed_to_courier. تسري آلة الحالات الحالية والموافقة الثانية. تستخدم حقول الشحن اليدوي قواعد مساحة العمل. مع accepted، ينقل return اختياري (pickup أو shipment) طلب الاسترداد إلى تلك المرحلة في الطلب نفسه، مع رسالة بريد إلكتروني واحدة إلى مقدّم الطلب؛ وعندما يحتاج تسليم عالي القيمة إلى موافقته الثانية، يبقى الطلب accepted ويذكر return_notice السبب (الطلب نفسه مرة أخرى لا يغيّر شيئًا). يحدد arranged_by اختياري (site أو owner) من يحجز شركة الشحن أو الإرجاع بالبريد، وتعرضه كل إجابة لطلب استرداد. بدون arranged_by، فإن عنوان التسليم المرسل في shipment (أو الذي يملكه الطلب أصلًا) يعني أن فريقك يرسله بالبريد كما كان؛ وإلا فإن إعداد Lost & Found للمنشأة هو الذي يقرر. owner تعني أن شركة الشحن الخاصة بمقدّم الطلب تستلم الغرض: لا يُطلب عنوان، والعنوان المرسل مع owner يُرفض، وshipped يُرفض. عندما تستلمه شركة الشحن تلك، أرسل handed_to_courier مع اسم الشركة في shipment.carrier ومرجع حجزها في shipment.tracking_number؛ ويُغلق الطلب. لتغيير من يحجزها، انقل الطلب إلى ready_for_pickup ثم إلى ready_for_shipment مع arranged_by. | claims:write |
| POST /claims/{id}/release-approval | يوافق مدير مختلف على تسليم عالي القيمة تم قبوله، وفق الفحوص نفسها المطبّقة في مساحة العمل. | claims:write |
| GET /claims/{id}/custody | سجل المراجعات والمراحل، والموافق، واسم من استلم ووقت الاستلام. signature_recorded قيمة منطقية؛ ولا يُكشف أي صورة توقيع ولا عنوان ملف خاص. | claims:read |
| POST /claims/{id}/handover | سجّل الاستلام الفعلي من ready_for_pickup، مع handover.name وعنوان بيانات PNG في handover.signature عندما يكون التوقيع مطلوبًا. الاستدعاءات المتكررة لطلب مغلق تحفظ الإيصال الأول. | claims:write |
| POST /items/{id}/disposition | kind donated أو disposed، وrecipient للتبرع، وnotes اختيارية. يسري تاريخ الاحتفاظ وفحوص طلبات الاسترداد المعلّقة أو المقبولة. يُرجع إيصال الدفعة المرقّم. | items:write |
استخدم Idempotency-Key عند إعادة محاولات الكتابة. سجل التحقق لا يصادق على مستند هوية ولا يوافق بنفسه على الملكية. إنشاء البلاغ الأولي يتبع مسار عمل الضيف، بما في ذلك الذكاء الاصطناعي المفعّل في المنشأة؛ وطلبات GET لقوائم التطابق تستخدم الأحكام المخزّنة والبحث النصي فقط. هذه عمليات REST/OpenAPI عامة؛ ولم يُعتمد أي تثبيت WSO2 ولا موصّل أصلي.
أضف غرضًا
curl https://vfound.io/api/v1/items -X POST \
-H "Authorization: Bearer $VFOUND_KEY" -H "Content-Type: application/json" \
-d '{"title":"Black leather wallet","category":"Wallets & Purses","found_date":"2026-09-23",
"location":"Front desk","colour":"Black","brand":"Fossil","tags":["leather","cards"],
"photo":"data:image/jpeg;base64,…","photo_public":true}'
الحقول: title وcategory مطلوبان. اختيارية: found_date وfound_time (HH:MM) وkeep_until وlocation وdescription وcolour وbrand وtags وvalue_band (unknown أو low أو medium أو high) وnotes (للموظفين فقط) وphoto (عنوان بيانات base64 حتى 8 MB) وphoto_public. الصور المرسلة عبر API لا يفحصها حارس الخصوصية في vFound AI، لذا اضبط photo_public على false لأي صورة تُظهر بيانات شخصية.
كائن الغرض
{"id":"9b2f…","title":"Black leather wallet","status":"in_care","category":"Wallets & Purses",
"found_date":"2026-09-23","found_time":"14:30","keep_until":"2026-10-21","location":"Front desk",
"description":null,"colour":"Black","brand":"Fossil","tags":["leather","cards"],"value_band":"low",
"photo_public":true,"photo_url":"https://vfound.io/uploads/…","transfer":null,"created_at":"…","updated_at":"…"}
الحالة واحدة من in_care أو in_transit (في الطريق إلى منشأة أخرى؛ ويسمّي transfer عندها المنشأتين) أو claimed أو expired أو donated أو disposed أو trash. يمكن لـ PATCH ضبط in_care أو expired أو donated أو disposed أو trash؛ وتتم إعادة الأغراض إلى الضيوف عبر طلبات الاسترداد.
طلبات الاسترداد
| الطلب | ما يفعله | النطاق |
|---|---|---|
| GET/claims | طلبات الاسترداد، الأحدث تغييرًا أولًا. المرشّحات: status وupdated_since وpage وper_page. | claims:read |
| GET/claims/{id} | طلب استرداد واحد بمرجعه. | claims:read |
{"id":"k3f9x2a1b7c4d8e6","status":"ready_for_pickup","item":{"id":"9b2f…","title":"Black leather wallet"},
"claimant":{"first_name":"Ana","last_name":"Ruiz","email":"ana@example.com","phone":null},
"description":"…","place_lost":"Bar","date_lost":"2026-09-22","language":"es","arranged_by":null,"created_at":"…","updated_at":"…"}
حالة طلب الاسترداد: unread أو open أو accepted أو awaiting_information أو ready_for_pickup أو ready_for_shipment أو shipped أو closed أو rejected أو expired (مقبول لكن لم يُستلم أبدًا). يحدد arranged_by من يحجز شركة الشحن أو الإرجاع بالبريد: venue (فريقك يرسله بالبريد) أو owner (شركة الشحن الخاصة بمقدّم الطلب تستلمه)؛ وتكون null عندما لا يكون لطلب الاسترداد إرجاع من هذا النوع. بيانات مقدّمي الطلبات بيانات شخصية: احتفظ بها فقط للمدة التي تحتاجها.
بلاغات الفقد
GET/lost-reports يسرد ما أبلغ الضيوف عن فقده، مع status (open أو closed) وبيانات التواصل بمقدّم البلاغ واللغة التي استخدمها وأي رابط Find My شاركه. النطاق: lost_reports:read.
التحليلات
GET/analytics?days=30 يرجع الملخص نفسه الموجود في التقارير: الأغراض المسجّلة والمُعادة، ومعدل الإرجاع، ووسيط الأيام حتى الإرجاع، وأين انتهت الأغراض، والفئات، والبؤر، وأكثر الأيام ازدحامًا، وإنتاج الفريق، والاتجاه، وآراء الضيوف. days هي 7 أو 30 أو 90 أو 365. النطاق: analytics:read.
إقامات الفندق
سياق الإقامة خاص بالمنشأة وبالحد الأدنى عمدًا. يحتوي على مرجع إقامة ثابت، ومرجع ضيف اختياري، واسم الضيف، والوصول والمغادرة، والمنطقة الزمنية للمصدر، والغرفة الحالية، والحالة، وطوابع المصدر الزمنية. ولا يحتوي أبدًا على أسعار أو بيانات دفع أو بيانات ولاء أو وثائق هوية أو تفضيلات أو ملاحظات حجز غير ذات صلة.
| الطلب | ما يفعله | النطاق |
|---|---|---|
| GET/stays | اسرد الإقامات. المرشّحات: search (الضيف أو المرجع الثابت أو الغرفة الحالية)، state وsource وpage وper_page. تطابق الغرفة يساعد في التنقل فقط؛ ولا يوحي أبدًا بالملكية. | stays:read |
| GET/stays/{stay} | إقامة واحدة وسجل مصدرها وتصحيحها القابل للتدقيق. | stays:read |
| POST/stays | أنشئ سجل مصدر API الذي يحدده external_stay_ref أو حدّثه. أرسل source_updated_at؛ والأحداث المتأخرة أو المعاد إرسالها التي ليست أحدث من الحدث المحفوظ تُقرّ دون استبدال بيانات أحدث. | stays:write |
curl https://vfound.io/api/v1/stays -X POST \
-H "Authorization: Bearer $VFOUND_KEY" -H "Idempotency-Key: pms-event-901" \
-H "Content-Type: application/json" \
-d '{"external_stay_ref":"BOOK-100","guest_name":"Avery Chen","current_room":"412",
"stay_state":"in_house","source_timezone":"America/New_York","source_updated_at":"2026-10-03T12:00:00Z"}'
تقبل الأغراض والطرود stay_id وroom_at_event اختياريين. إذا حُذفت الغرفة وقت الحدث، يلتقط vFound لقطة للغرفة الحالية للإقامة. لا تتغير تلك اللقطة بعد نقل الغرفة؛ ويعرض السجل أيضًا الغرفة الحالية، فيرى المكتب الاثنتين.
Parcels
| الطلب | ما يفعله | النطاق |
|---|---|---|
| GET/parcels | الطرود، الأحدث تغييرًا أولًا. المرشّحات: status (waiting أو collected أو returned)، search (المستلم أو الوحدة أو رقم التتبع أو المرسل أو رمز الاستلام)، updated_since. | parcels:read |
| GET/parcels/{id} | طرد واحد. | parcels:read |
| POST/parcels | سجّل طردًا لـ recipient_email (يُطابَق مع قائمة الأشخاص لديك) أو recipient_name، مع unit وcarrier وtracking وsender وshelf اختيارية. يتلقى الشخص رمز استلامه بريدًا إلكترونيًا ما لم تكن notify قيمتها false. | parcels:write |
| POST/parcels/{id}/collect | سلّمه: collected_by (مطلوب) وsignature اختياري (عنوان بيانات PNG). | parcels:write |
| POST/parcels/{id}/return | أعده إلى المرسل، مع note اختيارية. | parcels:write |
| POST/parcels/{id}/remind | أرسل إلى المستلم بريدًا إلكترونيًا بتذكير باستلامه. | parcels:write |
| POST/parcels/tracking | طبّع رقم تتبع واكتشف UPS أو FedEx أو USPS أو DHL أو Amazon أو ناقلًا دوليًا بنظام S10. يُقبل SSCC صالح من GS1 كتتبع للشحنة؛ ويُتعرَّف على معرّف منتج GS1 لكنه لا يُعامل أبدًا كرقم طرد. | parcels:read |
| GET/parcels/pickup-queue | الأشخاص الذين قالوا إنهم عند المكتب، مع عدد طرودهم وأرففهم. | parcels:read |
| POST/parcels/pickup-queue/{id}/serve | حدّد وصول شخص واحد إلى المكتب كمخدوم. | parcels:write |
| POST/parcels/bulk-remind | أرسل تذكيرات بالبريد الإلكتروني لما يصل إلى 200 طرد منتظر محدد. | parcels:write |
| POST/parcels/bulk-return | أعد ما يصل إلى 200 طرد منتظر محدد إلى المرسل. | parcels:write |
| GET/parcels/shelves | سعات أرفف الطرود والإشغال الحالي. | parcels:read |
| POST/parcels/shelves | أنشئ رفًا أو غيّر سعته. | parcels:write |
| GET/parcels/analytics | الحجم، وتوزيع شركات الشحن، ووقت الاستلام، ونسبة غير المستلم، وأكثر الأرفف ازدحامًا. | parcels:read |
| GET/parcels/outgoing | الطرود الصادرة الجاهزة لشركة شحن أو المسلَّمة. | parcels:read |
| POST/parcels/outgoing | سجّل طردًا صادرًا. | parcels:write |
| POST/parcels/outgoing/{id}/handoff | سجّل شركة الشحن والتوقيع عند التسليم. | parcels:write |
| GET/parcels/rounds | جولات التوزيع ومحطاتها. | parcels:read |
| POST/parcels/rounds | أنشئ جولة في حرم جامعي أو مكتب من الطرود المنتظرة. | parcels:write |
| POST/parcels/rounds/{round}/stops/{stop}/deliver | أكمل محطة باسم المستلم وتوقيعه. | parcels:write |
| GET/parcels/couriers | سعاة الشحن المسجَّلون عبر Visitors، مع status in أو out. | parcels:read |
{"id":412,"status":"waiting","recipient":{"name":"Ana Ruiz","email":"ana@example.com","unit":"Room 214","reference":"S1044"},
"carrier":"UPS","tracking":"1Z999AA10123456784","sender":null,"size":"small","shelf":"B2","pickup_code":"KQHRER",
"notified_at":"…","collected_at":null,"collected_by":null,"returned_at":null,"created_at":"…","updated_at":"…"}
رمز الاستلام يظهر فقط ما دام الطرد منتظرًا. بيانات المستلمين بيانات شخصية: احتفظ بها فقط للمدة التي تحتاجها.
Checkroom
| الطلب | ما يفعله | النطاق |
|---|---|---|
| GET/checkroom/tickets | التذاكر، الأحدث تغييرًا أولًا، مع status (pending أو in أو returned أو left أو moved)، والرقم، وما سُلّم، وpiece_records الموسومة فرديًا، وبيانات الضيف إن وُجدت، والرسم المسجّل عند المكتب، والأوقات. المرشّحات: status وsearch (الضيف أو الغرفة أو رقم التذكرة أو وسم القطعة أو رمز التذكرة) وupdated_since. | checkroom:read |
| GET/checkroom/tickets/{id} | تذكرة واحدة. | checkroom:read |
| POST/checkroom/tickets | سجّل استلام شيء واحصل على الرقم الحر التالي: kind (coat أو bag أو luggage أو other، مطلوب)، pieces، وpiece_details اختياري بنوع واحد وموقع تخزين لكل قطعة، وguest_name وguest_email وguest_room وcollect_by للأمتعة وnotes وfee_method (cash أو card) وstation_id وevent_id وstorage_location وlanguage وphoto. تحمل الإجابة أيضًا guest_ticket (الرمز وعنوان التذكرة الخاص) مرة واحدة، لعرضه كرمز QR أو طباعته للضيف؛ ولا تتضمنه القراءات والقوائم والـ webhooks أبدًا. | checkroom:write |
| POST/checkroom/tickets/{id}/hand-back | سلّمه بعد أن يقرأ نظامك تذكرة الضيف، مع collected_by وsignature اختياريين. أرسل piece_ids لإرجاع قطع محددة وترك الباقي مفتوحًا؛ واحذفه لإرجاع كل قطعة مفتوحة. without_ticket يسجّل أن الضيف فقد تذكرته ثم يحتاج إلى collected_by وsignature. | checkroom:write |
| GET/checkroom/stations | اسرد محطات Checkroom في المنشأة ونطاقات أرقامها ومواقع التخزين. | checkroom:read |
| POST/checkroom/stations | أنشئ محطة بنطاق أرقام غير متداخل. | checkroom:write |
| PUT/checkroom/stations/{id} | غيّر محطة أو نطاق أرقامها أو مواقع التخزين أو حالتها النشطة. | checkroom:write |
| GET/checkroom/events | اسرد الفعاليات الأخيرة والقادمة في Checkroom. | checkroom:read |
| POST/checkroom/events | أنشئ فعالية بحجمها المتوقع ومحطاتها. | checkroom:write |
| PUT/checkroom/events/{id} | غيّر أوقات فعالية أو توقعها أو محطاتها. | checkroom:write |
| GET/checkroom/exit-queue | التذاكر التي طلب ضيوفها من المكتب تجهيز أغراضهم. | checkroom:read |
| POST/checkroom/tickets/{id}/ready | حدّد تذكرة منتظرة على أنها جاهزة وأبلغ الضيف. | checkroom:write |
| GET/checkroom/report | حجم التذاكر، وساعات الذروة، ووقت الإرجاع، والرسوم حسب الطريقة والموظف. | checkroom:read |
| GET/checkroom/export | نزّل صفوف تقرير Checkroom بصيغة CSV آمنة من الصيغ. | checkroom:read |
Queue
طوابير الانتظار والأشخاص المنتظرون فيها والشبابيك التي يُستدعون إليها. كل تغيير يمر بالخطوات نفسها كما عند المكتب، وبالسجل نفسه، باسم منشئ المفتاح أو عضو الفريق المذكور في X-Acting-User. لا تحمل التذكرة أبدًا بريد الضيف الإلكتروني ولا إجاباته عن أسئلة الطابور.
| الطلب | ما يفعله | النطاق |
|---|---|---|
| GET/queue/lines | الطوابير بحالتها الآن والأشخاص المنتظرين والانتظار المقدّر لمن ينضم الآن. | queue:read |
| GET/queue/lines/{id} | طابور واحد. | queue:read |
| GET/queue/tickets | تذاكر يوم واحد في المنشأة (day، اليوم افتراضيًا)، بترتيب الاستدعاء؛ ويمكن التصفية حسب line وstatus. | queue:read |
| GET/queue/tickets/{id} | تذكرة واحدة. | queue:read |
| GET/queue/report | التذاكر، والأشخاص الذين خُدموا، وعدم الحضور، والذين غادروا، ووسيط دقائق الانتظار والخدمة خلال آخر days. | queue:read |
| POST/queue/tickets | أضف شخصًا إلى طابور، كما يفعل المكتب. | queue:write |
| POST/queue/call-next | استدعِ الشخص التالي إلى شباك (counter_id). لا يحصل موظفان يستدعيان في الوقت نفسه على الشخص نفسه أبدًا؛ وdata تكون null عندما لا ينتظر أحد. | queue:write |
| POST/queue/tickets/{id}/call | استدعِ شخصًا مختارًا إلى شباك. | queue:write |
| POST/queue/tickets/{id}/served | حدّد الشخص عند الشباك على أنه خُدم. | queue:write |
| POST/queue/tickets/{id}/no-show | حدّد شخصًا استُدعي ولم يحضر على أنه لم يحضر. | queue:write |
| POST/queue/tickets/{id}/remove | أخرج شخصًا من الطابور. | queue:write |
| GET/queue/bookings | الأوقات المحجوزة، الأبكر أولًا، مع from وto وline وstatus والترقيم بين الصفحات. ولا تتضمن أبدًا بريد الشخص الإلكتروني. | queue:read |
| POST/queue/bookings | احجز أحد الأوقات الحرة في صفحة الأوقات المحجوزة لطابور ما لشخص (line_id وstarts_at وemail). | queue:write |
| POST/queue/bookings/{id}/cancel | ألغِ وقتًا محجوزًا؛ ويتلقى الشخص بريدًا إلكترونيًا بأن الفريق ألغاه. | queue:write |
| POST/queue/bookings/{id}/arrived | سجّل وصول شخص لديه حجز؛ وتُوضع تذكرته بحسب الوقت المحجوز. | queue:write |
| POST/queue/tickets/{id}/arrived | حدّد شخصًا انضم قبل وصوله على أنه وصل. | queue:write |
| GET/queue/tickets/{id}/messages | الرسائل بين شخص في الطابور والفريق، الأقدم أولًا. القراءة تجعل رسائل الشخص مقروءة. | queue:read |
| POST/queue/tickets/{id}/messages | اكتب إلى شخص في الطابور (body، من 1 إلى 500 حرف)، باسم عضو الفريق صاحب المفتاح. | queue:write |
| GET/queue/survey | أرقام الاستبيان بعد الخدمة: الإجابات والمتوسط وكل تقييم، حسب الطابور والخدمة والشباك وعضو الفريق (يظهر متوسط عضو الفريق ابتداءً من 5 إجابات). ولا تتضمن التعليقات أبدًا. | queue:read |
| GET/queue/performance | أرقام بسيطة لكل عضو في الفريق عن الأيام نفسها التي يغطيها التقرير. دون درجة ودون ترتيب. | queue:read |
| GET/queue/lines/{id}/slots | الأوقات المحجوزة المتاحة لطابور ما، كما تعرضها صفحة الحجز الخاصة به. | queue:read |
| POST/queue/join | خذ رقمًا لضيف من موقعك الخاص، وفق قواعد الضيوف (طابور مفتوح، وحدود، وإجابات مطلوبة، ومربعات موافقة). أرسله من خادمك: المفتاح يحل محل اختبار captcha. | queue:write |
| GET/queue/tickets/lookup | ابحث عن التذاكر بالرقم الذي يحمله الضيف. | queue:read |
| GET/queue/tickets/{id}/status | ما تعرضه صفحة تذكرة الضيف نفسه: الدور والتقدير والجملة. | queue:read |
| GET/queue/tickets/{id}/history | خطوات تذكرة واحدة. ومن قام بكل خطوة هو team أو guest أو api (انضمام عبر مفتاح) أو system (تم تلقائيًا، مثل عدم الحضور التلقائي)، ولا يكون اسمًا أبدًا. | queue:read |
| GET/queue/customers/history | زيارات من طلب أن يُتذكَّر، يُعثر عليه بالبريد الإلكتروني، ما دام التعرّف مفعّلًا في المنشأة. ويخبر صاحب المفتاح ما إذا كان عنوان بريد إلكتروني يعود إلى زائر متذكَّر. | queue:read |
| GET/queue/insights | أعداد للأيام نفسها التي يغطيها التقرير: من غادر قبل أن يُستدعى، والأشخاص أصحاب الحجز والحاضرون دون موعد، ونسبة من استُدعي ضمن هدف الانتظار حسب الطابور والأسبوع، وساعات الازدحام من الأسابيع السابقة. أعداد فقط؛ ولا اسم ولا إجابة أبدًا. | queue:read |
| GET/queue/report-data | تذاكر Queue كما يقرؤها منشئ التقارير (fields[] وlimit حتى 1000 وoffset)، لأدوات BI. ولا يُدرج اسم الضيف أبدًا. | queue:read |
Equipment
| الطلب | ما يفعله | النطاق |
|---|---|---|
| GET/loans | المعدات المصروفة، الأحدث تغييرًا أولًا، مع status (out أو returned أو lost)، وهل هي overdue، والغرض، ومستلم المعدات، والأوقات. المرشّحات: status (out أو returned أو lost أو overdue) وsearch (اسم مستلم المعدات أو بريده الإلكتروني أو المرجع) وupdated_since. | loans:read |
| GET/loans/{id} | عملية صرف واحدة. | loans:read |
| POST/loans | اصرف شيئًا: item_id أو item_code (الرمز على ملصقه، أو الرابط الذي يحمله رمز QR الخاص به)، وborrower_name (مطلوب)، وperson_id اختياري لربط قائمة الأشخاص، وborrower_email لإيصال، وborrower_reference وdue_at وnote وlanguage وsignature. | loans:write |
| POST/loans/{id}/extend | امنح وقتًا أطول: due_at جديد. ويتلقى مستلم المعدات الوقت الجديد بريدًا إلكترونيًا. | loans:write |
| POST/loans/{id}/return | استلمه عائدًا، مع condition اختيارية (good أو damaged أو incomplete) وnote وset_aside لوضع الغرض جانبًا للإصلاح. | loans:write |
| POST/loans/returns | استلم عدة أشياء عائدة معًا: loan_ids (من 1 إلى 50)، مع condition وnote وset_aside الاختيارية نفسها للجميع. الكل أو لا شيء: إذا كان أحدها قد أُعيد أصلًا أو لم يُعثر عليه، فلا يتغير شيء. يتلقى مستلم المعدات الذي لديه عنوان بريد إلكتروني إيصالًا واحدًا لكل عملية صرف، يسرد كل ما عاد، وترسل كل عملية حدثها الخاص loan.returned. | loans:write |
| GET/loans/items | كل ما يصرفه المكتب، بالاسم. المرشّحات: status (available أو out أو repair أو retired) وsearch (الاسم أو وسم الأصل أو رمز الملصق) وupdated_since. | loans:read |
| GET/loans/items/{id} | غرض واحد، مع الرابط الذي يحمله رمز QR الخاص بملصقه. | loans:read |
| GET/loans/items/{id}/tickets | التذاكر المرسلة إلى Jira أو Zendesk أو ServiceNow الخاص بالمنشأة لهذا الغرض (تجريبي)، مع آخر حالة قُرئت. | loans:read |
| POST/loans/items | أضف معدات: name (مطلوب) وcategory وtag وlocation وnotes وloan_hours (كم ساعة تُصرف عادةً)، وphoto وproduct وvariant (يمكن حجز وحدات المنتج والنسخة الواحدة كوحدة واحدة)، وcopies لإضافة ما يصل إلى 50 غرضًا مطابقًا، مرقّمة. | loans:write |
| PATCH/loans/items/{id} | غيّر تفاصيله، أو اضبط status على available أو repair أو retired. product وvariant يغيّران عائلة منتجه؛ وcleaning_status needs_cleaning يحدده على أنه ينتظر التنظيف وnull يحدده على أنه نُظّف. تُظهر الأغراض product وvariant وcleaning_status وcleaning_since. | loans:write |
| GET/loans/items/{id}/tag | هل وسم NFC أو RFID مرتبط، وآخر أربعة أرقام سداسية عشرية من رقمه التسلسلي. | loans:read |
| PUT/loans/items/{id}/tag | اربط وسمًا برقمه التسلسلي، كما يقرؤه هاتف أو كما يكتبه قارئ بنمط لوحة المفاتيح (سداسي عشري أو سداسي عشري معكوس أو عشري)؛ ويحل محل أي وسم كان للغرض. | loans:write |
| DELETE/loans/items/{id}/tag | أزل وسم الغرض. | loans:write |
| POST/loans/checkouts | اصرف من غرض واحد إلى 50 غرضًا في عملية صرف واحدة ذرية، أو اصرف مجموعة معدات محفوظة. تقبل شخصًا وموعد إعادة وملاحظة وتوقيعًا اختياريًا، وبنود مخزون (stock) تُصرف على الإيصال نفسه وتُسرد في stock. تضبط custom_values سمات المنشأة المخصصة لعملية الصرف. | loans:write |
| GET/loans/kits | مجموعات معدات محفوظة تُصرف عادةً معًا. | loans:read |
| POST/loans/kits | احفظ مجموعة معدات من جزأين على الأقل في المجموع: item_ids مسمّاة وlines (عدد من فئة) وchild_kit_ids (مجموعات داخلها، حتى ثلاثة مستويات)، وstock_lines (مخزون معدود يُصرف معها، ولا يُحجز أبدًا لحجز)، واختياريًا locked بحيث لا تُصرف أغراضها المسمّاة إلا معًا. | loans:write |
| PUT/loans/kits/{id} | غيّر مجموعة معدات محفوظة وأغراضها. | loans:write |
| GET/loans/trainings | التدريبات التي قد تشترطها فئة أو غرض قبل أن يستلمه شخص (تُضبط في Equipment، السياسات، التدريب). | loans:read |
| GET/loans/trainings/{id}/holders | من يحمل تدريبًا، ومن أي تاريخ وحتى أي تاريخ، وهل انتهت صلاحيته. | loans:read |
| POST/loans/trainings/{id}/holders | امنح شخصًا من قائمة الأشخاص تدريبًا، أو جدّده، مع مستند إثبات اختياري. | loans:write |
| DELETE/loans/trainings/{id}/holders/{person} | اسحب تدريبًا من شخص، مع مستند إثباته. | loans:write |
| GET/loans/borrower-types | أنواع مستلمي المعدات: حدّ الأغراض لكل نوع والمدة المعتادة والفئات التي يراها أفراده ويستلمونها (تُضبط في Equipment، السياسات). الحد أو المدة الفارغان يعنيان أن ما لدى المنشأة هو المطبّق. | loans:read |
| GET/loans/borrower-types/{id}/members | من لديه نوع من أنواع مستلمي المعدات. | loans:read |
| POST/loans/borrower-types/{id}/members | امنح أشخاصًا من قائمة الأشخاص نوعًا من أنواع مستلمي المعدات (حتى 500 دفعة واحدة). | loans:write |
| PUT/loans/borrower-types/{id}/members/{person} | غيّر عضوية شخص في نوع من أنواع مستلمي المعدات: يوم بدايتها ويوم نهايتها (بعده يظل يرى ما يعرضه النوع لكنه لا يستطيع حجزه أو استلامه) وملاحظة عن المكان الذي أُخذ فيه رسم. لا يأخذ vFound أي دفعة. | loans:write |
| DELETE/loans/borrower-types/{id}/members/{person} | اسحب نوعًا من أنواع مستلمي المعدات من شخص. | loans:write |
| GET/loans/credits | أرصدة الحجز الممنوحة مؤخرًا، ورصيد شخص واحد. الأرصدة عدد تستهلكه الحجوزات، وليست مالًا أبدًا. | loans:read |
| POST/loans/credits | امنح شخصًا أرصدة حجز، أو استرد بعضها برقم سالب (للمالكين والمديرين). | loans:write |
| GET/loans/holds | الإيقافات النشطة على الاستلام: ما دام أحدها قائمًا، لا يُصرف للشخص شيء ولا يستطيع الحجز. | loans:read |
| POST/loans/holds | علّق استلام شخص، مع سبب اختياري (يُحفظ للفريق ولا يظهر أبدًا في البريد الإلكتروني) ووقت انتهاء وبريد إلكتروني للشخص. | loans:write |
| POST/loans/holds/{id}/lift | ارفع تعليقًا. | loans:write |
| GET/loans/spaces | الغرف والمكاتب ومواقف السيارات وأماكن أخرى تحجزها المنشأة لوقت محدد، مع إمكانية التصفية بـ type. كل منها غرض من النوع space، ولا يُصرف أبدًا. | loans:read |
| POST/loans/spaces | أضف غرفة أو مساحة مع نوعها وعدد من تتسع لهم وموقعها. | loans:write |
| PUT/loans/spaces/{id} | غيّر غرفة أو مساحة. | loans:write |
| GET/loans/spaces/availability | كل غرفة أو مساحة مع حجوزاتها المفتوحة بين from وto (حتى 31 يومًا)، مع اسم من يستلمها وعدد من سيحضر وأي تعليمات تجهيز. | loans:read |
| POST/loans/spaces/{id}/book | احجز غرفة أو مساحة لشخص ووقت، وحدها أو مع معدات (الكل أو لا شيء)، مع تعليمات تجهيز للفريق. | loans:write |
| POST/loans/reservation-groups/{id}/parts | أضف غرضًا واحدًا، أو غرضًا من فئة، إلى حجز مجموعة معدات أو سلة، ويُفحص كحجز جديد. يُرفض لمجموعة مقفلة. جزء من فئة يغطيها نموذج المخاطر في المنشأة يحتاج risk_answers، ويبقى تقييم الحجز بانتظار مراجعة جديدة. | loans:write |
| POST/loans/reservations/{id}/remove-part | أخرج جزءًا واحدًا من حجز مجموعة معدات أو سلة؛ ويُلغى الجزء الأخير مع الحجز. | loans:write |
| GET/loans/places | الأماكن المتداخلة الخاصة بالمنشأة: المباني والغرف والأرفف ومواقع العمل والشاحنات. يحدد place_id الخاص بالغرض مكانه ويملأ location وsub_location الخاصين به. | loans:read |
| GET/loans/category-tree | فئات المعدات مجمّعة في شجرة، الأصل أولًا. تظل القواعد والحجوزات سارية على فئة الغرض نفسه. | loans:read |
| GET/loans/asset-models | النماذج التي تُنشأ منها الأغراض الجديدة. أرسل asset_model_id على POST /loans/items لملء كل تفصيل تُرك فارغًا. | loans:read |
| GET/loans/items/{id}/links | روابط غرض بأغراض أخرى من المنشأة نفسها: يعمل مع، بديل، يحل محل. | loans:read |
| POST/loans/items/{id}/links | اربط غرضًا بآخر من المنشأة نفسها، مع ملاحظة. | loans:write |
| DELETE/loans/items/{id}/links/{link} | أزل رابطًا من الغرضين معًا. | loans:write |
| POST/loans/kits/{id}/move | انقل مجموعة معدات إلى مكان في المنشأة: كل غرض مسمّى فيها، وفي المجموعات داخلها، يذهب إليه دفعة واحدة (للمالكين والمديرين). | loans:write |
| GET/loans/items/{id}/meter-readings | قراءات العدّاد المدخلة يدويًا لغرض، الأحدث أولًا. | loans:read |
| POST/loans/items/{id}/meter-readings | سجّل قراءة عدّاد. جدول الصيانة الذي فيه every_meter يستحق متى قطع العدّاد تلك المسافة؛ والقراءات لا ترتفع إلا إلى أعلى. | loans:write |
| GET/loans/contracts | عقود الموردين مربوطة بالأغراض التي تغطيها (للمالكين والمديرين). | loans:read |
| GET/loans/resale | الأغراض المعروضة للبيع مع سعرها المطلوب وقيمتها الدفترية (للمالكين والمديرين). قائمة فقط: لا يُعلَن عن شيء ولا يُباع. | loans:read |
| GET/loans/points | نقاط الاستلام والإعادة التي يمكن أن يسمّيها الحجز. | loans:read |
| POST/loans/points | أضف نقطة (للمالكين والمديرين). يسمّي الحجز نقطة للاستلام منها ونقطة للإعادة إليها بـ pickup_point_id وdropoff_point_id. | loans:write |
| PUT/loans/points/{id} | غيّر نقطة أو أوقفها. | loans:write |
| GET/loans/projects | المشاريع التي يمكن أن ينتمي إليها حجز. لا يُستلم شيء لمشروع قبل الموافقة عليه. | loans:read |
| POST/loans/projects | أضف مشروعًا (بانتظار الموافقة). | loans:write |
| POST/loans/projects/{id}/decision | وافق على مشروع أو ارفضه (للمالكين والمديرين). | loans:write |
| GET/loans/risk-assessments | تقييمات المخاطر التي تنتظر مراجعة (أو حسب status)، مع إجابات من يستلم. | loans:read |
| POST/loans/risk-assessments/{id}/review | وافق على تقييم مخاطر أو ارفضه (للمالكين والمديرين). الرفض يلغي الحجز. | loans:write |
| POST/loans/reservation-series | احجز غرضًا واحدًا أو فئة واحدة أو غرفة أو مساحة واحدة كل يوم أو أسبوع (repeat: frequency وevery وweekdays وcount أو until وskip_conflicts). يتبع كل موعد قواعد الحجز ويحتسب المواعيد التي قبله؛ ولا يُحجز شيء إذا كان أحدها محجوزًا ما لم يكن skip_conflicts مفعّلًا. 52 موعدًا على الأكثر، خلال سنة. | loans:write |
| POST/loans/reservations/{id}/move | انقل حجزًا، مع كل جزء من حجز مجموعة معدات أو سلة محجوزة معًا، إلى أوقات جديدة أو غرض آخر من الفئة نفسها. يُفحص من جديد كحجز جديد؛ الكل أو لا شيء. | loans:write |
| GET/loans/waitlist | الأشخاص المنتظرون وقتًا حُجز، حسب status (waiting افتراضيًا). | loans:read |
| POST/loans/waitlist | أضف شخصًا إلى قائمة الانتظار لغرض أو فئة أو مساحة ووقت. وعندما يتحرر الوقت، يُحجز لأول شخص يناسبه الوقت الآن ويتلقى بريدًا إلكترونيًا. | loans:write |
| POST/loans/waitlist/{id}/cancel | أزل شخصًا من قائمة الانتظار. | loans:write |
| GET/loans/fees | سجل الرسوم، الأحدث أولًا (صفِّ بـ party_key أو kind أو status أو billing_code أو from أو to)، مع إعدادات الرسوم في المنشأة وكل من عليه مبلغ أو لديه وديعة محتجزة. المبالغ أعداد صحيحة بأصغر وحدة للعملة. يسجّل vFound الرسوم؛ ولا يعالج أي دفعة أبدًا. | loans:read |
| GET/loans/fees/party | مستلم معدات واحد (person_id أو party_key): ما عليه لكل عملة، والودائع المحتجزة، والإدخالات والفواتير. | loans:read |
| GET/loans/fees/billing-codes | المحمَّل والمعفى عنه والمسدَّد والمتبقي لكل رمز فوترة وعملة عن فترة؛ وformat=csv للحصول على ملف CSV. | loans:read |
| POST/loans/fees/charges | سجّل رسم ضرر أو استبدال أو رسمًا آخر، أو رسمًا مسعّرًا بـ fee_template_id. تسري ضريبة المنشأة ما لم تكن taxable قيمتها false. | loans:write |
| POST/loans/fees/payments | سجّل مالًا أخذته المنشأة بنفسها (نقدًا، أو بجهاز بطاقات خاص بها، أو بتحويل). يسدّد الرسوم المفتوحة، الأقدم أولًا. | loans:write |
| POST/loans/fees/deposits | سجّل وديعة أخذتها المنشأة؛ تُحتجز إلى أن تُردّ أو تُستبقى. | loans:write |
| POST/loans/fees/deposits/{id}/return | ردّ وديعة محتجزة. | loans:write |
| POST/loans/fees/deposits/{id}/keep | استبقِ وديعة محتجزة أو جزءًا منها (للمالكين والمديرين، مع سبب)؛ ويُحتسب الجزء المستبقى دفعة. | loans:write |
| POST/loans/fees/{id}/waive | أعفِ مما لا يزال الرسم يحتاجه (للمالكين والمديرين، مع سبب). | loans:write |
| POST/loans/fees/{id}/void | أبطل دفعة سُجّلت بالخطأ (للمالكين والمديرين، مع سبب). وإبطال الدفعة التي أنشأتها وديعة مستبقاة يعيد احتجاز ذلك المبلغ كوديعة. | loans:write |
| GET/loans/{id}/fees | ما يُعرض على المكتب عن عملية صرف عادت: غرامة التأخير التي لم تُسجَّل بعد، وقيمة الاستبدال عند الفقد أو التلف، والودائع المحتجزة. | loans:read |
| POST/loans/{id}/late-fine | أضف غرامة التأخير لعملية صرف عادت متأخرة، محسوبة من وقت عودتها. مرة واحدة لكل عملية. | loans:write |
| GET/loans/invoices | الفواتير، الأحدث رقمًا أولًا. | loans:read |
| POST/loans/invoices | أصدر فاتورة مرقّمة للرسوم المفتوحة على مستلم معدات بعملة واحدة. | loans:write |
| POST/loans/invoices/{id}/void | أبطل فاتورة (للمالكين والمديرين، مع سبب)؛ وreissue ينقل رسومها المفتوحة إلى فاتورة جديدة تحل محلها. | loans:write |
| GET/loans/reservations | الحجوزات حسب وقت البدء، مع إمكانية التصفية بـ status أو from. | loans:read |
| POST/loans/reservations | احجز غرضًا محددًا أو غرضًا واحدًا من فئة لشخص وفترة زمنية. تضبط custom_values سمات المنشأة المخصصة للحجز. | loans:write |
| POST/loans/reservations/{id}/approve | وافق على حجز ينتظر المراجعة. عندما تكون في المنشأة خطوات موافقة، يوقّع المفتاح خطوة فقط عن عضو الفريق الذي يسمّيه في X-Acting-User، ولا يوقّع اتصال المساعد أي خطوة أبدًا، ولا يوقّع أحد خطوة في حجز أجراه هو (approval_not_yours). والحجز فوق تعارض يتبع القاعدة نفسها. | loans:write |
| POST/loans/reservations/{id}/cancel | ألغِ حجزًا معلّقًا أو موافقًا عليه أو جاهزًا. | loans:write |
| POST/loans/reservations/{id}/pickup | سلّم الغرض المحجوز بصورة ذرية وأغلق الحجز كمستلَم. | loans:write |
| POST/loans/reservation-groups | احجز مجموعة معدات (kit_id) أو سلة (items: غرض، أو فئة وكمية، في كل بند) لشخص واحد وفترة زمنية: كل جزء أو لا شيء. الموافقة على أي جزء أو إلغاؤه أو استلامه يسري على كل جزء مفتوح. | loans:write |
| GET/loans/downtimes | فترات مؤرخة لا يمكن فيها حجز غرض واحد أو صرفه ولم تنتهِ بعد (item_id يحصر النتيجة في غرض واحد). | loans:read |
| POST/loans/downtimes | أضف فترة إلى غرض: loan_item_id وstarts_at وends_at وreason اختياري. تُرفض ما دام حجز أو عملية صرف يحتفظ بالغرض لأي جزء من ذلك الوقت. | loans:write |
| DELETE/loans/downtimes/{id} | أزل فترة. | loans:write |
| GET/loans/extra-values/{type}/{id} | سمات المنشأة المخصصة لمستلم معدات (person) أو reservation أو checkout، مع الحقول المعرّفة لذلك النوع من السجلات. | loans:read |
| PUT/loans/extra-values/{type}/{id} | اضبط تلك السمات، بعد فحصها مقابل حقول المنشأة وشروط الإظهار الخاصة بها. | loans:write |
| GET/loans/closures | أيام إغلاق مكتب المعدات التي لم تنتهِ بعد. | loans:read |
| POST/loans/closures | أضف إغلاقًا: تاريخا starts_on وends_on بالمنطقة الزمنية للمنشأة، حتى 366 يومًا. note الاختيارية تبقى داخلية؛ وpublic_message (حتى 300 حرف) تُعرض على من يستلمون المعدات. لا تُنسخ الملاحظات الموجودة إلى الرسالة الموجّهة إليهم أبدًا. | loans:write |
| DELETE/loans/closures/{id} | أزل إغلاقًا. | loans:write |
| GET/loans/rules | الإعدادات الافتراضية للمنشأة، وقواعد الفئات للمدة والحدود وحجب المتأخرات والموافقة وقواعد الحجز (فواصل التجهيز، والحد الأدنى للإشعار المسبق، وإلى أي مدى مقدمًا)، وفترات الإغلاق. | loans:read |
| POST/loans/rules | أنشئ قاعدة فئة واحدة أو استبدلها. حقول قواعد الحجز المحذوفة تحتفظ بقيمها المحفوظة. | loans:write |
| GET/loans/timeline | فحوص سعة الأغراض أو الفئات ليوم كامل. يلزم تاريخا from وuntil شاملان بتوقيت المنشأة المحلي، بما لا يزيد على 31 يومًا من اليوم حتى العام القادم؛ واختياريًا group=item|category وitem_id وcategory المطابقة تمامًا وpage (50 صفًا). الخلايا true أو false أو null (غير مؤكد). الأيام المتجاورة لا تضمن حجزًا متصلًا. | loans:read |
| GET/loans/warranties | تواريخ الضمان المسجّلة؛ filter=soon|expired|all وcategory المطابقة تمامًا وpage (50 صفًا). soon تشمل اليوم حتى 30 يومًا مقبلة. الاشتراك في التذكير الشخصي موجود في مساحة العمل. | loans:read |
| GET/loans/utilization | الساعات المنقضية لكل أصل من سجل الحالة المسجّل. يلزم تاريخا from وuntil شاملان بتوقيت المنشأة المحلي ضمن آخر 365 يومًا، ويُقتطع عند الآن؛ واختياريًا item_id وcategory المطابقة تمامًا وformat=csv. يعطي JSON الثواني بدقة؛ وساعات CSV بست خانات عشرية. المتاح يشمل المستلَم؛ ويُستثنى وقت الإصلاح أو الصيانة وسائر الأوقات غير المتاحة. أي توقف سابق غير معروف. تتطابق الإجماليات مع صفوف الأصول. | loans:read |
| GET/loans/maintenance | سجل الصيانة والمعايرة واختبار السلامة والفحص والتنظيف والإصلاح والملاحظات؛ صفِّ بالغرض أو بالعمل القادم أو بأوامر العمل (المفتوحة أو كلها) وفنيّها. | loans:read |
| POST/loans/maintenance | سجّل صيانة والموعد التالي المستحق لغرض. مع plan_id، العمل المنجز لجدول متكرر، ويبدأ جولته التالية. | loans:write |
| GET/loans/service-plans | جداول الصيانة والمعايرة واختبار السلامة والفحص والتنظيف المتكررة، مع بيان هل يستحق كل منها بالتاريخ أو بساعات الصرف أو بعدد عمليات الصرف. | loans:read |
| POST/loans/service-plans | أضف جدولًا متكررًا إلى غرض (للمالكين والمديرين). | loans:write |
| PUT/loans/maintenance/{id} | غيّر أمر عمل أو أغلقه: الحالة والفني والمورد والتكلفة، وللمنجز نتيجته وهل يعود الغرض إلى الخدمة. | loans:write |
| GET/loans/maintenance/costs | تكلفة الصيانة والإصلاح والتنظيف لكل غرض، من الإدخالات المنتهية وأوامر العمل المنجزة. | loans:read |
| GET/loans/items/{id}/lifecycle | سجل شراء الغرض وإهلاكه وتأمينه والتخلص منه، مع قيمته اليوم (للمالكين والمديرين). | loans:read |
| PUT/loans/items/{id}/lifecycle | احفظ سعر الشراء والتاريخ والمورد والطلب، وطريقة الإهلاك (القسط الثابت أو الرصيد المتناقص)، والعمر الافتراضي وقيمة الخردة، والتأمين (للمالكين والمديرين). | loans:write |
| POST/loans/items/{id}/dispose | سجّل كيف غادر الغرض (بيع أو خُرِّد أو تُبرِّع به أو أُعيد تدويره أو فُقد أو سُرق)؛ ويُسحب من الخدمة وتُلغى حجوزاته وأوامر عمله المفتوحة. | loans:write |
| DELETE/loans/items/{id}/dispose | تراجع عن تخلص سُجّل بالخطأ؛ ويعود الغرض متاحًا. | loans:write |
| GET/loans/valuation | قيمة المعدات في تاريخ ما، بالسنت، مع إجماليات ما لا يزال محتفظًا به (للمالكين والمديرين). | loans:read |
| POST/loans/service-plans/import | افحص جداول أو أضفها من ملف CSV بالأعمدة الموثّقة، مع تسمية المعدات بوسم الأصل (للمالكين والمديرين). | loans:write |
| POST/loans/maintenance/work-orders/import | افحص أوامر عمل مفتوحة أو أضفها من ملف CSV بالأعمدة الموثّقة (للمالكين والمديرين). | loans:write |
| GET/loans/maintenance/planner | الأعمال المجدولة وأوامر العمل المفتوحة حسب يوم المنشأة نفسها لمدة تصل إلى 62 يومًا، ولفني واحد اختياريًا. | loans:read |
| GET/loans/funding | ما اشتراه كل صندوق أو منحة أو مركز تكلفة وما حُمّل عليه من أعمال، قابل للتصفية بالصندوق والتواريخ (للمالكين والمديرين). سجل فقط: لا يأخذ vFound أي دفعة. | loans:read |
| GET/loans/substances | سجل المواد الخطرة: المادة والمكان وفئات الخطر وتواريخ المراجعة. سجل لما تقوله المنشأة؛ ولا يقدّم vFound أي نصيحة تخص السلامة. | loans:read |
| POST/loans/substances | أضف مادة، مع صحيفة بيانات السلامة الخاصة بها كملف PDF أو صورة (للمالكين والمديرين). | loans:write |
| PUT/loans/substances/{id} | غيّر مادة أو استبدل صحيفة بياناتها (للمالكين والمديرين). | loans:write |
| DELETE/loans/substances/{id} | أزل مادة وصحيفة بياناتها المحفوظة (للمالكين والمديرين). | loans:write |
| GET/loans/licences | تراخيص معدات المنشأة مع المقاعد وتاريخ الانتهاء والأغراض المثبّتة عليها (للمالكين والمديرين). لا يُخزَّن أي مفتاح ترخيص. | loans:read |
| POST/loans/licences | أضف ترخيصًا (للمالكين والمديرين). | loans:write |
| PUT/loans/licences/{id} | غيّر ترخيصًا ومكان تثبيته. | loans:write |
| DELETE/loans/licences/{id} | أزل ترخيصًا. | loans:write |
| GET/loans/expiries | التأمين والتراخيص التي تنتهي قريبًا أو انتهت بالفعل (للمالكين والمديرين). | loans:read |
| GET/loans/stocktakes | أحدث عمليات جرد المعدات مع أعداد ما مُسح وما فُقد. | loans:read |
| POST/loans/stocktakes | ابدأ جردًا مفتوحًا واحدًا للمنشأة، لكل شيء، أو لموقع أو فئة أو مجموعة معدات واحدة، أو لما يحمله شخص واحد (custodian_id)، مع إسناده اختياريًا إلى عضو في الفريق (assigned_to). | loans:write |
| POST/loans/stocktakes/{id}/scan | امسح ملصق معدات أو وسم أصل أو رقمًا تسلسليًا في الجرد المفتوح. | loans:write |
| POST/loans/stocktakes/{id}/scan-many | عُدّ ما يصل إلى 2,000 رمز دفعة واحدة (قارئ RFID بنمط لوحة المفاتيح أو قائمة)؛ يُحتسب كل رمز مرة واحدة وتُعاد الرموز غير المطابقة. | loans:write |
| PUT/loans/stocktakes/{id}/assign | أسند الجرد المفتوح إلى عضو واحد في الفريق ليعدّه (assigned_to)، أو إلى لا أحد (null). | loans:write |
| POST/loans/stocktakes/{id}/finish | أنهِ الجرد وأرجع قائمة الأغراض المفقودة. | loans:write |
| GET/loans/stocktake-schedules | عمليات جرد تُفتح من تلقاء نفسها، مرة واحدة أو بتكرار. | loans:read |
| POST/loans/stocktake-schedules | جدولة جرد، مرة واحدة أو أسبوعيًا أو شهريًا أو كل ثلاثة أشهر أو سنويًا، في وقت اليوم الخاص بالمنشأة. | loans:write |
| PATCH/loans/stocktake-schedules/{id} | غيّر جدولًا أو أوقفه مؤقتًا أو استأنفه. | loans:write |
| DELETE/loans/stocktake-schedules/{id} | احذف جدولًا؛ وتبقى عمليات الجرد التي فتحها. | loans:write |
| GET/loans/last-seen | أين مُسح كل غرض آخر مرة، حين تحفظ المنشأة مواضع المسح (أعضاء الفريق الذين وافقوا فقط؛ ولا يكون ذلك من مفتاح أبدًا). | loans:read |
| GET/loans/transfers | عمليات نقل المعدات الواردة والصادرة لهذه المنشأة. | loans:read |
| POST/loans/transfers | جهّز معدات لمنشأة أخرى مخوّلة في مجموعة العميل نفسها. | loans:write |
| POST/loans/transfers/{id}/send | سجّل أن المعدات المجهّزة غادرت منشأة المصدر. | loans:write |
| POST/loans/transfers/{id}/receive | استلم المعدات في الوجهة مع موقعها وحالتها عند الوصول. | loans:write |
| POST/loans/transfers/{id}/cancel | ألغِ نقلًا مجهّزًا قبل الإرسال. | loans:write |
| POST/loans/transfers/{id}/reject | ارفض في الوجهة نقلًا مجهّزًا قبل الإرسال. | loans:write |
| POST/loans/transfers/{id}/exception | سجّل مشكلة أثناء وجود المعدات في الطريق. | loans:write |
| POST/loans/import | عاين أو استورد ما يصل إلى 5,000 صف CSV باستخدام عناوين أعمدة vFound أو Snipe-IT أو Sortly أو Cheqroom. | loans:write |
Visitors
| الطلب | ما يفعله | النطاق |
|---|---|---|
| GET/visitors | الزيارات، الأحدث تغييرًا أولًا، مع status (expected أو in أو out أو cancelled أو missed)، والزائر، والمضيف، ورمز التصريح ما دام صالحًا، والأوقات. المرشّحات: status وsearch (الزائر أو الشركة أو المضيف أو رمز التصريح) وupdated_since. | visitors:read |
| GET/visitors/{id} | زيارة واحدة. | visitors:read |
| POST/visitors | ادعُ زائرًا أو سجّل حضوره. تقبل حقول الزائر والمضيف والوقت، إضافة إلى visitor_type_id والإجابات والتواريخ الصالحة وتكرارًا يوميًا أو في أيام الأسبوع. | visitors:write |
| POST/visitors/{id}/sign-in | سجّل حضور زائر متوقع؛ ويُبلَّغ المضيف. أرسل answers لعضو مجموعة يتطلب نوعه أسئلة إلزامية، وid_expires_on مع identity_checked عندما تسجّل المنشأة تاريخ انتهاء هوية مادية. تحمل الزيارة عندها id_expires_on وid_expired. | visitors:write |
| POST/visitors/{id}/group/sign-in | سجّل حضور كل من في مجموعة الزيارة ممن يُنتظر حضورهم اليوم، مع رسالة بريد إلكتروني واحدة إلى المضيف؛ ويُدرج في skipped كل من يحتاج إلى صورته أو فحص هويته أو توقيعه أو إجاباته أو شروطه الخاصة. | visitors:write |
| POST/visitors/{id}/sign-out | سجّل خروجه. | visitors:write |
| POST/visitors/{id}/cancel | ألغِ دعوة. | visitors:write |
| POST/visitors/{id}/send-pass | أرسل التصريح بالبريد الإلكتروني مرة أخرى. | visitors:write |
| POST/visitors/{id}/approve | وافق على زيارة معلّقة وأرسل التصريح. | visitors:write |
| POST/visitors/{id}/deny | ارفض زيارة معلّقة. | visitors:write |
| GET/visitors/{id}/badge | نزّل الشارة القابلة للطباعة من المتصفح. اختر size من 4x3 أو brother أو dymo. | visitors:read |
| GET/visitors/{id}/card | هل لدى الزيارة بطاقة RFID وآخر أربعة أحرف منها (ولا الرقم أبدًا). معطّلة إلى أن تفعّل المنشأة البطاقات والأقراص. | visitors:read |
| POST/visitors/{id}/card | امنح زيارة متوقعة أو مسجّلة الحضور بطاقة برقمها؛ ورقم واحد يكون فعالًا على زيارة واحدة في كل مرة. | visitors:write |
| DELETE/visitors/{id}/card | استرد البطاقة. | visitors:write |
| GET/visitors/{id}/assets | الأشياء المسلَّمة للزيارة، المدخلة يدويًا. | visitors:read |
| POST/visitors/{id}/assets | سجّل شيئًا سُلّم للزيارة، مع وسم اختياري. | visitors:write |
| POST/visitors/{id}/assets/{asset}/return | حدّد شيئًا على أنه أُعيد. | visitors:write |
| GET/visitor-assets/not-returned | الأشياء المسلَّمة للزوار ولم تُعَد بعد، الأحدث أولًا. | visitors:read |
| GET/visitors/{id}/fast-track | هل لدى الزيارة رمز مسار سريع فعّال، وحتى متى وكم مرة استُخدم (ولا الرمز أبدًا، فلا يراه إلا الزائر). | visitors:read |
| POST/visitors/{id}/fast-track | امنح زائرًا عائدًا رمز مسار سريع يدوم days (من 1 إلى 365). | visitors:write |
| DELETE/visitors/{id}/fast-track | استرد الرمز. | visitors:write |
| GET/visitor-types | اسرد أنواع الزوار وأسئلتها وشروطها وشاراتها وموافقاتها ومدة الاحتفاظ بها (retention_days تكون null عندما يتبع النوع الإعداد الافتراضي للمنشأة). | visitors:read |
| POST/visitor-types | أنشئ نوع زائر. | visitors:write |
| PATCH/visitor-types/{id} | غيّر حقول نوع الزائر التي ترسلها. | visitors:write |
| DELETE/visitor-types/{id} | عطّل نوع زائر دون تغيير الزيارات السابقة. | visitors:write |
| GET/visitor-roll-call | احصل على أحدث حصر حضور وأعداده المباشرة. الحصر الجاري يضيف كل من سجّل حضوره منذ بدايته؛ والذي يُترك جاريًا 6 ساعات يُغلق. | visitors:read |
| POST/visitor-roll-call | ابدأ حصر حضور، مع إمكانية تضمين الزوار المتوقعين اليوم وكل من ينتظر الموافقة. | visitors:write |
| PATCH/visitor-roll-call/entries/{entry} | حدّد إدخالًا واحدًا على أنه آمن أو مفقود. | visitors:write |
| POST/visitor-roll-call/{id}/finish | أنهِ حصر الحضور النشط واحتفظ بتقريره. | visitors:write |
| GET/staff-attendance | اسرد حضور الموظفين لمدى تواريخ بتوقيت المنشأة (اليوم افتراضيًا، 366 يومًا على الأكثر)، أو فقط الأشخاص المسجّلين حاليًا بـ open=true. ولا يتضمن بريد الشخص الإلكتروني أبدًا. | visitors:read |
| POST/staff-attendance | سجّل حضور شخص من قائمة الموظفين (mode office أو remote) أو خروجه، بالقواعد نفسها المطبّقة عند المكتب. يتطلب تفعيل تسجيل حضور الموظفين في المنشأة. | visitors:write |
| POST/staff-presence | أرسل ما يصل إلى 50 حدث حضور (in أو out أو muster) من نظام الشارات أو ساعة الدوام أو Wi-Fi لديك، يسمّي كل منها شخصًا في قائمة الموظفين بالمرجع أو بالمعرّف الخارجي أو بالبريد الإلكتروني. يتطلب تفعيل تسجيل حضور الموظفين وتغذية الحضور في المنشأة. ويجيب بما حدث لكل حدث، ولا يذكر من أبدًا. | visitors:write |
| POST/visitors/{id}/catering | أنشئ طلب الضيافة لزيارة متوقعة أو مسجّلة الحضور أو غيّره أو (من دون أي بنود) أزله، من الخيارات التي تسردها المنشأة. يرسل رسالة بريد إلكتروني واحدة إلى صندوق الضيافة في المنشأة؛ ولا يطلب vFound شيئًا ولا يأخذ أي دفعة. يتطلب تفعيل الضيافة في المنشأة. | visitors:write |
| GET/workplace/spaces | اسرد المكاتب وغرف الاجتماعات ومواقف السيارات التي يجوز للأشخاص حجزها في المنشأة. | visitors:read |
| GET/workplace/free | ابحث عن المساحات الخالية طوال وقت كامل (7 أيام على الأكثر)، مع استبعاد مكتب محجوز لشخص آخر. | visitors:read |
| GET/workplace/bookings | اسرد حجوزات المكاتب والغرف والمواقف ضمن مدى زمني لا يزيد على 31 يومًا. ولا يتضمن بريد الشخص الإلكتروني أبدًا. | visitors:read |
| POST/workplace/bookings | احجز مساحة لشخص، مرة واحدة أو كحجز متكرر (يوميًا أو أسبوعيًا، حتى 52 مرة، الكل أو لا شيء)، وفق قواعد الحجز في Equipment. | visitors:write |
| POST/workplace/bookings/{id}/cancel | ألغِ حجزًا، أو ألغِ بـ scope قيمتها following أو series أوقاته اللاحقة. | visitors:write |
| POST/workplace/bookings/{id}/check-in | سجّل حضور حجز، من 15 دقيقة قبل بدايته حتى نهايته. | visitors:write |
| POST/visitors/{id}/room | احجز غرفة اجتماعات لزيارة، من وقت الزيارة؛ وتتبع الغرفة الزيارة. | visitors:write |
| GET/appointment-pages | اسرد صفحات المواعيد في المنشأة وساعاتها وهل كل منها مفتوحة للزوار الآن. | visitors:read |
| GET/visitor-roll-call/archive | اسرد عمليات حصر الحضور المنتهية (الطوارئ والتدريبات والإشعارات)، الأحدث أولًا. | visitors:read |
| GET/visitor-roll-call/{id} | حصر حضور واحد مع أشخاصه وخطه الزمني وعمليات التمشيط وأعداد الرسائل. | visitors:read |
| POST/visitor-roll-call/{id}/people | أضف شخصًا (موظفًا أو غيره أو متعاقدًا) إلى حصر الحضور الجاري. | visitors:write |
| POST/visitor-roll-call/{id}/scan | حدّد زائرًا على أنه آمن من رابط تصريحه أو رمزه، عند نقطة التجمع. | visitors:write |
| POST/visitor-roll-call/{id}/sweeps | سجّل منطقة على أنها فُرغت بالتمشيط أو أن فيها أشخاصًا. | visitors:write |
| POST/visitor-roll-call/{id}/messages | أرسل رسالة إلى الجميع، أو إلى من لم يصبحوا آمنين بعد، أو إلى من يحتاجون مساعدة. تُرسل بالبريد الإلكتروني وتنبيه المتصفح، وعبر مزوّد المنشأة الخاص بها بالرسائل النصية أو WhatsApp، مع رابط خاص للرد بأنه آمن أو يحتاج مساعدة. | visitors:write |
| GET/visitor-roll-call/{id}/people/{entry}/messages | المحادثة مع شخص واحد في حصر حضور: ما أرسله الفريق إليه وما كتبه ردًّا من رابطه الخاص، الأقدم أولًا. للرد، استخدم نقطة نهاية الرسائل مع audience entry. | visitors:read |
| POST/visitor-hazard-alerts | تحذير يكتبه عضو في الفريق ويرسله إلى مجموعة مختارة: hazard وmessage وgroup (on_site أو visitor_type أو host أو tenant، مع group_ref). يبدأ حصر حضور من نوع hazard لتلك المجموعة. لا يقرأ vFound أي تغذية للطقس أو الأخبار أو التهديدات: لا يُرسل شيء ما لم ترسل هذا الطلب. يجيب بـ 409 ما دام حصر حضور آخر جاريًا. | visitors:write |
| POST/visitor-help-alerts | اطلب المساعدة بهدوء: يُبلَّغ أعضاء الفريق المختارون لذلك؛ ولا يرى أي زائر شيئًا. | visitors:write |
| GET/visitor-kiosks | اسرد أجهزة الكشك المقترنة والمعلّقة والملغاة. | visitors:read |
| POST/visitor-kiosks/pairing | أنشئ رمز اقتران من ثمانية أحرف يدوم عشر دقائق. | visitors:write |
| DELETE/visitor-kiosks/{id} | ألغِ جهاز كشك. | visitors:write |
| PUT/visitor-kiosks/{id}/settings | غيّر إعدادات كشك واحد: بريد إلكتروني عندما لا يُرى لعدد من الدقائق، والعودة إلى البداية بعد وقت من الهدوء، وتوقيع عند تسجيل الحضور، وطباعة الشارة من اللوحي. كل شيء يبدأ معطّلًا. | visitors:write |
| GET/visitor-analytics | الإجماليات حسب اليوم والساعة والنوع والمضيف، إضافة إلى متوسط مدة البقاء للسنة الأخيرة. | visitors:read |
| GET/visitor-registration | احصل على رابط التسجيل الذاتي للمنشأة وهل هو مفعّل. | visitors:read |
| GET/school/movements | حالات تأخر التلاميذ ومغادرتهم المبكرة، الأقدم أولًا، من since (الافتراضي آخر 24 ساعة)، مع reference كل تلميذ لنظام معلومات المدرسة. لا يستطيع عضو الفريق ذو صلاحية العرض فقط المسمّى في X-Acting-User استخدامه. | school:read |
| PUT/school/pupils | أضف ما يصل إلى 500 تلميذ أو حدّثهم بـ reference؛ وأرسل active قيمتها false لتلميذ غادر. لا يُحذف شيء هنا. | school:write |
بيانات الزوار بيانات شخصية: احتفظ بها فقط للمدة التي تحتاجها.
الأشخاص
تضم قائمة الأشخاص المقيمين أو الموظفين أو الطلاب الذين يخدمهم مكتبك. يجد Parcels المستلمين فيها، ويجد Visitors المضيفين، ويقترح Equipment مستلمي المعدات. أبقِها متزامنة مع نظام الموارد البشرية أو الطلاب أو الممتلكات لديك عبر API.
| الطلب | ما يفعله | النطاق |
|---|---|---|
| GET/people | القائمة، بالاسم. المرشّحات: search (الاسم أو البريد الإلكتروني أو الوحدة أو المرجع) وupdated_since. | people:read |
| GET/people/{id} | شخص واحد. | people:read |
| POST/people | أضف شخصًا: name (مطلوب) وemail وunit وreference وlanguage لرسائله الإلكترونية. | people:write |
| POST/people/upsert | أضف ما يصل إلى 500 شخص أو حدّثهم في استدعاء واحد: people قائمة بالحقول نفسها. من كان بريده الإلكتروني موجودًا في القائمة يُحدَّث. ويجيب بعدد من أُضيفوا وحُدّثوا وتُخطّوا. | people:write |
| PATCH/people/{id} | غيّر الحقول التي ترسلها فقط. | people:write |
| DELETE/people/{id} | أزل شخصًا. تحتفظ طرودهم وزياراتهم وعمليات الصرف الخاصة بهم بالاسم الذي كان لديهم. | people:write |
| GET/people/export | نزّل قائمة الأشخاص الكاملة بصيغة CSV آمنة من الصيغ. | people:read |
| POST/people/{id}/send-my-vfound | أرسل بالبريد الإلكتروني إلى شخص نشط واحد الصفحة الموقّعة لطرودهم وزوارهم ومعداتهم المرتبطة. | people:write |
| GET/people/sync-source | اعرض دليل CSV المحفوظ وآخر نتيجة مزامنة. | people:read |
| PUT/people/sync-source | احفظ url عام بصيغة HTTPS لملف CSV وmode (upsert أو mirror). | people:write |
| DELETE/people/sync-source | أزل الاتصال وأبقِ الأشخاص المستوردين بالفعل. | people:write |
| POST/people/sync-source/run | شغّل الاتصال المحفوظ الآن. | people:write |
يستطيع المالكون والمديرون أيضًا ربط رابط CSV عام بصيغة HTTPS من الأشخاص. يفحصه vFound كل ساعة، ويتبع ثلاث عمليات إعادة توجيه على الأكثر بعد فحص كل وجهة، ويقبل 10 MB على الأكثر، وفي وضع mirror يتوقف قبل إجراء أي تغيير عندما ينخفض عدد الصفوف الصالحة بأكثر من 30 في المئة. تُغيَّر الحقول المتصلة عند مصدرها.
التزويد التلقائي بالدليل
لدى Microsoft Entra الاتصال الجاهز الذي يضبطه العميل والمذكور أعلاه. أما أدلة الهوية، ومنها Okta وOneLogin وJumpCloud، فيمكنها بدلًا من ذلك تزويد قائمة الأشخاص على https://vfound.io/api/scim/v2/Users بمفتاح API من vFound يحمل people:write. استخدم مفتاح Bearer كالرمز السري. يزيل التعطيل الشخص من الاقتراحات؛ ويجعل DELETE الروابط مجهولة الهوية وفق قواعد الأشخاص نفسها. تنشئ نقطة النهاية هذه مدخلات في قائمة الأشخاص فقط ولا تنشئ أبدًا حسابات دخول للفريق.
يمكن أن تأتي قوائم المتدربين على المعدات من الدليل نفسه: اربط تدريبًا بمجموعة في الدليل باسمها (Equipment، السياسات، التدريب)، ثم عيّن تلك المجموعة لتطبيق vFound. تجيب https://vfound.io/api/scim/v2/Groups فقط عن المجموعات التي يسمّيها تدريب، وترفض أي مجموعة أخرى. أعضاؤها هم الأشخاص (بمعرّف مستخدم SCIM الخاص بهم) الذين يحملون التدريب؛ والشخص الذي يغادر المجموعة يفقد التدريب فقط إذا كان الدليل هو الذي منحه إياه، فيبقى السجل الذي أضافه الموظفون. والسجل الذي منحه الدليل وانتهت صلاحيته يُجدَّد من ذلك اليوم عندما يرسل الدليل المجموعة مرة أخرى والشخص ما زال فيها. تجيب المجموعات فقط عن منشأة لديها Equipment. ولأن عضوية المجموعة تمنح تدريبًا، والتدريب يتيح للأشخاص استلام المعدات التي تشترطه، فإن مفتاحًا يحمل people:write يستطيع منح التدريبات بهذه الطريقة: احتفظ بهذا المفتاح لمزوّد الهوية لديك.
Webhooks
أضف ما يصل إلى 25 عنوان HTTPS في الإعدادات، للمطورين، أو عبر API أدناه، واختر أي الأحداث أدناه يتلقاه كل عنوان. يرسل vFound طلب POST بصيغة JSON خلال ثوانٍ، ويعيد محاولة الإخفاقات لنحو ثلاث ساعات، ويوقف عنوانًا بعد 15 عملية تسليم فاشلة متتالية.
| الحدث | متى | البيانات |
|---|---|---|
item.created | يُضاف غرض معثور عليه | غرض |
item.updated | تتغير حالته أو عنوانه أو موقعه أو فئته أو تاريخ الاحتفاظ به أو ظهور صورته | غرض |
item.transfer_sent | يُرسل غرض معثور عليه إلى منشأة أخرى في المجموعة (تتلقاه المنشأتان) | نقل غرض |
item.transfer_cancelled | تستعيده المنشأة المرسِلة قبل وصوله | نقل غرض |
item.transfer_received | تؤكد المنشأة المستلِمة وصوله | نقل غرض |
claim.created | يقدّم ضيف طلب استرداد | طلب استرداد |
item.disposition_recorded | يُتبرَّع بغرض أو يُتخلَّص منه | غرض |
item.match_updated | يتغير حكم مطابقة محفوظ بالذكاء الاصطناعي؛ report_id وitem_id وlabel وreason | زوج مطابقة |
lost_report.match_updated | يتغير حكم مطابقة محفوظ بالذكاء الاصطناعي؛ report_id وitem_id وlabel وreason | زوج مطابقة |
claim.ownership_reviewed | يسجّل مدير مراجعة ملكية؛ اجلب العهدة لسجل المراجعات | طلب استرداد |
claim.decision_recorded | يُقبل طلب استرداد أو يُرفض | طلب استرداد |
claim.release_approved | يوافق مدير مختلف على التسليم | طلب استرداد |
claim.handover_recorded | يغلق الاستلام الفعلي طلب استرداد جاهزًا للاستلام | طلب استرداد |
claim.status_changed | ينتقل طلب استرداد إلى حالة جديدة | طلب استرداد |
lost_report.updated, lost_report.closed, lost_report.contact_updated, lost_report.created | يبلّغ ضيف عن فقد | بلاغ فقد |
parcel.logged | يُسجَّل طرد عند المكتب أو عبر API | طرد |
parcel.updated | تتغير أي من تفاصيله عند المكتب، مثل مستلمه أو رقم تتبعه أو رفّه | طرد |
parcel.reminded | يُرسل إلى المستلم تذكير، من المكتب أو تلقائيًا | طرد |
parcel.collected | يُسلَّم طرد | طرد |
parcel.returned | يُعاد طرد إلى المرسل | طرد |
parcel.recipient_arrived | يقول مستلم إنه عند المكتب | إدخال في طابور الاستلام |
parcel.reminders_snoozed | يوقف مستلم تذكيراته مؤقتًا | شخص وعدد الطرود |
parcel.held | يحدد مستلم تاريخ احتفاظ | شخص وتاريخ وعدد الطرود |
parcel.proxy_created | يرسل مستلم رمز استلام بالبريد الإلكتروني إلى مفوَّض | شخص ومفوَّض وتاريخ انتهاء |
parcel.pickup_served | يحدد المكتب وصولًا على أنه خُدم | إدخال في طابور الاستلام |
parcel.escalated | يبلغ طرد منتظر عمر التصعيد في المنشأة | طرد |
parcel.outgoing_logged | يُسجَّل طرد صادر | طرد صادر |
parcel.outgoing_handed_over | يُسلَّم طرد صادر إلى شركة شحن | تسليم صادر |
parcel.round_created | تُنشأ جولة توزيع | ملخص الجولة |
parcel.round_delivered | تكتمل محطة في جولة توزيع | معرّفات الجولة والمحطة والطرود |
checkroom.checked_in | يُسجَّل استلام شيء ويُعطى رقمًا | تذكرة |
checkroom.handed_back | يُسلَّم | تذكرة |
checkroom.left | يُغلق المساء وهو ما زال في Checkroom | تذكرة |
checkroom.self_checkin_started | يبدأ ضيف تذكرة من كشك مقترن | تذكرة |
checkroom.ready_requested | يطلب ضيف من المكتب تجهيز أغراضه | تذكرة |
checkroom.ready | يحدد المكتب أغراض ضيف على أنها جاهزة | تذكرة |
checkroom.station_created | تُنشأ محطة في Checkroom | محطة |
checkroom.station_updated | تتغير محطة في Checkroom | محطة |
checkroom.event_created | تُنشأ فعالية في Checkroom | الحدث |
checkroom.event_updated | تتغير فعالية في Checkroom | الحدث |
loan.checked_out | يُصرف غرض | عملية صرف |
loan.due_soon | يقل الوقت المتبقي على موعد إعادته عن ساعتين، مرة واحدة لكل موعد إعادة | عملية صرف |
loan.overdue | يحل موعد إعادته ولم يُعد، مرة واحدة لكل موعد إعادة | عملية صرف |
loan.extended | يتغير موعد إعادته | عملية صرف |
loan.returned | يعود إلى المكتب | عملية صرف |
loan.lost | يُسجَّل أنه لن يعود | عملية صرف |
loan.checkout_created | تُنشأ عملية صرف ذرية واحدة لعدة أغراض | عملية صرف، مع أي مخزون على الإيصال نفسه في stock |
loan.self_checkout | يكمل مستلم المعدات الصرف من الكشك | عملية صرف |
loan.kit_created | تُنشأ مجموعة معدات محفوظة | مجموعة معدات |
loan.kit_updated | تتغير مجموعة معدات محفوظة | مجموعة معدات |
loan.reservation_requested | ينتظر حجز الموافقة | حجز |
loan.reservation_created | يُؤكَّد حجز فورًا | حجز |
loan.reservation_approved | يُوافَق على حجز معلّق | حجز |
loan.reservation_ready | تصبح المعدات المحجوزة جاهزة للاستلام | حجز |
loan.reservation_cancelled | يُلغى حجز | حجز |
loan.reservation_collected | تُسلَّم المعدات المحجوزة | عملية صرف |
loan.extension_requested | يطلب مستلم المعدات وقتًا إضافيًا | عملية صرف |
loan.problem_reported | يبلّغ مستلم المعدات عن مشكلة في المعدات | عملية صرف |
loan.rule_updated | تتغير قاعدة صرف فئة | قاعدة |
loan.maintenance_logged | تُسجَّل صيانة | الصيانة |
loan.maintenance_due | تستحق صيانة مجدولة | الصيانة |
loan.service_due | يستحق جدول خدمة متكرر (بالتاريخ أو بساعات الصرف أو بعدد عمليات الصرف)، مرة واحدة لكل جولة | الصيانة |
loan.work_order_opened | يُفتح أمر عمل، من الموظفين أو من إعادة تطلب المنشأة أن يُفتح لها أمر | الصيانة |
loan.work_order_closed | يُنجز أمر عمل أو يُلغى | الصيانة |
loan.item_disposed | يُتخلَّص من غرض (بيع أو خُرِّد أو تُبرِّع به أو أُعيد تدويره أو فُقد أو سُرق) | Equipment |
loan.stocktake_started | يبدأ جرد للمعدات | جرد |
loan.stocktake_completed | ينتهي جرد للمعدات | جرد |
loan.transfer_prepared | تجهّز منشأة مخوّلة معدات للنقل | نقل |
loan.transfer_sent | تغادر المعدات المجهّزة منشأة المصدر | نقل |
loan.transfer_received | تستلم الوجهة المعدات | نقل |
loan.transfer_rejected | ترفض الوجهة نقلًا مجهّزًا | نقل |
loan.transfer_cancelled | يلغي المصدر نقلًا مجهّزًا | نقل |
loan.transfer_exception | نقل في الطريق يحتاج إلى انتباه | نقل |
loan.transfer_lost | يغلق المصدر نقلًا لم يصل أبدًا | نقل |
loan.charge_recorded | يُسجَّل رسم غرامة أو تلف أو استبدال أو استخدام أو غيره | إدخال رسوم |
loan.charge_waived | يعفي مدير مما لا يزال الرسم يحتاجه، مع سبب | إدخال رسوم |
loan.payment_recorded | يسجّل الموظفون مالًا أخذته المنشأة بنفسها (لا يعالج vFound أي دفعة أبدًا) | إدخال رسوم |
loan.payment_voided | يبطل مدير دفعة سُجّلت بالخطأ | إدخال رسوم |
loan.deposit_recorded | يسجّل الموظفون وديعة أخذتها المنشأة | إدخال رسوم |
loan.deposit_resolved | تُردّ وديعة محتجزة أو تُستبقى | إدخال رسوم |
loan.invoice_issued | تصدر فاتورة لرسوم مستلم المعدات | فاتورة |
loan.invoice_voided | يبطل مدير فاتورة، مع سبب | فاتورة |
loan.quote_accepted | يقبل الفريق عرض سعر وتُنشأ حجوزاته | عرض سعر |
loan.payment_request_created | يسجّل الفريق طلب دفع (لا يُرسل شيء إلى الشخص) | طلب دفع |
loan.payment_request_paid | الدفعات المسجّلة على طلب تغطيه كاملًا | طلب دفع |
loan.delivery_done | يُعلَّم تسليم أو استلام على أنه تم | تسليم |
loan.items_imported | يكتمل استيراد CSV للمعدات | أعداد |
visit.expected | يُدعى زائر | زيارة |
visit.signed_in | يسجّل زائر حضوره، عند المكتب أو من لافتة QR الخاصة بك | زيارة |
visit.host_confirmed | يؤكد المكتب من جاء زائر سجّل حضوره بنفسه لزيارته | زيارة |
visit.signed_out | يسجّل خروجه، عند المكتب أو من تصريحه أو تلقائيًا بعد انتهاء اليوم | زيارة |
visit.cancelled | تُلغى دعوة | زيارة |
visit.approval_requested | تنتظر زيارة موافقة الموظفين | زيارة |
visit.approved | يُوافَق على زيارة معلّقة | زيارة |
visit.denied | تُرفض زيارة معلّقة | زيارة |
visit.host_replied | يرد مضيف من رابطه الخاص | زيارة |
visit.roll_call_started | يبدأ حصر حضور مباشر (طوارئ أو تدريب أو إشعار) | ملخص حصر الحضور |
visit.roll_call_completed | ينتهي حصر حضور مباشر | ملخص حصر الحضور |
visitor_type.created | يُنشأ نوع زائر | نوع زائر |
visitor_type.updated | يتغير نوع زائر | نوع زائر |
visitor_type.deactivated | يُعطَّل نوع زائر | نوع زائر |
visitor_agreement.signed | يوقّع زائر وثيقة اتفاقية، مع رابط للنسخة الموقّعة يعمل سبعة أيام | توقيع اتفاقية |
kiosk.paired | يُقرَن كشك للزوار | كشك |
kiosk.revoked | يُلغى كشك للزوار | كشك |
courier.signed_in | يُسجَّل زائر توصيل في Parcels | ساعي شحن |
courier.signed_out | يغادر زائر توصيل | ساعي شحن |
staff.signed_in | يسجّل شخص من قائمة الموظفين حضوره، في المكتب أو عن بُعد | حضور الموظفين |
staff.signed_out | يسجّل شخص من قائمة الموظفين خروجه، أو يُسجَّل خروجه تلقائيًا | حضور الموظفين |
person.created | يُضاف شخص | شخص |
person.updated | يتغير شخص | شخص |
person.deactivated | يعطّل التزويد بالدليل شخصًا | شخص |
person.deleted | يُزال شخص | شخص |
people.sync.completed | تكتمل مزامنة CSV متصلة | أعداد |
people.sync.failed | تفشل مزامنة CSV متصلة بأمان | خطأ |
report.delivered | يعمل تقرير مجدول من التقارير والتحليلات، مشترك مع المنشأة، مع التسليم إلى webhooks مختارة (التقرير الخاص لا يُرسل أبدًا إلى webhooks)؛ اشترك فيه في الإعدادات، للمطورين (لا يستطيع مفتاح API الاشتراك فيه) | كل عمود يسمّيه التقرير وما يصل إلى 5,000 صف، أو كل مجموعة |
queue.ticket_joined | ينضم شخص إلى طابور، من هاتفه أو من كشك أو من المكتب أو عبر API | تذكرة Queue |
queue.ticket_called | يُستدعى شخص إلى شباك، أو يُستدعى مرة أخرى | تذكرة Queue |
queue.ticket_served | يُحدَّد شخص على أنه خُدم | تذكرة Queue |
queue.ticket_no_show | يُحدَّد شخص استُدعي على أنه لم يحضر، من الفريق أو بعد دقائق الطابور | تذكرة Queue |
queue.ticket_left | يغادر شخص الطابور من تذكرته، أو يُخرجه الفريق | تذكرة Queue |
queue.ticket_transferred | يُنقل شخص إلى طابور أو شباك آخر | تذكرة Queue |
queue.ticket_closed | تُغلق تذكرة ما زالت مفتوحة في نهاية يوم المنشأة، أو في طابور مؤرشف | تذكرة Queue |
queue.booking_created | يحجز شخص وقتًا في صفحة الأوقات المحجوزة لطابور، أو يحجزه API | حجز Queue |
queue.booking_cancelled | يُلغى وقت محجوز، من الشخص أو الفريق أو API | حجز Queue |
queue.ticket_arrived | يقول شخص انضم قبل وصوله إنه هنا، أو يحدّده الفريق على أنه وصل | تذكرة Queue |
queue.message_received | يكتب شخص في الطابور إلى الفريق من صفحة تذكرته؛ والحدث لا يحمل كلمات | رسالة Queue |
queue.message_sent | يكتب الفريق إلى شخص في الطابور؛ والحدث لا يحمل كلمات | رسالة Queue |
queue.survey_answered | يجيب شخص خُدم عن الاستبيان؛ والحدث يحمل التقييم ولا يحمل التعليق أبدًا | إجابة استبيان Queue |
{"id":"evt_…","type":"claim.created","created":"2026-09-23T14:30:00+00:00",
"venue":{"code":"harbourhotel","name":"Harbour Hotel"},"data":{ …the claim… }}
تحقق من التوقيع
تحمل كل عملية تسليم Vfound-Signature: t=<unix time>,v1=<hex>، حيث hex هو HMAC SHA256 لـ t + "." + raw body بالسر الخاص بنقطة النهاية لديك. ارفض عمليات التسليم الأقدم من خمس دقائق. بعد أن تنشئ سرًا موقِّعًا جديدًا، تحمل عمليات التسليم قيمتين لـ v1 لمدة 24 ساعة، واحدة لكل سر، فاقبل التسليم إذا طابقت أي منهما.
// Node.js
const crypto = require("crypto");
function verified(rawBody, header, secret) {
const parts = header.split(",").map((p) => p.split("="));
const t = (parts.find(([k]) => k === "t") || [])[1];
const expected = crypto.createHmac("sha256", secret).update(t + "." + rawBody).digest("hex");
const fresh = Math.abs(Date.now() / 1000 - Number(t)) < 300;
return fresh && parts.some(([k, v]) => k === "v1" && v.length === expected.length
&& crypto.timingSafeEqual(Buffer.from(expected), Buffer.from(v)));
}
// PHP
$t = null; $signatures = [];
foreach (explode(',', $header) as $part) {
[$k, $v] = array_pad(explode('=', $part, 2), 2, '');
if ($k === 't') { $t = $v; } elseif ($k === 'v1') { $signatures[] = $v; }
}
$expected = hash_hmac('sha256', $t.'.'.$rawBody, $secret);
$ok = abs(time() - (int) $t) < 300
&& count(array_filter($signatures, fn ($s) => hash_equals($expected, $s))) > 0;
تتضمن الترويسات أيضًا Vfound-Event ومعرّف Vfound-Delivery فريدًا يمكنك استخدامه لتجاهل التكرارات. تُرسل webhooks إلى عناوين HTTPS العامة فقط وعلى المنفذ 443.
الاشتراك عبر API
تستطيع أدوات مثل Zapier إضافة عناوينها الخاصة وإزالتها بمفتاح يحمل webhooks:manage. يظهر السر الموقِّع مرة واحدة، في إجابة POST. وتحمل الاستجابة أيضًا ترويسة Location فيها العنوان الذي يُستدعى بـ DELETE عند إزالة الاشتراك.
يستطيع المفتاح الاشتراك فقط في الأحداث التي يمكنه قراءة بياناتها: يحتاج كل حدث إلى نطاق القراءة الخاص بمنتجه (items:read لأحداث الأغراض، وclaims:read لأحداث طلبات الاسترداد، وlost_reports:read وparcels:read وcheckroom:read، وloans:read لأحداث المعدات، وvisitors:read لأحداث الزيارة ونوع الزائر والكشك وساعي الشحن، وpeople:read لأحداث الشخص وقائمة الأشخاص). ويسرد المفتاح ويزيل فقط العناوين التي أنشأها بنفسه؛ والعناوين المضافة في الإعدادات، أو بمفتاح آخر، لا تظهر له.
| الطلب | ما يفعله | النطاق |
|---|---|---|
| GET/webhooks | العناوين التي أنشأها هذا المفتاح وأحداثها. | webhooks:manage |
| POST/webhooks | أضف عنوانًا: url (HTTPS عام على المنفذ 443) وevents، قائمة بالأحداث أعلاه التي يستطيع المفتاح قراءتها. | webhooks:manage |
| DELETE/webhooks/{id} | أزل عنوانًا أنشأه هذا المفتاح وسجل تسليماته. | webhooks:manage |
سجل التسليم
تسرد الإعدادات، للمطورين، كل عملية تسليم إلى كل عنوان خلال آخر 30 يومًا، مع كيف جرت، وتعيد إرسال أي منها بمعرّف Vfound-Delivery نفسه. وهناك يمكنك أيضًا تعديل عنوان وإعادة تشغيل عنوان موقوف وإنشاء سر موقِّع جديد. العنوان الذي تفشل 15 عملية تسليم له متتالية يُوقف، ويتلقى مالك المنشأة بريدًا إلكترونيًا.
موجز بيانات التقارير (Power BI)
ينشئ المالك أو المدير رابط موجز في التقارير والتحليلات، تحت موجز بيانات Power BI، للمنتجات التي يختارها. يظهر الرابط مرة واحدة. في Power BI اختر Get data ثم Web والصقه. يقرأ كل رابط منشأة واحدة فقط، ويتوقف فورًا عند إلغائه، أو عندما لا يعود من أنشأه مالكًا أو مديرًا للمنشأة، أو عندما تُوقف المنشأة مؤقتًا أو تُغلق.
GET /api/feeds/reports/{token}/{dataset} يجيب بصفوف مجموعة بيانات واحدة: equipment_loans أو equipment_activity أو visits أو checkroom_tickets. اختر فترتها بـ days (من 1 إلى 366، و90 عند حذفها) أو بـ from وto (YYYY-MM-DD، بتوقيت المنشأة). GET /api/feeds/reports/{token}/saved/{id} يجيب بتقرير محفوظ مشترك مع المنشأة كلها، لفترة ذلك التقرير نفسه؛ ولا تغيّره days وfrom وto. ويمكنك أيضًا إرسال الرمز كـ Authorization: Bearer <token> إلى /api/feeds/reports/{dataset} أو /api/feeds/reports/saved/{id}. تحتوي إجابة واحدة على ما يصل إلى 100,000 صف في value، فيقرأ Get data وWeb النتيجة كاملة؛ ثم حوّل قائمة value إلى جدول. وتنتهي الإجابة بـ total وtruncated: عندما يطابق صفوف أكثر مما تحتويه إجابة واحدة، تكون truncated قيمتها true وتسمّي @odata.nextLink الباقي ($top و$skip يتنقلان بين الصفحات، للأدوات التي تتبعه)؛ أما Get data وWeb فلا يتبعه، فاختر فترة أقصر بدلًا من ذلك. وعندما يحتاج تقرير إلى قراءة أكثر من 400,000 صف أو أكثر من 20 ثانية، تنتهي الإجابة بـ error وtotal قيمتها null وtruncated قيمتها true؛ ويجيب تقرير محفوظ مجمّع بـ 422 مع السبب بدلًا من ذلك. تأتي الصفوف بالترتيب الذي سُجّلت به. الأوقات في الصفوف بالتوقيت العالمي UTC (ISO 8601)؛ والتقرير المحفوظ المجمّع حسب تاريخ يسمّي كل مجموعة باليوم أو الأسبوع أو الشهر أو يوم الأسبوع أو الساعة بتوقيت المنشأة. وتُستثنى عناوين البريد الإلكتروني واسم ضيف Checkroom وغرفته ما لم يُنشأ الرابط ليتضمن بيانات التواصل.
مساعدو الذكاء الاصطناعي (MCP)
vFound خادم Model Context Protocol على https://vfound.io/api/mcp، لتتمكن مساعدات الذكاء الاصطناعي من البحث عن الأشياء والمساعدة عند المكتب. اربط واحدًا بإحدى طريقتين: سجّل الدخول بـ vFound، للمساعدات التي تسجّل موصّلاتها الدخول بـ OAuth، أو بمفتاح API، للعملاء الذين يرسلون ترويسة، مثل Claude Code وCursor وVisual Studio Code. وفي الحالتين يرى الأدوات التي تسمح بها نطاقاته فقط، للمنتجات المفتوحة في منشأتك. ويجوز لعميل مرتبط بمفتاح API أن يرسل أيضًا X-Acting-User؛ وعندها تعمل كل أداة باسم عضو الفريق ذاك، ضمن دوره.
# Claude Code
claude mcp add --transport http vfound https://vfound.io/api/mcp \
--header "Authorization: Bearer $VFOUND_KEY"
// Cursor (.cursor/mcp.json)
{"mcpServers":{"vfound":{"url":"https://vfound.io/api/mcp","headers":{"Authorization":"Bearer vf_live_…"}}}}
// Visual Studio Code (.vscode/mcp.json)
{"servers":{"vfound":{"type":"http","url":"https://vfound.io/api/mcp","headers":{"Authorization":"Bearer vf_live_…"}}}}
| الأداة | ما يفعله | النطاق |
|---|---|---|
search_found_items | ابحث عن الأغراض المعثور عليها بكلمات مثل «iPhone أسود» | items:read |
list_expected_visitors | الزوار المدعوون ولم يصلوا بعد | visitors:read |
list_visitors_on_site | الزوار المسجّلون حاليًا | visitors:read |
list_visitor_types | أنواع الزوار وقواعدها | visitors:read |
visitor_analytics | إجماليات الزوار وأنماطهم ومتوسط مدة البقاء | visitors:read |
visitor_registration_link | رابط التسجيل الذاتي للمنشأة | visitors:read |
list_couriers_on_site | سعاة الشحن المسجّلون عبر Visitors | parcels:read |
list_waiting_parcels | الطرود المنتظرة الاستلام | parcels:read |
detect_parcel_tracking | طبّع رقم تتبع واكتشف شركة الشحن الخاصة به | parcels:read |
parcel_pickup_queue | الأشخاص المنتظرون عند مكتب الطرود | parcels:read |
parcel_shelves | سعة أرفف الطرود وإشغالها | parcels:read |
parcel_analytics | حجم الطرود وشركات الشحن وأداء الاستلام | parcels:read |
list_outgoing_parcels | الطرود الصادرة وحالة تسليمها | parcels:read |
list_parcel_rounds | جولات توزيع الطرود ومحطاتها | parcels:read |
list_checkroom_exit_queue | التذاكر التي ينتظر ضيوفها عند المخرج | checkroom:read |
mark_checkroom_ready | حدّد تذكرة منتظرة على أنها جاهزة وأبلغ الضيف | checkroom:write |
list_checkroom_stations | محطات Checkroom ونطاقات الأرقام | checkroom:read |
list_checkroom_events | فعاليات Checkroom الأخيرة والقادمة | checkroom:read |
checkroom_report | حجم Checkroom ووقت الإرجاع وإجماليات الرسوم | checkroom:read |
list_queue_lines | الطوابير والأشخاص المنتظرون والانتظار المقدّر الآن | queue:read |
list_queue_waiting | الأشخاص المنتظرون اليوم، بترتيب الاستدعاء | queue:read |
queue_report | إجماليات Queue ووسيط دقائق الانتظار والخدمة | queue:read |
call_next_in_queue | استدعِ الشخص التالي إلى شباك | queue:write |
mark_queue_ticket_served | حدّد الشخص عند الشباك على أنه خُدم | queue:write |
list_overdue_equipment | المعدات التي تجاوزت موعد إعادتها ومن لديه كل منها | loans:read |
list_equipment_kits | مجموعات معدات محفوظة | loans:read |
create_equipment_kit | احفظ مجموعة معدات قابلة لإعادة الاستخدام دون صرفها | loans:write |
list_equipment_reservations | الحجوزات حسب الوقت والحالة | loans:read |
reserve_equipment | احجز غرضًا أو فئة دون صرفها | loans:write |
book_repeating_reservation | احجز غرضًا أو فئة أو مساحة كل يوم أو أسبوع | loans:write |
move_reservation | انقل حجزًا إلى أوقات جديدة أو غرض آخر من فئته | loans:write |
list_waitlist | الأشخاص المنتظرون وقتًا حُجز | loans:read |
join_waitlist | أضف شخصًا إلى قائمة الانتظار | loans:write |
list_space_bookings | كل غرفة أو مكتب أو موقف سيارات وحجوزاته بين وقتين | loans:read |
book_space | احجز غرفة أو مساحة لشخص ووقت؛ ولا تُصرف أبدًا | loans:write |
list_equipment_rules | قواعد الصرف للمنشأة وللفئات | loans:read |
save_equipment_rule | أنشئ قاعدة فئة أو استبدلها | loans:write |
list_equipment_maintenance | سجل صيانة المعدات والأعمال القادمة | loans:read |
list_equipment_service_plans | جداول الصيانة والمعايرة واختبار السلامة والفحص والتنظيف المتكررة وما يستحق منها | loans:read |
update_equipment_work_order | غيّر أمر عمل لمعدات أو أغلقه | loans:write |
get_equipment_maintenance_costs | تكلفة الصيانة والإصلاح والتنظيف لكل غرض | loans:read |
get_equipment_valuation | قيمة المعدات في تاريخ ما بعد الإهلاك (للمالكين والمديرين) | loans:read |
list_equipment_substances | سجل المواد الخطرة: المادة والمكان وفئات الخطر وتواريخ المراجعة (سجل، دون نصيحة تخص السلامة) | loans:read |
get_equipment_funding | ما اشتراه كل صندوق أو منحة أو مركز تكلفة وما حُمّل عليه من أعمال (للمالكين والمديرين) | loans:read |
get_equipment_planner | الأعمال المجدولة وأوامر العمل المفتوحة حسب يوم المنشأة نفسها | loans:read |
list_equipment_licences | تراخيص المعدات مع المقاعد وتواريخ الانتهاء (للمالكين والمديرين) | loans:read |
get_equipment_expiries | التأمين والتراخيص التي تنتهي قريبًا أو انتهت بالفعل (للمالكين والمديرين) | loans:read |
log_equipment_maintenance | سجّل صيانة أو معايرة أو اختبار سلامة أو فحصًا أو تنظيفًا أو إصلاحًا أو ملاحظة | loans:write |
list_equipment_stocktakes | عمليات الجرد الأخيرة وأعدادها | loans:read |
start_equipment_stocktake | ابدأ جردًا | loans:write |
scan_equipment_stocktake | سجّل غرضًا واحدًا في جرد مفتوح | loans:write |
scan_many_equipment_stocktake | عُدّ عدة رموز في جرد مفتوح دفعة واحدة | loans:write |
finish_equipment_stocktake | أنهِ جردًا وأرجع ما هو مفقود | loans:write |
list_equipment_transfers | عمليات النقل الواردة والصادرة دون بيانات من يستلم المعدات | loans:read |
preview_equipment_import | تحقق من ملف CSV للمعدات دون حفظه | loans:write |
find_person | ابحث عن شخص في قائمة الأشخاص | people:read |
export_people | صدّر قائمة الأشخاص بصيغة CSV آمنة من الصيغ | people:read |
directory_sync_status | افحص اتصال CSV المحفوظ وآخر تشغيل له | people:read |
run_directory_sync | شغّل اتصال CSV المحفوظ الآن | people:write |
email_my_vfound | أرسل إلى شخص صفحته الخاصة الموقّعة بالبريد الإلكتروني | people:write |
invite_visitor | ادعُ زائرًا، يتلقى تصريحًا بالبريد الإلكتروني | visitors:write |
approve_visit | وافق على طلب زيارة معلّق | visitors:write |
list_free_workplace_spaces | ابحث عن مكاتب أو غرف اجتماعات أو مواقف خالية لوقت ما | visitors:read |
book_workplace_space | احجز مكتبًا أو غرفة اجتماعات أو موقف سيارات لشخص | visitors:write |
request_visit_catering | اطلب ضيافة مع زيارة، من الخيارات التي تسردها المنشأة | visitors:write |
list_appointment_pages | اسرد صفحات المواعيد في المنشأة وهل كل منها مفتوحة للزوار | visitors:read |
list_staff_on_site | اسرد الأشخاص في قائمة الموظفين المسجّلين حاليًا، في المكتب أو عن بُعد | visitors:read |
sign_staff_in_or_out | سجّل حضور شخص من قائمة الموظفين أو خروجه | visitors:write |
list_visitor_assets_not_returned | اسرد الأشياء المسلَّمة للزوار التي لم تُحدَّد على أنها أُعيدت بعد | visitors:read |
issue_visitor_asset | سجّل شيئًا سُلّم لزيارة متوقعة أو مسجّلة الحضور | visitors:write |
return_visitor_asset | حدّد شيئًا سُلّم لزيارة على أنه أُعيد | visitors:write |
start_roll_call | ابدأ حصر الحضور النشط أو أعده | visitors:write |
mark_visitor_safe | حدّد زائرًا واحدًا على أنه آمن | visitors:write |
create_kiosk_pairing | أنشئ رمز اقتران كشك لمدة عشر دقائق | visitors:write |
log_parcel | سجّل طردًا وأرسل بريدًا إلكترونيًا إلى المستلم | parcels:write |
remind_parcel | ذكّر مستلمًا باستلام طرد | parcels:write |
remind_parcels | ذكّر ما يصل إلى 200 مستلم طرود محددين | parcels:write |
log_outgoing_parcel | أضف طردًا صادرًا إلى سجل شركات الشحن | parcels:write |
create_parcel_round | أنشئ جولة توزيع من الطرود المنتظرة | parcels:write |
extend_loan | امنح مستلم المعدات وقتًا أكثر | loans:write |
تنفّذ كل أداة طلب API أعلاه بالفحوص نفسها، فلا يستطيع مساعد أبدًا أن يفعل أكثر مما يسمح به مفتاحه أو اتصاله. لا توجد أدوات تسلّم أي شيء أو تسجّل حضور أحد أو خروجه أو تبتّ في طلب استرداد أو تحذف. وتُحتسب كل إجابة ضمن 120 طلبًا في الدقيقة الخاصة بالمفتاح أو الاتصال.
سجّل الدخول بـ vFound
أضف https://vfound.io/api/mcp كموصّل في مساعدك الخاص. يجد المساعد طريقة تسجيل الدخول بنفسه ويفتح صفحة vFound، حيث يسجّل المالك أو المدير الدخول إلى مساحة عمله كالمعتاد، ويختار المنشأة ويرى بكلمات واضحة ما يجوز للمساعد فعله، ويمكنه إلغاء تحديد أي شيء. لا يستطيع الموظفون والأعضاء ذوو صلاحية العرض فقط ربط مساعد. المساعد خاص بمنشأتك: اشتراكك مع مزوّده يدفع ثمن ذكائه الاصطناعي، ولا يتلقى vFound إلا طلبات الأدوات التي يرسلها.
يعمل الاتصال باسم الشخص الذي سمح به، بالفحوص نفسها المطبّقة على مفتاح API: يتوقف عن العمل إذا لم يعد ذلك الشخص يدير المنشأة أو إذا لم تكن المنشأة نشطة، ولا يغيّر شيئًا ما دام الاشتراك موقوفًا مؤقتًا، ولا يرى أدوات إلا للمنتجات المفتوحة. يدوم رمز الوصول الخاص به ساعة واحدة ويجدده المساعد بنفسه؛ والاتصال غير المستخدم لمدة 30 يومًا يسجّل الدخول من جديد. شاهد كل اتصال ومن ربطه ومتى استُخدم آخر مرة في الإعدادات، للمطورين، حيث يوقفه قطع الاتصال فورًا. يعمل الرمز على نقطة نهاية MCP فقط، لا على REST API؛ والتطبيق الذي يحتاج إلى REST API يتصل كما يقول القسم التالي.
لمطوري العملاء: OAuth 2.1 كما تصفه مواصفة تفويض MCP، مع تدفق رمز التفويض وPKCE (S256) فقط. الاكتشاف: /.well-known/oauth-protected-resource (RFC 9728، المورد https://vfound.io/api/mcp) و/.well-known/oauth-authorization-server (RFC 8414)؛ والطلب بلا رمز يتلقى ترويسة WWW-Authenticate تسمّي الأول. تسجّل العملاء أنفسهم في /oauth/register (RFC 7591) كعملاء عامين دون سر؛ ويجب أن تستخدم عناوين إعادة التوجيه https، أو http فقط لـ localhost أو 127.0.0.1، وأن تطابق عندئذ تمامًا. ثم /oauth/authorize و/oauth/token (تدوم الرموز 60 ثانية وتعمل مرة واحدة؛ وتُستبدل رموز التحديث عند كل استخدام، وإعادة استخدام رمز قديم تقطع اتصال المساعد) و/oauth/revoke (RFC 7009). تستخدم النطاقات أسماء مفاتيح API أعلاه؛ وأرسل resource=https://vfound.io/api/mcp (RFC 8707).
سجّل الدخول بـ vFound لتطبيقات أخرى
يستطيع تطبيق ليس مساعدًا للذكاء الاصطناعي، مثل نظام مخزون أو حجوزات أو موارد بشرية، الاتصال بـ REST API بالطريقة نفسها بدلًا من مفتاح API: أرسل resource=https://vfound.io/api/v1 إلى /oauth/authorize و/oauth/token، مع نطاقات بأسماء مفاتيح API، باستثناء webhooks:manage الذي لا يمكن منحه لتطبيق. يسجّل المالك أو المدير الدخول، ويرى اسم التطبيق وما يجوز له فعله بكلمات واضحة، ويمكنه إلغاء تحديد أي شيء ثم يسمح به. يعمل الاتصال باسم ذلك الشخص بالفحوص نفسها المطبّقة على مفتاح API: يتوقف عن العمل إذا لم يعد يدير المنشأة أو إذا لم تكن المنشأة نشطة، ولا يغيّر شيئًا ما دام الاشتراك موقوفًا مؤقتًا، ويجوز له إرسال 120 طلبًا في الدقيقة، مثل المفتاح. يعمل X-Acting-User مع مفتاح API فقط. يعمل رمز الوصول الخاص به على REST API فقط، ولا يعمل أبدًا على نقطة نهاية MCP، وموافقة تُعرض لأحدهما لا توافق أبدًا على الآخر. يُسرد في الإعدادات، للمطورين كتطبيق يستخدم واجهة vFound البرمجية، حيث يوقفه قطع الاتصال فورًا. الاكتشاف: /.well-known/oauth-protected-resource/api/v1؛ والباقي هو التدفق أعلاه.
الأخطاء
الأخطاء بصيغة JSON مع message؛ وأخطاء التحقق تضيف errors حسب الحقل. 401 تعني عدم وجود مفتاح صالح، و403 نطاقًا ناقصًا، أو مفتاحًا لم يعد منشئه يدير المنشأة، أو عضو فريق في X-Acting-User ليس عضوًا نشطًا أو لا يسمح دوره بالنطاق، أو منشأة غير نشطة، أو تغييرًا أُرسل بينما الاشتراك موقوف مؤقتًا، و404 غير موجود في منشأتك، و422 مدخلات غير صالحة و429 طلبات كثيرة جدًا.
عندما يتعذّر تغيير بسبب الحالة الحالية للسجل، تكون الإجابة 422 مع code ثابت أيضًا. أسماء الأكواد لا تتغير أبدًا:
| الكود | ماذا يعني |
|---|---|
parcel_not_waiting | لم يعد الطرد منتظرًا: فقد استُلم أو أُعيد أو سُلّم بالفعل. |
tracking_duplicate | يوجد هنا بالفعل طرد منتظر بهذا الرقم للتتبع. |
no_email | ليس لدى الشخص أو الزائر عنوان بريد إلكتروني، فلا يمكن إرسال شيء. |
capacity_full | كل أرقام Checkroom مستخدمة. |
already_checked_in | تذكرة Checkroom مسجَّل استلامها بالفعل. |
already_handed_back | تذكرة Checkroom سُلّمت بالفعل. |
nothing_to_hand_back | ليس في تذكرة Checkroom ما يُسلَّم. |
number_in_use | رقم Checkroom هذا مستخدم بالفعل. |
ticket_closed | لا يمكن إرسال بريد إلكتروني إلا لتذكرة Checkroom مفتوحة. |
item_out | المعدات عند شخص. استلمها عائدةً أولًا. |
item_in_repair | المعدات موضوعة جانبًا للإصلاح. |
item_retired | المعدات مسحوبة من الخدمة، فلا يمكن صرفها ولا حجزها. |
reservation_conflict | حجز شخص الغرض، أو آخر غرض حر في فئته، خلال هذا الوقت، أو يُتوقع أن يظل خارجًا. |
already_back | المعدات استُلمت عائدة بالفعل. |
not_out | المعدات ليست خارجة، فلا يمكن منحها وقتًا أكثر أو تذكيرًا أو تحديدها على أنها لن تعود. |
borrower_overdue | لدى مستلم المعدات معدات متأخرة، والمنشأة أو الفئة لا تسمح بشيء آخر إلى أن تعود. |
borrower_item_limit | هذا سيمنح مستلم المعدات أغراضًا أكثر مما تسمح به المنشأة أو الفئة في وقت واحد. |
reservation_not_ready | الحجز غير موافَق عليه بعد، أو استُلم أو أُلغي بالفعل. |
reservation_item_mismatch | عملية الصرف لا تتضمن الغرض الذي أُجري الحجز له. |
reservation_category_mismatch | عملية الصرف تتضمن غرضًا خارج الفئة المحجوزة. |
reservation_borrower_mismatch | الحجز يعود إلى مستلم معدات مختلف. |
reservation_too_long | الحجز أطول من المدة التي يمكن بها استلام الفئة. لا تُقيَّد بهذه الطريقة إلا الحجوزات المُجراة من My vFound. |
reservation_daily_limit | أجرى مستلم المعدات بالفعل 5 حجوزات من My vFound خلال آخر 24 ساعة. |
booking_notice | يبدأ الحجز قبل ما يسمح به الحد الأدنى للإشعار المسبق للفئة. |
booking_too_far_ahead | ينتهي الحجز أو الصرف أو موعد الإعادة الجديد بعد أبعد مدى يمكن حجز الفئة فيه مسبقًا. |
desk_closed | سيبدأ الحجز في يوم يكون فيه مكتب المعدات مغلقًا. |
kit_unavailable | جزء من مجموعة معدات أو سلة غير متاح لهذا الوقت، فلم يُحجز شيء. يسرد الحقل unavailable كل جزء وسببه. |
borrower_not_in_group | تسمح المنشأة بالاستلام أو الحجز فقط للأشخاص الذين لديهم نوع من أنواع مستلمي المعدات، وهذا المستلم ليس في أي منها (أو أُدخل بالكتابة بدل اختياره من قائمة الأشخاص). |
category_not_allowed | لا يسمح أي من أنواع مستلمي المعدات الخاصة بهذا المستلم بهذه الفئة. |
borrower_on_hold | الاستلام موقوف لهذا الشخص: وضع الموظفون تعليقًا، أو توقف المنشأة الاستلام بعد تأخر متكرر في الإعادة، أو عليه مبلغ يساوي على الأقل ما تحجب المنشأة عنده (رسوم من النوع charges). يعطي الحقل hold نوعه وحتى متى. |
space_too_small | عدد الأشخاص أكبر مما تتسع له الغرفة أو المساحة (سعتها). |
kit_locked | المعدات تنتمي إلى مجموعة معدات مقفلة، لا تُصرف إلا كاملة: ضمّن كل غرض مسمّى في المجموعة. |
approval_not_yours | حددت المنشأة جهات موافقة بترتيب وهذا الشخص ليس التالي (أو أن المنشأة لا تسمح لأحد بتخطي خطوة من أجله). |
project_not_approved | الحجز يتبع مشروعًا غير موافَق عليه بعد، فلا يمكن استلام شيء. |
not_enough_credits | تستخدم المنشأة أرصدة الحجز وهذا الشخص لم يبق له رصيد. امنحه بعضًا أولًا. والحجز الملغى أو الذي لم يُستلم أبدًا يعيد رصيده. |
risk_assessment_pending | للحجز تقييم مخاطر لم يُوافَق عليه، فلا يمكن استلام شيء. |
series_unavailable | تعذّر إنشاء حجز متكرر لأن وقتًا واحدًا منه على الأقل محجوز أو يخالف قاعدة حجز، فلم يُحجز شيء. يسرد الحقل skipped كل وقت وسببه. |
time_available | الوقت الذي طلب شخص انتظاره خالٍ، فاحجزه بدلًا من الانضمام إلى قائمة الانتظار. |
space_not_handed_out | الغرفة أو المساحة محجوزة لوقتها ولا تُصرف أبدًا، فلا يمكن صرفها ولا استلامها. |
stock_short | لا يوجد من بند المخزون هذا ما يكفي في المكان (والدفعة) المسمّيين، فلم يتغير شيء. يعطي الحقل available الكمية الموجودة هناك. |
stock_issue_closed | كل ما صُرف في عملية صرف المخزون هذه عاد أو شُطب بالفعل. |
order_closed | أمر شراء انتهى أو أُلغي ولا يمكن تغييره. |
order_over_received | أُدخل أكثر مما لا يزال بند أمر الشراء ينتظره. |
order_not_placed | لا يمكن استلام مخزون مقابل أمر شراء ما زال مسودة. |
fees_off | الرسوم معطّلة لهذه المنشأة. فعّلها أولًا في سياسة المكتب والاستلام. |
entry_closed | لم يعد بالإمكان تغيير إدخال الرسوم أو الفاتورة بهذه الطريقة: الرسم سُدّد أو أُعفي منه، أو الدفعة أُبطلت، أو الوديعة رُدّت أو استُبقيت، أو الفاتورة مُبطلة. |
on_invoice | الرسم على فاتورة صادرة. أبطل الفاتورة أولًا، ثم أعفِ من الرسم. |
not_late | لم تعد عملية الصرف متأخرة وفق قواعد غرامة التأخير في المنشأة، أو أنها ما زالت خارجة. |
nothing_to_invoice | ليس على مستلم المعدات رسم مفتوح بتلك العملة غير موجود أصلًا على فاتورة صادرة. |
charge_unavailable | أحد الرسوم المختارة غير مفتوح، أو على فاتورة أخرى أو لشخص آخر. |
desk_kept | المكتب محجوز لشخص آخر في أحد الأيام المطلوبة. |
desk_has_bookings | حجز المكتب لهذا الشخص سيتعارض مع حجوزات مفتوحة لآخرين في تلك الأيام. ألغِها أولًا. |
booking_closed | حجز المكتب أو الغرفة أو الموقف أُلغي أو أُفرج عنه، فلا يمكن تسجيل الحضور له. |
check_in_closed | يفتح تسجيل الحضور قبل بدء الحجز بـ 15 دقيقة ويُغلق عند انتهائه. |
item_service_due | تمنع المنشأة خروج المعدات التي تحتاج إلى عمل، وقد حل تاريخ صيانة هذا الغرض أو استحق أحد جداوله. سجّل العمل أولًا. |
item_failed_inspection | تمنع المنشأة خروج المعدات التي تحتاج إلى عمل، وفشل آخر فحص لهذا الغرض. سجّل نجاحًا أولًا. |
work_order_closed | أمر العمل هذا مغلق بالفعل ولا يمكن تغييره. |
already_disposed | تم التخلص من هذا الغرض بالفعل. |
not_disposed | لم يتم التخلص من هذا الغرض، فلا شيء يُتراجع عنه. |
item_disposed | تم التخلص من هذا الغرض. تراجع عن التخلص قبل استخدامه مرة أخرى. |
training_required | قاعدة فئة أو الغرض يشترط تدريبًا لا يحمله مستلم المعدات، أو يحمله لكن بعد تاريخ انتهائه. يسمّي الحقل training ما ينقص. |
stocktake_open | هناك جرد مفتوح بالفعل. أنهِه أولًا. |
item_unavailable | المعدات غير متاحة أو موضوعة جانبًا للإصلاح، فلا يمكن أن تبدأ نقلًا. |
transfer_open | للمعدات نقل مفتوح بالفعل. |
transfer_not_ready | لا يمكن إرسال إلا نقل مجهّز. |
transfer_not_in_transit | لا يمكن استلام أو تحديد مشكلة إلا للمعدات التي في الطريق. |
transfer_already_sent | لم يعد بالإمكان إلغاء نقل مُرسَل أو رفضه. |
already_signed_in | الزائر مسجّل الحضور بالفعل. |
visit_closed | الزيارة مغلقة. سجّل حضور الزائر كزيارة جديدة. |
not_signed_in | الزائر غير مسجّل الحضور. |
not_expected | لا يمكن إلغاء أو إرسال تصريح إلا لزيارة متوقعة. |
approval_required | تحتاج الزيارة إلى موافقة قبل أن يسجّل الزائر حضوره. |
visit_not_valid_today | لا يمكن استخدام التصريح مرة أخرى اليوم، أو أن اليوم خارج تواريخه. |
plus_one_not_allowed | التصريح لا يسمح بضيوف، أو لم يعد موافَقًا عليه أو متوقعًا أو صالحًا. |
plus_one_limit | أضاف الزائر كل الضيوف الذين يسمح بهم التصريح. |
nobody_to_sign_in | لا أحد في مجموعة الزيارة متوقع اليوم. |
visitor_capacity_full | تسجيل حضور الزائر سيتجاوز حد المنشأة أو نوع الزائر لعدد الزوار المسجّلين في وقت واحد. |
تسجيل حضور زائر عند المكتب يجيب بـ 409 مع code عندما يحتاج الزائر إلى فحص من عضو في الفريق أولًا. تسمّي الإجابة نوع التطابق فقط (blocklist أو building أو restricted_party أو answers)؛ أما الإدخال واسمه وسببه فهي لفريق المنشأة، ولا تظهر أبدًا في إجابة API. أعد إرسال الطلب مع ضبط screening_reviewed على true فقط بعد أن يفحص عضو في الفريق التطابق. ويتطلب ذلك مفتاحًا يحمل نطاق visitors:screening (معطّل افتراضيًا، مثل وصول أي مفتاح آخر إليه)، وأن يكون عضو الفريق الذي يسميه المفتاح في X-Acting-User ممن يبتّ دوره في الزيارات. يُسجَّل التأكيد باسم المفتاح، لا باسم عضو الفريق الذي أنشأ المفتاح أبدًا. وبدون النطاق تكون الإجابة 403 مع screening_scope. وينطبق الأمر نفسه على الموافقة على زيارة يوقفها تطابق:
| الكود | ماذا يعني |
|---|---|
screening_match | يطابق الزائر إحدى قوائم الحظر في المنشأة، أو فحصًا من الفريق، أو قائمة الفحص. يجب أن يؤكد عضو في الفريق أنه فحص التطابق قبل تسجيل حضور الزائر. |
screening_scope | يؤكد الطلب تطابق فحص أو يوافق عليه، ولا يملك المفتاح نطاق visitors:screening (أو أن عضو الفريق المسمّى في X-Acting-User لا يبتّ في الزيارات). |
قوائم التحقق لسير العمل
تستطيع منشأة على vFound Enterprise ضبط الخطوات التي يؤكدها موظفوها في لحظة مفصلية: تسجيل غرض معثور عليه أو تسليمه أو التبرع به أو التخلص منه؛ وتسليم طرد أو إعادته؛ وتسجيل الاستلام أو التسليم في Checkroom؛ وصرف المعدات أو استلامها عائدة؛ وتسجيل حضور زائر أو خروجه. وما دامت واحدة منها سارية، تقبل هذه الطلبات حقل checklist: [{"key": "id_checked", "done": true}, {"key": "reason", "note": "Refused"}]، أو كائنًا من مفتاح إلى true أو نص ملاحظة. وتقبله POST /items وPATCH /items/{id} وPOST /items/{id}/disposition وPOST /claims/{id}/handover وPOST /claims/{id}/decision وPOST /parcels/{id}/collect وPOST /parcels/{id}/return وPOST /parcels/bulk-return وPOST /parcels/rounds/{round}/stops/{stop}/deliver وPOST /checkroom/tickets وPOST /checkroom/tickets/{id}/hand-back وPOST /loans وPOST /loans/{id}/return وPOST /loans/returns وPOST /loans/checkouts وPOST /loans/reservations/{id}/pickup وPOST /visitors وPOST /visitors/{id}/sign-in وPOST /visitors/{id}/sign-out. وبدون الخطوات المطلوبة تكون الإجابة 422 مع الكود checklist_incomplete وكائن checklist يسمّي الخطوات التي لا تزال تحتاج إلى تأكيد، ولا يتغير شيء. وعندما لا تسري أي قائمة يُتجاهل الحقل. وقوائم التحقق المكتملة، مع من أكدها ومتى، موجودة في checklists في إجابات الغرض الواحد وطلب الاسترداد والطرد والتذكرة وعملية الصرف والزيارة.
| الكود | ماذا يعني |
|---|---|
checklist_incomplete | 422: تسري قائمة تحقق لسير العمل على هذه الخطوة ولم تُؤكَّد خطواتها المطلوبة. |
إعادة المحاولات بترويسة Idempotency-Key يمكن أن تجيب أيضًا بـ code:
| الكود | ماذا يعني |
|---|---|
idempotency_key_invalid | 400: الترويسة ليست من 1 إلى 191 حرف ASCII مرئيًا. |
idempotency_key_reused | 422: استُخدم هذا المفتاح بالفعل لطلب مختلف. |
idempotency_in_progress | 409: الطلب الأول بهذا المفتاح ما زال قيد التنفيذ. حاول مرة أخرى بعد قليل. |
offline_in_progress | النسخة الأولى من هذا الإجراء غير المتصل ما زالت قيد الحفظ. يعيد الجهاز إرسالها بعد قليل. |
الطلب الذي يسمّي عضو فريق في X-Acting-User يمكن أن يجيب أيضًا بـ code:
| الكود | ماذا يعني |
|---|---|
acting_user_refused | 403: الترويسة لا تسمّي عضو فريق نشطًا واحدًا بالضبط في هذه المنشأة، أو أن المفتاح اتصال أُنشئ بتسجيل الدخول. |
acting_user_role | 403: عضو الفريق المسمّى لا يستطيع استخدام نطاق هذه العملية بدوره في المنشأة. |