اربط أداتك بـ The Big One.

في The Big One، ينشئ مدير النظام رمزًا من الإعدادات ‹ التكاملات ‹ وصول المطوّرين، مع اختيار صلاحياته: read (القراءة)، write (الكتابة)، import (الإرسال دفعةً واحدة)، billing (الفوترة، لا تُحدَّد أبدًا تلقائيًا). لا يُعرض الرمز إلا مرة واحدة؛ أنشئ رمزًا لكل أداة لتتمكّن من إلغائها كلٌّ على حدة.

يحمل كل استدعاء الرمز في الترويسة Authorization. تُستنتج الشركة من الرمز: لا حاجة إلى إرسال أي معرّف للشركة.

رمز API محصور في بعض العقارات. لتسليم مفتاح إلى عميل أو شريك، اختر «بعض العقارات» في نافذة رمز API: عميلًا (العقارات التي هو عميلها اليوم، وتتبعه تلقائيًا) أو مباني أو وسومًا أو عقارات مختارة؛ وتُجمع الاختيارات. لا يقرأ رمز API عندئذ إلا ما يخص هذه العقارات (المهام والحجوزات والمشكلات والتقييمات والتوصيلات والبياضات)، ومباني هذه العقارات فقط. يجيب الفريق والإجازات وطلبات البياضات وسجل الإرسال بـ 403؛ وتقتصر القطاعات على قطاعات عقاراته؛ وتجيب المهمة أو العقار خارج الحدود بـ 404. لا يملك رمز API المحصور أبدًا import، ويتطلب billing عميلًا: لا يقرأ عندئذ إلا بطاقة هذا العميل وأسعاره وتقاريره.

المخطط الكامل. يمكن تنزيل مخطط OpenAPI 3.1 للواجهة كلها (المسارات والمعاملات والردود والإشعارات) دون رمز: https://thebigone.io/api/public/v1/openapi.json. إصداره هو تاريخ آخر تغيير، الموصوف في سجل التغييرات أسفل هذه الصفحة.

curl https://thebigone.io/api/public/v1/tasks?from=2026-10-01&to=2026-10-07 \
  -H "Authorization: Bearer cnimp_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"

الحقول بالإنجليزية وبصيغة camelCase، وهي نفسها عند الإرسال والقراءة. يحمل كل عنصر ترسله معرّفك الخاص externalId: إعادة إرسال المعرّف نفسه تحدّث العنصر بدل إنشاء نسخة مكرّرة.

صور الإعلان. في الإرسال دفعةً واحدة، يمكن أن يحمل كل عقار الحقل photos: روابط https:// (أو { url, caption, thumbnailUrl })، والأولى هي الصورة الرئيسية، و60 على الأكثر. تظهر في بطاقة العقار للمكتب ولعمال النظافة. من دون هذا الحقل لا يتغيّر شيء؛ و[] يحذفها.

{ "properties": [ {
  "externalId": "LOG-12",
  "name": "Bastille — 3 pièces",
  "photos": [
    { "url": "https://photos.votre-outil.fr/log-12/salon.jpg", "caption": "Salon" },
    "https://photos.votre-outil.fr/log-12/chambre.jpg"
  ]
} ] }

تُرجع القوائم { data, nextOffset, limit, offset }. ما دامت قيمة nextOffset ليست فارغة، أعد الاستدعاء مع offset=nextOffset (100 عنصر افتراضيًا، و500 كحد أقصى). للمزامنة، احفظ وقت آخر استدعاء لك ومرّره في updatedSince.

عوامل تصفية المهام: from، to، status (created، assigned، in_progress، completed، cancelled)، type، propertyExternalId، validated، updatedSince. لا تُعاد المهام الملغاة (cancelled، غير الظاهرة في التخطيط) إلا مع status=cancelled أو includeCancelled=true؛ وتحمل كل مهمة الحقل inPlanning. أضف include=report,checklist,comments لتتلقى في استدعاء واحد محتوى التقرير وقائمة التحقق وتعليقات كل مهمة (50 مهمة في الصفحة كحد أقصى مع checklist).

