الصفحة الرئيسية لـ vFoundاطلب تجربتك المجانية
للمطورين

واجهة 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إضافة سياق الإقامة أو تحديثه من نظام الفندق بصورة idempotentPOST /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.

Oracle OPERA Cloud غير متاح. يبقى محوّل الخادم الذي يفشل بأمان معطّلًا إلى أن يكتمل الوصول إلى Oracle وموافقة الفندق وضبط البيئة بدقة والقبول الفعلي. ولا يُعلن أنه معتمد أو أن العملاء تحققوا منه.

الأغراض

الطلبما يفعلهالنطاق
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}/decisionstatus: 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}/dispositionkind 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سعاة الشحن المسجّلون عبر Visitorsparcels: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_incomplete422: تسري قائمة تحقق لسير العمل على هذه الخطوة ولم تُؤكَّد خطواتها المطلوبة.

إعادة المحاولات بترويسة Idempotency-Key يمكن أن تجيب أيضًا بـ code:

الكودماذا يعني
idempotency_key_invalid400: الترويسة ليست من 1 إلى 191 حرف ASCII مرئيًا.
idempotency_key_reused422: استُخدم هذا المفتاح بالفعل لطلب مختلف.
idempotency_in_progress409: الطلب الأول بهذا المفتاح ما زال قيد التنفيذ. حاول مرة أخرى بعد قليل.
offline_in_progressالنسخة الأولى من هذا الإجراء غير المتصل ما زالت قيد الحفظ. يعيد الجهاز إرسالها بعد قليل.

الطلب الذي يسمّي عضو فريق في X-Acting-User يمكن أن يجيب أيضًا بـ code:

الكودماذا يعني
acting_user_refused403: الترويسة لا تسمّي عضو فريق نشطًا واحدًا بالضبط في هذه المنشأة، أو أن المفتاح اتصال أُنشئ بتسجيل الدخول.
acting_user_role403: عضو الفريق المسمّى لا يستطيع استخدام نطاق هذه العملية بدوره في المنشأة.
هل لديك أسئلة أو حالة استخدام ينبغي أن ندعمها؟ راسلنا بالبريد الإلكتروني. نقرأ كل رسالة.