{
  "id": "0b9d2c7e-4a6f-4c1e-9f2a-1d3e5b7c9a01",
  "externalId": "MEN-881",
  "type": "cleaning",
  "date": "2026-11-07",
  "startTime": "11:00:00",
  "timezone": "Europe/Paris",
  "startAt": "2026-11-07T11:00:00+01:00",
  "plannedDurationMinutes": 150,
  "plannedEndAt": "2026-11-07T13:30:00+01:00",
  "status": "completed",
  "inPlanning": true,
  "assignees": ["Camille"],
  "startedAt": "2026-11-07T10:12:00Z",
  "endedAt": "2026-11-07T12:05:00Z",
  "completedAt": "2026-11-07T12:05:04Z",
  "validated": true,
  "validatedAt": "2026-11-07T14:20:00Z",
  "property": { "id": "…", "name": "Bastille — 3 pièces", "externalId": "LOG-12" },
  "reservation": { "id": "…", "code": "HMX4K2", "platform": "guesty", "checkoutAt": "2026-11-07T11:00:00+01:00" },
  "nextArrival": { "id": "…", "code": "HMQ81Z", "platform": "guesty", "checkinAt": "2026-11-07T15:00:00+01:00", "guests": 4 },
  "reportUrl": "https://thebigone.io/task/report/…",
  "reportReadyAt": "2026-11-07T12:05:04Z",
  "report": { "summary": { "status": "to_report", "toReport": 2, "checklistItems": 38, "checklistDone": 37 },
    "notDone": [ { "label": "Four : intérieur", "section": "Cuisine", "required": true } ],
    "issues": [ { "category": "leak", "status": "new", "urgent": true } ],
    "inspection": null, "inventory": [], "linenMoves": [] },
  "updatedAt": "2026-11-07T14:20:01Z"
}

الأوقات والتقرير والضيوف. تحمل كل مهمة timezone (المنطقة الزمنية للعقار)، وstartAt وplannedEndAt (التاريخ والوقت كاملين مع فارقهما، مثل 2026-11-07T11:00:00+01:00)، وplannedDurationMinutes وcompletedAt وvalidatedAt. endedAt هو وقت الانتهاء الذي سجّله عامل النظافة، وإلا فلحظة انتهاء المهمة. بمجرد انتهاء المهمة يُملأ reportUrl ويبيّن reportReadyAt منذ متى يمكن الاطلاع على التقرير. يعطي reservation الإقامة المرتبطة (code الحجز، وplatform: البرنامج المصدر، وcheckinAt وcheckoutAt)، ويعطي nextArrival وصول الضيوف التالي إلى العقار.

تفاصيل المهمة. يعطي GET /api/public/v1/tasks/:id كل شيء دفعة واحدة: report (محتوى التقرير)، وchecklist (كل بند من قائمة التحقق مع done وnote وvalue وphotos وreferencePhotos)، وcomments. روابط الصور صالحة لمدة 7 أيام؛ ويبقى رابط التقرير (reportUrl) صالحًا 90 يومًا.

محتوى التقرير. قيمة report.summary.status هي ok أو to_report، ويعدّ toReport البنود الإلزامية غير المنجزة والمشكلات المُبلَّغ عنها أثناء المهمة وفحصًا يجب إعادته. ثم تأتي التفاصيل: notDone وnotes وissues وinspection (الفحص المنجز، وresult: compliant أو redo، والتقييم والملاحظة) وinventory (البياضات والمستهلكات المعدودة أثناء المهمة: الناقصة والمتسخة والمكسورة) وlinenMoves.

"checklist": {
  "name": "Ménage classique",
  "items": [ {
    "id": "…", "label": "Salle de bains : miroir et robinetterie", "section": "Salle de bains",
    "required": true, "kind": "checklist", "done": true, "note": null, "value": null,
    "photos": [ { "url": "https://…", "thumbnailUrl": "https://…", "takenAt": "2026-10-05T12:41:00Z" } ],
    "referencePhotos": []
  } ]
}

المهام المحذوفة. يعرض GET /api/public/v1/tasks/deleted?since=… المهام المحذوفة منذ تلك اللحظة (تُحفظ 90 يومًا): فلا تُخلط أبدًا مهمة غائبة عن صفحة بمهمة محذوفة. وتخرج المهمة المستعادة من سلة المحذوفات من هذه القائمة وتعود إلى /tasks.

عوامل تصفية الحجوزات: from وto وstatus (confirmed وcancelled وblocked — تواريخ مغلقة بلا ضيف) وpropertyExternalId وupdatedSince. المشكلات المُبلَّغ عنها: from وto (يوم الإبلاغ) وstatus (new وin_progress وresolved) وurgent وtaskId وpropertyExternalId وupdatedSince. تقييمات الضيوف: from وto وtaskId وpropertyExternalId وupdatedSince؛ تُحوَّل الدرجات إلى مقياس من 5، وتبقى الدرجة الأصلية في ratingRaw وratingScale.

{
  "id": "7c1e…",
  "category": "leak",
  "urgent": true,
  "description": "Fuite d'eau sous le lavabo",
  "status": "new",
  "reporterName": "Camille",
  "reportedAt": "2026-10-05T12:50:00Z",
  "taskId": "0b9d2c7e-4a6f-4c1e-9f2a-1d3e5b7c9a01",
  "property": { "id": "…", "name": "Bastille — 3 pièces", "externalId": "LOG-12" },
  "photos": [ { "url": "https://…", "thumbnailUrl": "https://…" } ]
}

فئات المشكلة (category): damage (كسر)، breakdown (عطل)، dirt (أوساخ)، linen (البياضات)، pests (آفات)، access (الدخول)، leak (تسرّب)، other (أخرى).

الفريق. يعيد GET /api/public/v1/people لكل شخص id وname (اسم التخطيط) وemail وrole وroles وactivities (cleaning وlinen وinspection وdelivery وmaintenance) وsectors وavailability: الأيام من 1 (الاثنين) إلى 7 (الأحد)، وساعتا البدء والانتهاء، وmaxHours عند تحديد حد أقصى للشخص. عوامل التصفية: role وactivity. لا يُعاد أبدًا رقم الهاتف أو العنوان أو العقد أو الأجر. GET /api/public/v1/time-off: from وto (الإجازات المتداخلة مع الفترة) وstatus (requested وapproved وrefused) وpersonId وupdatedSince؛ ويوجد طلب التعديل أو الإلغاء المعلّق في changeRequest.

{
  "id": "5d2f…",
  "name": "Camille",
  "planningName": "Camille",
  "fullName": "Camille Martin",
  "email": "camille@…",
  "role": "agent",
  "roles": ["agent"],
  "activities": ["cleaning", "linen"],
  "sectors": [ { "id": "…", "name": "Paris Est" } ],
  "availability": [ { "weekday": 1, "startTime": "08:00", "endTime": "16:00", "maxHours": 7 } ]
}

العقارات. يتضمن كل عقار propertyType وcapacity وbedrooms وbathrooms وtimezone وsector وbuilding وtags وclient (العميل الحالي وفق الأسعار، كما في الفاتورة). عوامل تصفية القائمة: active وsectorId وtag وupdatedSince. يضيف GET /api/public/v1/properties/:id الحقول amenities وlistingPhotos وsheet: أقسام بطاقة العقار وحقولها المعبأة. لا يخرج قسم «الدخول» (الرموز، صندوق المفاتيح…) عبر واجهة API.

العنوان. يحمل كل عقار أيضًا addressDetails: street وpostalCode وcity وfull، وهو عنوان العقار نفسه المأخوذ من بطاقته، وليس عنوان المبنى أبدًا.

{
  "id": "…",
  "externalId": "LOG-12",
  "name": "Bastille — 3 pièces",
  "address": "17 rue de la Roquette",
  "addressDetails": { "street": "17 rue de la Roquette", "postalCode": "75011", "city": "Paris", "full": "17 rue de la Roquette 75011 Paris" },
  "propertyType": "apartment",
  "capacity": 6, "bedrooms": 2, "bathrooms": 1,
  "sector": { "id": "…", "name": "Paris Est" },
  "building": { "id": "…", "name": "12 rue de la Roquette", "address": "12 rue de la Roquette, 75011 Paris" },
  "tags": ["Premium"],
  "client": { "id": "…", "name": "Habitat Parisien" },
  "sheet": [ { "label": "Le logement", "role": "housing",
    "fields": [ { "id": "…", "label": "Surface", "value": "65 m²", "role": "surface" } ] } ]
}

البياضات والتوصيلات. يتضمن كل سطر من البياضات place (type: depot أو building أو property) وarticle وsource (company أو laundry أو client). GET /api/public/v1/linen/stock: عوامل التصفية placeType وarticle وupdatedSince. GET /api/public/v1/linen/moves: from وto وkind (count وdelivery وtaken وoffice وprepared وcleaning وmove وreceipt) وplaceType وarticle؛ وتعطي كل حركة before وafter وdelta. GET /api/public/v1/linen/orders: from وto وstatus (draft وsent وreceived)، دون أسعار. GET /api/public/v1/deliveries: from وto إلزاميان (31 يومًا كحد أقصى) وdriver وpropertyExternalId؛ وتعطي كل عملية توصيل arrivedAt وdepartedAt وcompletedAt وproofs (روابط صالحة لمدة 7 أيام).

{
  "id": "…",
  "date": "2026-11-04",
  "time": "09:30",
  "property": { "id": "…", "name": "Bastille — 3 pièces", "externalId": "LOG-12" },
  "driver": "Yanis",
  "arrivedAt": "2026-11-04T08:41:00Z",
  "departedAt": "2026-11-04T08:47:00Z",
  "completedAt": "2026-11-04T08:47:10Z",
  "proofs": [ { "url": "https://…", "takenAt": "2026-11-04T08:46:00Z", "note": null } ]
}

الفوترة. لا تستجيب نقاط الوصول هذه إلا لرمز حُدِّد فيه المربع billing (الفوترة)؛ ولا يُحدَّد أبدًا تلقائيًا: لا تحدّده إلا لأدواتكم الخاصة أو لمحاسبكم. GET /api/public/v1/clients: الهوية وجهة الاتصال وعناوين الفوترة (billingEmails) و SIREN ورقم ضريبة القيمة المضافة ونسبة الضريبة المطبّقة اليوم (tax.source: client أو company أو exempt أو reverseCharge)؛ ويضيف includeDeleted=true العملاء المنقولين إلى سلة المحذوفات. GET /api/public/v1/prices: السعر الأساسي لكل عقار وفتراته، وفي onDate السعر المطبّق في اليوم date (اليوم افتراضيًا)؛ عامل التصفية clientId. GET /api/public/v1/reports: التقارير والفواتير (عاملا التصفية from وto بالصيغة YYYY-MM، وclientId)، مع status (checked أو invoiced أو sent أو paid) والمجاميع وإشعارات الدائن المعتمدة والصافي المستحق وpayment (null ما دامت الفاتورة غير معتمدة). ويضيف GET /api/public/v1/reports/:id الأسطر كما فُوترت تمامًا. المبالغ هي مبالغ البرنامج، ولا يُعاد حسابها أبدًا.

{
  "id": "…",
  "number": 12,
  "clientId": "…",
  "month": "2026-10",
  "period": null,
  "status": "sent",
  "currency": "EUR",
  "totals": { "ht": 1250, "tax": 250, "ttc": 1500 },
  "net": { "invoicedHt": 1250, "invoicedTtc": 1500, "creditHt": 50, "creditTtc": 60, "netHt": 1200, "netTtc": 1440 },
  "creditNotes": [ { "id": "…", "number": "AV-2026-014", "date": "2026-11-03", "amountHt": 50 } ],
  "sentOn": "2026-11-02",
  "payment": { "status": "toPay", "paidOn": null, "dueDate": "2026-12-02", "daysLate": 0 },
  "lines": [ { "apartment": "Bastille — 3 pièces", "date": "2026-10-05", "description": "Ménage",
    "quantity": 1, "amountHt": 100, "baseHt": 80,
    "adjustments": { "linen": { "count": 2, "amount": 20 }, "hours": null, "other": 0 },
    "manual": false, "taskId": "0b9d2c7e-…" } ]
}

ينشئ POST /api/public/v1/tasks مهمة بالحقول نفسها المستخدمة في الاستيراد (externalId، propertyExternalId، date، type، startTime، durationHours، assigneeName، notes…). الاستجابة 201 عند إنشائها، و200 إذا كانت موجودة وجرى تحديثها.

curl -X POST https://thebigone.io/api/public/v1/tasks \
  -H "Authorization: Bearer cnimp_…" -H "Content-Type: application/json" \
  -d '{"externalId":"MEN-882","propertyExternalId":"LOG-12","date":"2026-10-06","type":"cleaning","startTime":"11:00"}'

يعدّل PATCH /api/public/v1/tasks/:id الحقول date، startTime، durationHours، assigneeName، notes، needsDelivery أو needsKit. لا تُعدَّل أبدًا مهمة بدأت أو انتهت أو اعتُمدت: تكون الاستجابة عندئذٍ 409.

أضف عنوان HTTPS لأداتك في وصول المطوّرين واختر الأحداث. يرسل The Big One إليه طلب POST بصيغة JSON خلال الدقيقة التالية:

• task.created — أُنشئت المهمة
• task.assigned — وُزّعت المهمة
• task.started — بدأت المهمة
• task.completed — انتهت المهمة
• task.validated — اعتمد مسؤولٌ المهمة
• task.updated — تم تعديل المهمة: التاريخ، الوقت، المدة، عامل النظافة، الملاحظات، العقار… (data.changes)
• task.cancelled — تم إلغاء المهمة (تخرج من جدول العمل)
• task.deleted — تم حذف المهمة (data.task: آخر صيغة معروفة لها)
• task.comment_added — تمت إضافة تعليق إلى مهمة (data.comment)
• report.ready — تقرير المهمة متاح (reportUrl وreport)
• inspection.completed — تمت مراقبة الجودة (النتيجة والتقييم والملاحظة في report.inspection)
• issue.reported — مشكلة مُبلَّغ عنها من عامل النظافة (data.issue)
• issue.updated — تم التكفل بالمشكلة أو حلها (data.issue)
• issue.resolved — تم حل المشكلة: يمكنك إبلاغ العميل بأنه «تم الحل»
• reservation.created — تم إنشاء الحجز (data.reservation)
• reservation.updated — تم تعديل الحجز: التواريخ أو الأوقات أو العقار أو عدد الضيوف
• reservation.cancelled — تم إلغاء الحجز أو حذفه من برنامج الإدارة (removed: true)
• property.created — تم إنشاء العقار (data.property)
• property.updated — تم تعديل العقار، بما في ذلك عميله حسب الأسعار (data.property، data.changes)

POST https://votre-outil.fr/hooks/thebigone
X-TheBigOne-Event: task.completed
X-TheBigOne-Delivery: 5f1c…
X-TheBigOne-Signature: t=1790000000,v1=9a3f…

{ "id": "5f1c…", "type": "task.completed", "createdAt": "2026-10-05T13:05:02Z",
  "data": { "task": { …la mission, au format de la lecture… } } }

أجب برمز 2xx خلال 10 ثوانٍ. وإلا تُعاد محاولة الإرسال بعد 1 و5 و15 و60 ثم 240 دقيقة، ثم يُتخلّى عنه. يحدّد X-TheBigOne-Delivery عملية الإرسال: استخدمه لتجاهل أي تكرار.

تحقّق من التوقيع بالسرّ المعروض عند إنشاء العنوان: HMAC-SHA256 لـ <t>.<المحتوى الخام>، وارفض أي طابع زمني أقدم من 5 دقائق.

import crypto from "node:crypto";

function signatureValide(secret, corpsBrut, entete) {
  const t = /t=(\d+)/.exec(entete)?.[1];
  const v1 = /v1=([0-9a-f]+)/.exec(entete)?.[1];
  if (!t || !v1 || Math.abs(Date.now() / 1000 - Number(t)) > 300) return false;
  const attendu = crypto.createHmac("sha256", secret).update(`${t}.${corpsBrut}`).digest("hex");
  return crypto.timingSafeEqual(Buffer.from(attendu), Buffer.from(v1));
}

سجل الإرسال. يعرض GET /api/public/v1/webhook-deliveries عمليات الإرسال (قيد الانتظار، مرسلة، متروكة)، مع عدد المحاولات وآخر رد من خادمك ووقت المحاولة التالية. في صفحة وصول المطورين، يرسل زر «إرسال اختبار» حدث test.ping إلى العنوان المختار.

• لكل عنوان: 1200 عملية قراءة و300 عملية كتابة كل 10 دقائق. لكل رمز، مع جميع العناوين: 1200 استدعاء كل 10 دقائق. وبعد ذلك، يحمل الرد 429 الترويسة Retry-After (عدد الثواني للانتظار). لتقليل الاستدعاءات: include= في قائمة المهام، والإشعارات.
• الاستيراد: 5 ميغابايت لكل استدعاء، و2000 عنصر لكل نوع، و60 استدعاءً كل 10 دقائق لكل شركة.
• التواريخ بصيغة YYYY-MM-DD. الأوقات وحدها (HH:MM) بالتوقيت المحلي للعقار (الحقل timezone)؛ أما startAt وplannedEndAt وcheckinAt وبقية الطوابع الزمنية فكاملة، مع فارقها أو بتوقيت UTC (معيار ISO 8601).

400 معاملات أو محتوى غير صالح · 401 الرمز غائب أو غير صالح · 403 الصلاحية ناقصة · 404 غير موجود · 409 المهمة مقفلة · 413 المحتوى كبير جدًا · 422 سطر مرفوض · 429 استدعاءات كثيرة جدًا · 503 الخدمة غير متاحة مؤقتًا. كل الأخطاء بالشكل { "error": "…" }.

لديك سؤال عن التكامل؟ اطّلع على صفحة المصدر المخصّص أو راسلنا عبر النموذج أدناه.

يُؤرَّخ هنا كل تغيير قد يمسّ أداة متصلة. وإصدار مخطط OpenAPI (info.version) هو تاريخ آخر تغيير.

• 7 نوفمبر 2026. المهام الملغاة: الحالة cancelled، ولم تعد تُعاد افتراضيًا (كانت تظهر من قبل بالحالة created)؛ والحقل inPlanning. يُملأ reportUrl دائمًا للمهمة المنتهية؛ وcompletedAt وreportReadyAt؛ ويُملأ endedAt حتى دون تسجيل الوقت. أوقات كاملة مع المنطقة الزمنية (timezone وstartAt وplannedEndAt)، والإقامة المرتبطة (reservation) والوصول التالي (nextArrival). include=report,checklist,comments ومحتوى التقرير كبيانات. المسارات /tasks/deleted و/webhook-deliveries و/openapi.json. عنوان العقار (addressDetails). عشرة إشعارات جديدة. روابط الصور صالحة 7 أيام. /sectors مفتوح للرمز المحصور (قطاعاته). حدود أعلى.
• 3 نوفمبر 2026. قائمة التحقق وصور المهمة، والمشكلات المُبلَّغ عنها، وتقييمات الضيوف، والفريق والإجازات، والعقارات الكاملة، والقطاعات والمباني، والبياضات والتوصيلات، والفوترة (الصلاحية billing)؛ رمز API محصور في بعض العقارات؛ أربعة إشعارات (مشكلة مُبلَّغ عنها، حجز أُنشئ أو عُدّل أو أُلغي)؛ حد لكل رمز.
• 27 سبتمبر 2026. الإصدار الأول: الاستيراد دفعة واحدة، وقراءة المهام والعقارات والحجوزات، وإنشاء مهمة وتعديلها، ورموز حسب الاستخدام، وإشعارات موقّعة.