تحميل بيانات مؤسستك

موضع هذه الميزة

يتيح تحميل البيانات لـ Kaleidr الإجابة بالاستناد إلى بيانات مؤسستك. وهذه ميزة ضمن خطة Enterprise. يستخدم مساعد Kaleidr Studio النسخة المنشورة من البيانات لأعضاء مؤسستك المسجّلين الدخول. ولإتاحتها على موقعك أو خادمك، توجد ثلاث خطوات إضافية: إصدار مفتاح يملك صلاحية قراءة البيانات، وطرح الأسئلة بهذا المفتاح، والتحقق من ظهور مواقعك في الإجابات. يشرح دليل الإجابات من بياناتك الخاصة العملية كاملة وطريقة استخدام البيانات في الإجابات. وهذه الصفحة مرجع لمرحلة التحميل، بما يشمل جميع الطلبات والحقول والحدود والأخطاء وعمليات سحب النسخة المنشورة.

هذه الصفحة لا تتناول الملفات التي تضيفها إلى خريطة من لوحة البيانات في Kaleidr Studio (مثل جدول بيانات أو ملف GeoJSON أو مسار GPX). فتلك ميزة مستقلة متاحة في جميع الخطط؛ راجع مجموعات البيانات على الخريطة.

توجد طريقتان للتحميل، وكلتاهما تستخدمان مسار المعالجة نفسه:

الواجهة: قسم Data for AI Answers أسفل لوحة البيانات في أي خريطة داخل Kaleidr Studio. هذه واجهة التحميل الوحيدة، وتظهر أدواتها فقط لمالك المؤسسة أو مسؤولها المخوّل بالتحميل. يشرح التحميل في Kaleidr Studio خطواتها.
واجهة API الموضحة هنا: تستدعي الواجهة المرئية هذه العمليات نفسها، لذا تنطبق صيغ الملفات والحدود والحالات والأخطاء أدناه على الطريقتين، وتظهر النسخة المنشأة بإحداهما في الأخرى.

قبل البدء، تجدر معرفة ثلاث خصائص للتحميل:

يُبحث في بياناتك عند الإجابة عن السؤال. يستشير Kaleidr الإصدار المنشور في تلك اللحظة؛ ولذلك يؤدي إلغاء نشره إلى توقف الإجابات اللاحقة عن استخدام بياناته فورًا.
تُستخدم بياناتك لمؤسستك وحدها. وهي معزولة لكل مؤسسة ولا تظهر على خريطة Kaleidr المخصصة للمستهلكين أو في إجابات مؤسسة أخرى.
لا تُختلق قيمك. يمكن لمساعد اختياري اقتراح ربط الأعمدة استنادًا إلى صف العناوين وخمسة صفوف نموذجية كحد أقصى. ثم تُحوَّل جميع صفوف الملف وفق الربط الذي توافق عليه. إذا كان الربط خاطئًا، صححه وأعد تشغيل العملية؛ فلا تُنشأ أسعار أو تواريخ أو أسماء من عند النظام.

الإتاحة

المتطلب	التفاصيل
الخطة	Enterprise. تعيد عمليات التحميل والنشر وإعادة الإرسال واقتراح الربط في خطتي Free وPro الخطأ 403 `vendor_data_not_on_plan`. الخطة المعتمدة هي خطة مؤسسة Kaleidr التي تُشترى وتُغيَّر من kaleidr.com/billing، ولا توجد خطة مستقلة لـ Studio.
الدور	مالك المؤسسة أو مسؤولها؛ وإلا يظهر الخطأ 403 `org_admin_required`.
الحدود	تحددها اتفاقية مؤسستك؛ راجع الحدود. تعرض `GET /shared-api/datahub/limits` حدود مؤسستك الفعلية.
الواجهة	قسم Data for AI Answers في لوحة البيانات داخل Kaleidr Studio، أو واجهة API في هذه الصفحة. كلاهما يستخدم المسار نفسه والتحققات ذاتها.

ما العمليات التي تتطلب كل خطة؟

العمليات	الدور	الخطة
اقتراح ربط الأعمدة والتحميل والنشر وإعادة الإرسال	المالك أو المسؤول	Enterprise
قراءة الحدود وحالة المعالجة وقائمة النسخ	المالك أو المسؤول	أي خطة
إلغاء نشر نسخة أو حذفها	المالك أو المسؤول	أي خطة

تظل عمليات الصفين الثاني والثالث متاحة في جميع الخطط؛ لذلك تستطيع المؤسسة التي انتقلت إلى خطة لا تسمح بالتحميل عرض ما سبق تحميله وسحبه.

استخدام البيانات نفسه متاح في Enterprise فقط في موضعي الاستخدام: يجيب مساعد Kaleidr Studio من النسخة المنشورة ما دامت المؤسسة في هذه الخطة. أما قراءة البيانات في الإجابات عبر مفتاح API أو SDK فتتطلب صلاحية منفصلة هي نطاق vendor، ولا يتاح هذا النطاق إلا لمؤسسة في Enterprise. راجع الإجابات من بياناتك الخاصة.

يعتمد ما يظهر في قسم Data for AI Answers داخل Studio على خطة مؤسستك ودورك: راجع ما يظهر في القسم عندما لا يمكنك الرفع.

ما الذي تستطيع مؤسستك تحميله؟

تحقق قبل التحميل. هذا الطلب هو الذي يقرأه قسم Studio عند فتحه.


الطلب	`GET /shared-api/datahub/limits`
من يحق له	المالك أو المسؤول، في أي خطة
معامل الاستعلام	`org_id` اختياري لتحديد المؤسسة عند إدارة أكثر من مؤسسة

curl https://api.kaleidr.com/shared-api/datahub/limits \
  -H "Authorization: Bearer $KALEIDR_ACCESS_TOKEN"

هذا المثال يخص مؤسسة في Enterprise. حُذفت الحدود الثلاثة منه عمدًا لأنها محددة في اتفاقية مؤسستك، فلا يمكن أن يكون أي رقم مطبوع هنا ملائمًا للجميع. يحتوي limits دائمًا على حقول الأعداد الصحيحة الثلاثة في الجدول أدناه.

{
  "can_upload": true,
  "plan": "enterprise",
  "limits": { "…": "places, documents and artifact_mb: three integers, described below" },
  "reason": null
}

في خطتي Free وPro تظل الاستجابة 200، مع توضيح السبب:

{
  "can_upload": false,
  "plan": "pro",
  "limits": { "places": 0, "documents": 0, "artifact_mb": 0 },
  "reason": "vendor_data_not_on_plan"
}

الحقل	النوع	المعنى
`can_upload`	قيمة منطقية	هل يُقبل التحميل من هذه المؤسسة؟
`plan`	سلسلة أو null	الخطة التي تنطبق حدودها: `free` أو `pro` أو `enterprise`.
`limits.places`	عدد صحيح	المواقع في عملية تحميل واحدة، أو صفوف البيانات في ملف CSV.
`limits.documents`	عدد صحيح	المستندات في عملية تحميل واحدة.
`limits.artifact_mb`	عدد صحيح	حجم الملف بوحدة MiB.
`reason`	سلسلة أو null	تكون `vendor_data_not_on_plan` حين يكون `can_upload` بالقيمة `false`، وإلا فهي `null`. وتصبح الحدود الثلاثة جميعها صفرًا.

هذه الأرقام خاصة بمؤسستك، وهي المحددة في اتفاقيتها. ولا يمكن لأي حد أن يتجاوز الحد الأقصى الذي تقبله عملية الرفع نفسها؛ فللمنصة سقف تقني لكل واحد من الحدود الثلاثة، ولا يمكن للاتفاقية تجاوزه.

الحالة	المعنى
200	تُعاد دائمًا للمالك أو المسؤول في جميع الخطط. دون Enterprise تعود `can_upload: false` بدل رفض الطلب.
401	رمز الوصول مفقود أو منتهي الصلاحية أو ليس رمز وصول.
403 `org_admin_required`	الحساب ليس مالكًا أو مسؤولًا في المؤسسة.

المصادقة

يستخدم كل طلب رمز الوصول الخاص بحساب Kaleidr الذي سجلت الدخول إليه بوصفه رمز Bearer:

Authorization: Bearer <account access token>

ليس هذا مفتاح API؛ فالمفتاح kld_pk_… أو kld_sk_… مرفوض. تحدد المفاتيح عمليات التكامل، أما تحميل البيانات فهو إجراء إداري للمؤسسة، لذا يتطلب مصادقة مستخدم له دور مناسب.
يجب استخدام رمز الوصول، لا رمز المعرّف (ID token).
يعود الرمز إلى مالك أو مسؤول مسجّل الدخول وتنتهي صلاحيته بانتهاء جلسته. لا تتوافر بعد بيانات اعتماد طويلة الأمد لهذه الواجهة. إذا أردت تشغيل التحميل من مهمة آلية، تواصل مع Kaleidr قبل تنفيذها.
لا تحتاج إلى هذه الإجراءات في واجهة Studio؛ فهي تستخدم جلسة العضو المسجّل الدخول.

جميع المسارات في هذه الصفحة تقع تحت https://api.kaleidr.com. تقرأ الأمثلة الرمز من متغير بيئة:

export KALEIDR_ACCESS_TOKEN='<account access token>'

إذا كنت تدير عدة مؤسسات، أضف org_id (داخل جسم طلب التحميل أو في معامل الاستعلام ?org_id= للطلبات الأخرى) لتحديد المؤسسة. وإذا لم تضفه، تُستخدم مؤسستك الأساسية.

البيانات التي يمكنك تحميلها

تتكون كل عملية تحميل من ملف نصي واحد يُرسل كسلسلة نصية في طلب JSON. وتحدد لاحقة اسم الملف طريقة قراءته.

ما لديك	ما ترسله	ما يتضمنه
قائمة مواقع	ملف `.csv` بأسماء أعمدة ثابتة ومن دون ربط	مواقع
جدول بيانات مُصدّر يحتوي صفًا لكل ليلة أو غرفة أو سعر	ملف `.csv` مع `mapping_spec`	مواقع وأنواع غرف وخطط أسعار وأسعار ليلية وتوافر
بيانات منظّمة مسبقًا بالكامل	حزمة `.json`	كل ما سبق إضافة إلى ساعات العمل والمستندات

يجب أن تتضمن كل عملية تحميل موقعًا واحدًا على الأقل.

ملف CSV للمواقع

يجب أن يستخدم صف العناوين أسماء الأعمدة التالية:

العمود	مطلوب	ملاحظات
`name`	نعم	يفشل تحميل الصف غير المسمى، ويُبلَّغ عن رقم السطر.
`timezone`	نعم	منطقة زمنية وفق IANA مثل `Europe/London`.
`lat`, `lng`	أحد الشكلين	إحداثيات تُستخدم كما وردت.
`address`	أحد الشكلين	يُستخدم لتحديد الإحداثيات عند غياب `lat` و`lng`.
`category`	لا	تصنيف قصير مثل `hotel` أو `restaurant`.
`ref`	لا	معرّفك الخاص للصف؛ وإن غاب، يُحدَّد الصف برقم السطر.

name,timezone,lat,lng,address,category
Harbor Hotel,Europe/London,51.5079,-0.0877,"1 Example Street, London",hotel
Canal House,Europe/Amsterdam,,,"Example Gracht 12, Amsterdam",hotel

جدول بيانات مع ربط الأعمدة

لا يمكن قراءة جدول يحتوي صفًا لكل ملاحظة (عقار أو غرفة أو خطة أو تاريخ أو سعر) بأسماء أعمدة ثابتة. أرسله مع mapping_spec يحدد العمود الذي يزوّد كل حقل بقيمته.

Property,Address,Room,Plan,Date,Nightly Rate,Available
Harbor Hotel,"1 Example Street, London",Double,Flexible,2026-11-06,189.00,4
Harbor Hotel,"1 Example Street, London",Suite,Flexible,2026-11-06,320.00,1

{
  "places": {
    "ref_from": ["Property"],
    "fields": {
      "name": "Property",
      "address": "Address",
      "timezone": { "const": "Europe/London" },
      "category": { "const": "hotel" }
    }
  },
  "room_types": { "ref_from": ["Room"], "fields": { "name": "Room" } },
  "rate_plans": { "ref_from": ["Plan"], "fields": { "name": "Plan" } },
  "daily_rates": {
    "fields": {
      "stay_date": "Date",
      "price_amount": "Nightly Rate",
      "price_currency": { "const": "GBP" }
    }
  },
  "daily_inventory": {
    "fields": { "stay_date": "Date", "units_available": "Available" }
  }
}

قواعد ربط الأعمدة:

الجزء	المعنى
الأقسام	`places` (إلزامي) و`room_types` و`rate_plans` و`daily_rates` و`daily_inventory`. ضمّن فقط الأقسام الموجودة في جدولك.
`ref_from`	الأعمدة التي تحدد الكيان الواحد؛ الصفوف ذات القيم المتماثلة فيها تشير إلى الموقع أو نوع الغرفة أو الخطة نفسها.
`fields`	يأخذ كل حقل قيمته من اسم عمود. وقد تستخدم بعض الحقول قيمة ثابتة بالصورة `{ "const": "value" }`.

لا يسمح الربط إلا بتعيين الحقول الواردة في الجدول. يوضح العمود الأخير الحقول التي تقبل قيمة ثابتة.

القسم	الحقول التي يمكن تعيينها	الحقول التي تقبل قيمة ثابتة
`places`	`name`, `address`, `timezone`, `category`, `lat`, `lng`, `overture_id`	`timezone`, `category`
`room_types`	`name`	`name`
`rate_plans`	`name`, `currency`, `cancellation_policy`, `board_basis`	`name`, `currency`
`daily_rates`	`stay_date` (تاريخ ISO)، و`price_amount` (رقم لا يقل عن 0)، و`price_currency` (ثلاثة أحرف)	`price_currency`
`daily_inventory`	`stay_date`, `units_available` (عدد صحيح غير سالب)	لا شيء

تنطبق قاعدتان، ومخالفة أي منهما خطأ تحقق:

يُرفض أي حقل غير مدرج في الجدول. يذكر الخطأ الحقل ويسرد ما يقبله قسمه: room_types.fields.beds: not a field a mapping can set -- room_types takes name. أما البيانات التي لا يمكن تمثيلها في خلايا الجدول، مثل عدد الأسرّة والسمات الحرة، فيجب إرسالها ضمن حزمة JSON.
تُرفض القيم الثابتة في غير المواضع المحددة. يجب أن تأتي الأسعار والتواريخ والأعداد وأسماء المواقع وإحداثياتها من أعمدة الملف: daily_rates.fields.price_amount: must name a column -- a constant cannot supply this field. تُخصص القيمة الثابتة لما ينطبق على الجدول كله، كمنطقة زمنية أو عملة واحدة.

تظهر هذه الأخطاء في قائمة errors ضمن اقتراح الربط، وكذلك في error_report عند معالجة تحميل يستخدم هذا الربط. تفشل المعالجة حينها ولا تُجهَّز أي بيانات.

إذا وُجد daily_rates، فلا بد من وجود room_types وrate_plans أيضًا، لأن كل سعر يرتبط بنوع غرفة وخطة أسعار. وإذا لم يحتو جدولك على عمود للخطة، فعيّن اسمها كقيمة ثابتة.

ينطبق الربط على ملف .csv فقط. وإرساله مع ملف .json يفشل المعالجة.

حزمة JSON

ملف .json هو كائن واحد يحتوي أيًا من القوائم التالية، وترتبط العناصر ببعضها بواسطة ref.

{
  "places": [
    {
      "ref": "harbor",
      "name": "Harbor Hotel",
      "timezone": "Europe/London",
      "lat": 51.5079,
      "lng": -0.0877,
      "address": "1 Example Street, London",
      "category": "hotel"
    }
  ],
  "room_types": [{ "ref": "double", "place_ref": "harbor", "name": "Double" }],
  "rate_plans": [{ "ref": "flex", "place_ref": "harbor", "name": "Flexible" }],
  "daily_rates": [
    {
      "place_ref": "harbor",
      "room_type_ref": "double",
      "rate_plan_ref": "flex",
      "stay_date": "2026-11-06",
      "price_amount": 189.0,
      "price_currency": "GBP"
    }
  ],
  "daily_inventory": [
    { "place_ref": "harbor", "room_type_ref": "double", "stay_date": "2026-11-06", "units_available": 4 }
  ],
  "hours": [
    { "place_ref": "harbor", "weekday": 0, "opens": "07:00", "closes": "23:00" },
    { "place_ref": "harbor", "valid_from": "2026-12-25", "valid_through": "2026-12-25", "is_closed": true }
  ],
  "documents": [
    { "title": "Cancellation policy", "text": "Free cancellation until 18:00 on the day before arrival." }
  ]
}

القائمة	الحقول المطلوبة	ملاحظات
`places`	`name`, `timezone`، و`lat` مع `lng` أو `address`	يجب أن يكون `ref` فريدًا؛ ويلزم موقع واحد على الأقل.
`room_types`, `rate_plans`	`place_ref`, `name`	يجب أن يكون `ref` فريدًا داخل القائمة.
`daily_rates`	`place_ref`, `room_type_ref`, `rate_plan_ref`, `stay_date`, `price_amount`, `price_currency`
`daily_inventory`	`place_ref`, `room_type_ref`, `stay_date`, `units_available`
`hours`	`place_ref` ويوم `weekday` أو تاريخ `valid_from`	قيمة `weekday` بين 0 و6، حيث 0 يوافق الاثنين. و`opens` و`closes` هما وقتا اليوم.
`documents`	`title`, `text`	نص مُضمَّن فقط.

تقبل القوائم أيضًا حقولًا اختيارية، ولكل منها حد حجم؛ راجع حدود الحقول.

بخصوص المستندات:

يتكوّن المستند من title وtext المُضمَّن. تُتجاهل أيّ مسارات تخزين أو مفاتيح تضيفها إليه؛ ولا يمكن للمستند الإشارة إلى ملف خارجي.
يصف mime الاختياري النص. يُحفظ كما هو عند استخدام text/plain أو text/markdown أو text/html، وتُسجل أي قيمة أخرى على أنها text/plain.

يجب أن تكون الأرقام محدودة وقابلة للتمثيل. لا تُقبل NaN أو Infinity كإحداثيات أو أسعار أو أعداد، ولا داخل حقول JSON الحرة؛ ويُبلغ عن الصف باعتباره خطأ.

تسلسل التحميل

تُنشئ كل عملية تحميل ingest واحدًا (مهمة معالجة) وrelease واحدًا (نسخة ذات إصدار). تظل النسخة draft حتى نشرها. يستبدل النشر النسخة المنشورة سابقًا بخطوة واحدة، فلا يرى القرّاء تحديثًا جزئيًا ولا تمر المؤسسة بفجوة بلا بيانات عند الاستبدال. الطريقة الوحيدة لإزالة كل النسخ المنشورة هي إلغاء نشر النسخة الحالية.

propose a mapping  ─►  stage a preview  ─►  check the result  ─►  publish
   (optional,            POST /ingests        GET /ingests/{id}     POST /ingests/{id}/publish
    for a sheet)         preview: true

later, to take a release back out:   unpublish  ─►  delete
                                      POST /releases/{id}/unpublish    DELETE /releases/{id}

1. اقتراح ربط الأعمدة (اختياري)

استخدم هذه الخطوة إذا كان لديك جدول بيانات بلا ربط. أرسل بداية الملف: صف العناوين وبعض صفوف البيانات، لا كامل الملف المصدَّر.


الطلب	`POST /inference-api/vendor/mapping/propose`
المخوّل	مالك أو مسؤول مؤسسة ضمن Enterprise، أي الحسابات نفسها المخولة بالتحميل.
الجسم	`{ "csv_head": "<the first characters of your file>" }`
الحد	طول `csv_head` بين 1 و16,384 حرفًا، و30 اقتراحًا لكل حساب في الساعة.
التكلفة	يستهلك كل اقتراح رصيد الذكاء الاصطناعي لمؤسستك بمقدار الرموز التي استخدمها. بقية الطلبات بهذه الصفحة لا تستهلك الرصيد.

curl -X POST https://api.kaleidr.com/inference-api/vendor/mapping/propose \
  -H "Authorization: Bearer $KALEIDR_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"csv_head":"Property,Address,Room,Plan,Date,Nightly Rate,Available\nHarbor Hotel,\"1 Example Street, London\",Double,Flexible,2026-11-06,189.00,4\nHarbor Hotel,\"1 Example Street, London\",Suite,Flexible,2026-11-06,320.00,1\n"}'

{
  "mapping_spec": { "places": { "ref_from": ["Property"], "fields": { "name": "Property", "address": "Address", "timezone": { "const": "Europe/London" } } }, "room_types": { "ref_from": ["Room"], "fields": { "name": "Room" } } },
  "notes": "Time zone inferred from the addresses.",
  "columns": ["Property", "Address", "Room", "Plan", "Date", "Nightly Rate", "Available"],
  "sample_result": { "places": 1, "room_types": 2, "rate_plans": 1, "daily_rates": 2, "daily_inventory": 2 },
  "errors": []
}

كيفية قراءة الاستجابة:

افحص sample_result. يُطبَّق الربط المقترح على الصفوف النموذجية، ويعرض sample_result عدد العناصر الناتجة لكل قسم. هكذا تكشف الربط الذي يبدو صحيحًا لكن لا ينتج شيئًا قبل التحميل.
قد لا تكون errors فارغة حتى مع الاستجابة 200. يرجع الاقتراح غير القابل للتطبيق مع جميع أخطائه دفعة واحدة لتعديل الربط. أمثلتها غياب عمود لحقل إلزامي، أو اسم عمود غير موجود، أو منطقة زمنية غير معتمدة لدى IANA، أو عملة لا تتكون من ثلاثة أحرف.
تُؤخذ عينات من الصفوف المكتملة فقط، بحد أقصى خمسة. يُستبعد السطر الأخير من csv_head ما لم ينته النص بسطر جديد؛ إذ لا يمكن التمييز بين السطر المبتور والمكتمل.
لا يُخزَّن شيء. عدّل الاقتراح وأرسله بنفسك في الخطوة التالية.

الحالة	المعنى
403 `org_admin_required`	لست مالكًا أو مسؤولًا لأي مؤسسة.
403 `vendor_data_not_on_plan`	أنت مالك أو مسؤول، لكن لا توجد أي مؤسسة تابعة لك ضمن Enterprise المسموح لها بالتحميل.
422	طول `csv_head` يتجاوز 16,384 حرفًا، أو لا يوجد صف عناوين، أو توجد أسماء أعمدة مكررة، أو لا يوجد صف بيانات مكتمل. يوضح `detail` السبب.
429، حد المعدّل	أكثر من 30 اقتراحًا من هذا الحساب خلال الساعة الماضية.
429، رصيد AI	استُهلك رصيد الذكاء الاصطناعي للمؤسسة للفترة الحالية.
502 `mapping proposal unavailable`	تعذر إنشاء الاقتراح؛ أعد المحاولة أو اكتب الربط يدويًا.

التمييز بين حالتي 429

كلتا حالتي الرفض تستخدمان الرمز 429. اقرأ جسم الاستجابة:

	حد المعدّل	نفاد رصيد الذكاء الاصطناعي
الجسم	`{ "detail": "at most 30 mapping proposals per hour" }`	جسم الاستجابة القياسي للحصة
كيفية التمييز	لا يوجد حقل `error`؛ و`detail` هو العبارة أعلاه.	`"error": "quota_exceeded"` مع `limit` و`used` و`remaining` و`reset_at`
المطلوب	انتظر؛ يُحسب الحد لكل حساب خلال الساعة الماضية.	انتظر حتى `reset_at` أو أضف رصيد AI أو اكتب الربط يدويًا.

{
  "error": "quota_exceeded",
  "detail": "Usage limit reached. Please try again later.",
  "tier": "enterprise",
  "remaining": 0,
  "reset_at": "2026-11-01T04:00:00+00:00",
  "period": "month",
  "reset_in_seconds": 1296000
}

يحذف المثال أربعة حقول موجودة: يعرض limit وused حصة مؤسستك واستهلاكها المحددين في الاتفاقية؛ ويشير product وmeter إلى عداد Kaleidr Studio لا عداد API لأن التحميل ميزة في Studio. لكن الرصيد المستهلك واحد، وهو رصيد الذكاء الاصطناعي لمؤسستك. فرّق بين الحالات بحقل error كما في أي رفض بسبب الحصة.

كيفية احتساب تكلفة الاقتراح:

لا تُستهلك أرصدة لطلب مرفوض بالرمز 403 أو 422 أو 429 لحد المعدّل. ويُحتسب أيضًا الطلب المرفوض بالرمز 422 بسبب العينة ضمن الحد البالغ 30 طلبًا في الساعة.
لا يُستهلك رصيد عندما يتعذر توليد اقتراح بسبب عدم وصول إجابة (502).
يُحتسب رصيد الرموز إذا وصلت إجابة اقتراح ولكن تعذر استخدامها (502 أيضًا).
يُحتسب الاقتراح الذي يُرجع قائمة errors غير فارغة كأي اقتراح تم إنتاجه.

تعرض Studio في الحالتين رسالتين: "لقد بلغت الحد الأقصى لمقترحات الربط في الساعة. حاول لاحقًا أو عدّل الربط يدويًا." و"نفد رصيد الذكاء الاصطناعي لمؤسستك لهذه الفترة. يمكنك كتابة الربط يدويًا." لا يتطلب الربط اليدوي اقتراحًا ولا يستهلك رصيدًا.

2. تجهيز معاينة


الطلب	`POST /shared-api/datahub/ingests`
المخوّل	المالك أو المسؤول في Enterprise
الترويسة	`Idempotency-Key` بطول 8 إلى 128 حرفًا، إلزامية

حقل الجسم	النوع	الافتراضي	المعنى
`filename`	سلسلة حتى 200 حرف	إلزامي	يجب أن ينتهي بـ `.csv` أو `.json`. اللاحقة تحدد طريقة القراءة.
`artifact`	سلسلة	إلزامي	النص الخام للملف.
`source`	`"csv"` أو `"api"` أو `"manual"`	`"csv"`	وصف لمصدر البيانات لا يحدد المحلل؛ القيمة `"json"` غير صالحة وتعيد 422.
`mapping_spec`	كائن حتى 64 KB	لا شيء	ربط أعمدة الجدول. احذفه لملف CSV بسيط للمواقع أو لحزمة JSON.
`preview`	قيمة منطقية	`false`	عند `true` تُجهَّز البيانات للمعاينة دون نشر؛ وعند `false` تُنشر بعد قراءتها.
`org_id`	UUID	مؤسستك الأساسية	المؤسسة المستهدفة بالتحميل.

curl -X POST https://api.kaleidr.com/shared-api/datahub/ingests \
  -H "Authorization: Bearer $KALEIDR_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: places-2026-10-10-a" \
  -d '{
    "filename": "places.csv",
    "source": "csv",
    "preview": true,
    "artifact": "name,timezone,lat,lng,address,category\nHarbor Hotel,Europe/London,51.5079,-0.0877,\"1 Example Street, London\",hotel\n"
  }'

{
  "ingest_id": "5f0c2a1e-…",
  "release_id": "a81d77b0-…",
  "status": "pending",
  "status_url": "/shared-api/datahub/ingests/5f0c2a1e-…",
  "dispatched": true
}

يقتصر نطاق Idempotency-Key على مؤسستك. إعادة إرسال المفتاح نفسه تعيد عملية ingest التي أنشأها مسبقًا مع dispatched: false دون إنشاء أخرى. استخدم مفتاحًا جديدًا عند إعادة التجهيز عمدًا بعد تعديل الربط، فالمفتاح القديم يسترجع معالجة الربط السابق.

يبيّن dispatched هل بدأ الطلب المعالجة. عند إنشاء ingest جديد تشير false إلى أن المعالجة لم تبدأ وأن الحالة تظل pending؛ ابدأها عبر طلب إعادة الإرسال.

استخدم preview: true عند أول تحميل وكلما تغيّر الربط.

عملية تحميل واحدة في الوقت نفسه، وحد أقصى في الساعة. يُرفض طلب جديد أثناء معالجة طلب آخر للمؤسسة نفسها، أو بعد بدء 30 عملية تحميل خلال الساعة الماضية:

الحالة	`detail`	المعنى	الإجراء
409	`org_ingest_in_progress`	توجد عملية ingest أخرى للمؤسسة في حالة `running`.	استعلم عنها حتى تبلغ `succeeded` أو `failed`، ثم أعد التحميل باستخدام `Idempotency-Key` نفسه.
429	`ingest_rate_limited`	أنشأت مؤسستك 30 عملية ingest في الساعة الماضية، وتشمل المعاينات.	انتظر ثم أعد الإرسال. استخدم طلب اقتراح الربط لفحص الربط بدل تكرار المعاينات.
413	`request_body_too_large`	حجم الطلب كله أكثر من 32 MiB.	أرسل ملفًا أصغر؛ راجع الحدود.

إعادة إرسال Idempotency-Key استُخدم سابقًا لا تُعد رفعًا جديدًا؛ بل تعيد عملية الاستيعاب الحالية ولا تُرفض برمزي 409 أو 429 المذكورين أعلاه. ولا تتم مقارنة محتوى الطلب بالطلب الأول، لذلك يُتجاهل أي ملف مختلف يُرسل باستخدام مفتاح مستعمل. ومع ذلك، يُتحقق من الطلب قبل البحث عن المفتاح، لذا قد تُرفض الإعادة برمز 413 أو 403 org_admin_required أو vendor_data_not_on_plan أو 422 بسبب أحد الحدود. ويظل المفتاح محفوظًا ما دام الإصدار المرتبط به موجودًا؛ وبعد حذفه أو إزالته تلقائيًا، يبدأ المفتاح نفسه عملية رفع جديدة.

3. فحص النتيجة


الطلب	`GET /shared-api/datahub/ingests/{ingest_id}`
المخوّل	المالك أو المسؤول في أي خطة

curl https://api.kaleidr.com/shared-api/datahub/ingests/5f0c2a1e-… \
  -H "Authorization: Bearer $KALEIDR_ACCESS_TOKEN"

{
  "ingest_id": "5f0c2a1e-…",
  "release_id": "a81d77b0-…",
  "status": "succeeded",
  "attempts": 1,
  "row_counts": {
    "places": 1,
    "room_types": 0,
    "rate_plans": 0,
    "daily_rates": 0,
    "daily_inventory": 0,
    "hours": 0,
    "documents": 0
  },
  "error_report": null,
  "created_at": "2026-10-10T09:12:04Z",
  "started_at": "2026-10-10T09:12:20Z",
  "finished_at": "2026-10-10T09:12:41Z"
}

تنتقل قيمة status من pending إلى running ثم إلى succeeded أو failed.

عند succeeded يعرض row_counts عدد العناصر المقروءة حسب نوع البيانات. قارنه بالمتوقع قبل النشر.
عند failed تعرض error_report.errors العناصر غير المقروءة وأسبابها بحسب الصف، حتى 200 إدخال. ويعرض error_report.error_count العدد الكلي. لا تغيّر المعالجة الفاشلة النسخة المنشورة.

{
  "status": "failed",
  "error_report": {
    "errors": [
      "places[1]: missing lat/lng -- supply coordinates, or an address to geocode from",
      "places[2]: unknown timezone 'London'"
    ],
    "error_count": 2
  }
}

التحميل إمّا ينجح كاملًا أو يفشل كاملًا. إذا فشل التحقق لأي صف فلا يُجهّز شيء من الملف. أصلح الملف وأعد تحميله باستخدام Idempotency-Key جديد.

4. النشر


الطلب	`POST /shared-api/datahub/ingests/{ingest_id}/publish`
المخوّل	المالك أو المسؤول في Enterprise
الجسم	لا شيء

curl -X POST https://api.kaleidr.com/shared-api/datahub/ingests/5f0c2a1e-…/publish \
  -H "Authorization: Bearer $KALEIDR_ACCESS_TOKEN"

تأتي الاستجابة بهيئة استجابة التجهيز نفسها، مع status: "pending". لا يُسمح بالنشر إلا لعملية ingest جُهّزت باستخدام preview: true وبلغت succeeded.

يُعاد تحليل الملف عند النشر. يُقرأ الملف نفسه وبالربط نفسه فتطابق الأعداد والمعرّفات المعاينة. لكن قد تتغير إحداثيات موقع أُدخل بعنوانه فقط قليلًا إذا أصبحت نتيجة تحديد العنوان أدق.

استعلم عن الحالة مجددًا. تعود عملية ingest إلى pending ثم تُعالج حتى succeeded. وعندها تُنشر النسخة وتُستبدل النسخة السابقة.

فسّر 409 هنا على أنه "العملية جارية"، لا فشل يستدعي إعادة المحاولة. لا يأخذ طلب النشر Idempotency-Key ولا يحتاجه. إذا انتهت مهلة الطلب لديك لكنه نجح لدى Kaleidr، تعيد المحاولة 409 ingest_is_not_a_preview، أو 409 publish_already_in_progress عند تداخل محاولتين. كلتا الحالتين تعني أن النشر المطلوب جارٍ أو تم؛ افحص حالة ingest بدل إعادة الإرسال.

هناك حالة مختلفة للرمز 409: يعني org_ingest_in_progress أن عملية رفع أخرى تخص مؤسستك قيد المعالجة، ولذلك لم يبدأ هذا النشر. انتظر حتى تصل عملية الاستيعاب الأخرى إلى الحالة succeeded أو failed، ثم أعد طلب النشر.

النشر في خطوة واحدة

أرسل preview: false أو احذف preview للنشر فور قراءة الملف دون طلب نشر منفصل. استخدم ذلك للتحميل المتكرر ذي الربط الذي سبق اختباره.

إعادة بدء عملية معالجة عالقة


الطلب	`POST /shared-api/datahub/ingests/{ingest_id}/dispatch`
المخوّل	المالك أو المسؤول في Enterprise

استخدم الطلب إذا بقيت عملية ingest في pending (مثلًا عندما تكون dispatched هي false) أو وصلت failed لسبب لا يتعلق ببياناتك. لا تتكرر معالجة ingest أكثر من ثلاث مرات.

الحالة	المعنى
409 `ingest_already_succeeded`	لا يلزم إجراء.
409 `ingest_already_running`	المعالجة جارية.
409 `ingest_attempts_exhausted`	استُخدمت المحاولات الثلاث؛ أعد التحميل بمفتاح `Idempotency-Key` جديد.
409 `org_ingest_in_progress`	تُعالج عملية ingest أخرى للمؤسسة؛ انتظر اكتمالها ثم أعد الطلب.
404 `ingest_not_found`	لا توجد عملية استيعاب بهذا المعرف في مؤسستك، أو أن الإصدار المرتبط بها قيد الحذف أو حُذف بالفعل. ولا توجد عملية لإعادة تشغيلها.

قائمة النسخ


الطلب	`GET /shared-api/datahub/releases`
المخوّل	المالك أو المسؤول في أي خطة
الاستعلام	`status` اختياري: `draft` أو `published` أو `superseded` أو `failed` أو `deleting`؛ أي قيمة أخرى تعيد 422 `unknown_release_status`. وكذلك `org_id` اختياري.

curl "https://api.kaleidr.com/shared-api/datahub/releases?status=published" \
  -H "Authorization: Bearer $KALEIDR_ACCESS_TOKEN"

[
  {
    "id": "a81d77b0-…",
    "status": "published",
    "published_at": "2026-10-10T09:15:02Z",
    "superseded_at": null,
    "created_at": "2026-10-10T09:12:04Z",
    "state": "published",
    "ingest_id": "5f0c2a1e-…"
  }
]

الحقل	النوع	المعنى
`id`	UUID	معرّف النسخة، ويُستخدم في طلبَي إلغاء النشر والحذف.
`status`	سلسلة	`draft` أو `published` أو `superseded` أو `failed` أو `deleting`.
`published_at`	طابع زمني أو null	وقت نشر النسخة.
`superseded_at`	طابع زمني أو null	وقت فقدانها حالة النسخة الحالية، سواء بالاستبدال أو إلغاء النشر أو انتهاء المعاينة.
`created_at`	طابع زمني	وقت قبول التحميل.
`state`	سلسلة	الإجراءات الممكنة الآن؛ راجع الجدول التالي.
`ingest_id`	UUID أو null	معرّف المعالجة التي أنشأتها، ويُستخدم في طلبَي الحالة والنشر.

الحقل state هو status مع تقسيم حالة المسودة إلى حالتين، حتى تعرف الواجهة أي إجراءات تعرض دون طلب إضافي:

`state`	`status`	المعنى	الإجراء المتاح
`processing`	`draft`	التحميل في الانتظار أو قيد القراءة، بما فيه النشر المباشر ومعاينة يجري نشرها.	انتظر؛ ويمكن حذفه.
`preview`	`draft`	اكتملت المعاينة وتنتظر قرارك.	انشرها أو احذفها.
`published`	`published`	النسخة التي تستند إليها الإجابات.	ألغ نشرها.
`superseded`	`superseded`	استُبدلت بنسخة أحدث أو أُلغي نشرها أو انتهت معاينتها.	احذفها.
`failed`	`failed`	تعذرت قراءة التحميل.	احذفها.
`deleting`	`deleting`	الحذف قيد التنفيذ.	لا شيء.

تتضمن القائمة أحدث 50 نسخة، من الأحدث إلى الأقدم. يمكن أن تكون نسخة واحدة فقط published لكل مؤسسة في الوقت نفسه، ولا تبقى أي نسخة منشورة بعد إلغاء النشر. لا تظهر النسخ قيد الحذف إلا عند طلب ?status=deleting، وتختفي من جميع القوائم عند اكتمال الحذف.

سحب نسخة من الخدمة

هناك عمليتان منفصلتان عمدًا لإزالة البيانات: إلغاء النشر يخرج النسخة المنشورة من الخدمة، والحذف يمحو نسخة غير منشورة. يستطيع المالك أو المسؤول في أي خطة تنفيذهما، حتى بعد مغادرة Enterprise. لا تحتاج أي منهما إلى جسم طلب أو Idempotency-Key، ويمكن تكرارهما بأمان.

في Kaleidr Studio

يعرض كل صف في قائمة Releases ضمن Data for AI Answers الإجراء المناسب مع طلب التأكيد قبل الإرسال. وتظل القائمة وإجراءاها متاحين للمالكين والمسؤولين بعد مغادرة Enterprise ما دامت لدى المؤسسة نسخ محفوظة؛ ويعرض القسم حينها "التحميل جزء من خطة Enterprise." بدل خطوات التحميل.

تسمية الصف	الإجراء	التأكيد	ما يظهر لاحقًا
Published	Unpublish	"هل تريد إلغاء نشر هذه النسخة؟ سيتوقف Kaleidr AI عن الإجابة من هذه البيانات حتى تنشر نسخة أخرى، ولا يمكن نشر النسخة نفسها مجددًا."	"جارٍ إلغاء النشر…" ثم "أُلغي النشر. لم يعد Kaleidr AI يجيب من هذه البيانات." ويتحول الصف إلى Superseded.
Draft أو Superseded أو Failed	Delete	"هل تريد حذف هذه النسخة؟ سيُحذف الإصدار وكل ما أُنشئ منه نهائيًا ولا يمكن التراجع."	"جارٍ الحذف…" ثم "حُذفت النسخة." ويختفي الصف.
Processing	لا شيء

لكل تأكيد زر إجراء وزر Cancel. لا تعرض الشاشة Delete على النسخة المنشورة؛ وتظهر استجابة API حينئذ بالمعنى: "هذه النسخة منشورة. ألغ نشرها قبل حذفها." يشرح دليل قائمة النسخ تفاصيل القائمة.

إلغاء نشر نسخة


الطلب	`POST /shared-api/datahub/releases/{release_id}/unpublish`
المخوّل	المالك أو المسؤول، في أي خطة
الجسم	لا شيء
الاستعلام	`org_id` اختياري

curl -X POST https://api.kaleidr.com/shared-api/datahub/releases/a81d77b0-…/unpublish \
  -H "Authorization: Bearer $KALEIDR_ACCESS_TOKEN"

{ "release_id": "a81d77b0-…", "status": "superseded" }

تخرج النسخة من الخدمة فور عودة استجابة الطلب، وينتج عن ذلك:

لا تبقى لدى مؤسستك نسخة منشورة حتى تنشر أخرى. لا تعود النسخة التي سبقت الحالية تلقائيًا. تستمر الإجابات بالمعرفة العامة دون الإشارة إلى اختفاء بياناتك.
لا يمكن إعادة نشر النسخة نفسها. لاستعادة بياناتها، أعد تحميل الملف وانشره من جديد.
تبقى النسخة في القائمة بحالة superseded ويمكنك الآن حذفها، أو ستتم إزالتها تلقائيًا إن لم تفعل.

الحالة	`detail`	المعنى
200		أصبحت النسخة `superseded`. تعيد المحاولة الرمز 200 نفسه، وكذلك الطلب على نسخة `superseded` أصلًا بسبب استبدالها بوقت سابق.
403	`org_admin_required`	الحساب ليس مالكًا أو مسؤولًا.
404	`release_not_found`	لا توجد نسخة بهذا المعرّف في مؤسستك، أو يجري حذفها.
409	`release_not_published`	النسخة مسودة أو فاشلة ولم تكن منشورة أصلًا؛ فلا شيء لإلغاء نشره.

حذف نسخة


الطلب	`DELETE /shared-api/datahub/releases/{release_id}`
المخوّل	المالك أو المسؤول، أي خطة
الجسم	لا شيء
الاستعلام	`org_id` اختياري

curl -X DELETE https://api.kaleidr.com/shared-api/datahub/releases/a81d77b0-… \
  -H "Authorization: Bearer $KALEIDR_ACCESS_TOKEN"

HTTP/1.1 202 Accepted

{ "release_id": "a81d77b0-…", "status": "deleting", "dispatched": true }

يحذف هذا الإجراء النسخة والملف الذي رُفع لإنشائها وكل ما أنتجه Kaleidr منها، ولا يمكن التراجع عنه.

يجب إلغاء نشر النسخة المنشورة أولًا. حذفها يعيد 409 release_is_published. يمكن حذف أي نسخة أخرى: معاينة، أو مستبدلة، أو فاشلة، أو تحميل لا تزال قراءته جارية.
الاستجابة 202، ويكتمل الحذف بعد وقت قصير من عودتها. تصبح النسخة فورها deleting وتختفي من قائمة النسخ ولا يمكن نشرها، ويعيد طلب ingest الخاص بها 404 ingest_not_found. وينطبق ذلك أيضًا على الاستعلام عن الحالة وإعادة بدء المعالجة.
يوضح dispatched هل بدأ هذا الطلب الحذف. إذا كان false يبدأ تلقائيًا بعد قليل، ويمكنك إعادة الطلب.
تكرار الطلب آمن. أثناء الحذف يعاد 202، وبعد اكتماله لا توجد النسخة ويعاد 404 release_not_found، ويمكن اعتبار 404 "حُذفت سابقًا".

الحالة	`detail`	المعنى
202		حالة النسخة `deleting`، وتتكرر الاستجابة نفسها حتى يكتمل الحذف.
403	`org_admin_required`	لست مالكًا أو مسؤولًا.
404	`release_not_found`	لا توجد نسخة بهذا المعرّف في مؤسستك، بما في ذلك النسخة المحذوفة بالكامل.
409	`release_is_published`	النسخة منشورة؛ ألغ نشرها ثم احذفها.

لتأكيد الحذف، اعرض قائمة النسخ بالمعامل ?status=deleting؛ فالقائمة الفارغة تعني عدم وجود حذف جارٍ.

إزالة النسخ القديمة تلقائيًا

لا تحتاج إلى حذف النسخ التي لم تعد حالية؛ إذ يزيلها Kaleidr تلقائيًا بالطريقة نفسها المستخدمة في طلب الحذف:

النسخة	موعد الإزالة
`superseded`: استُبدلت أو أُلغي نشرها	بعد 30 يومًا من الاستبدال أو إلغاء النشر
معاينة لم تُنشر مطلقًا	تنتهي بعد 14 يومًا، وتُحذف بعد 30 يومًا أخرى
`failed`	بعد 30 يومًا من انتهاء آخر محاولة معالجة
`published`	لا تُزال ما دامت منشورة

ما لا يشمله الحذف

لا تستخدم أي إجابة تُنشأ بعد اكتمال الحذف النسخة المحذوفة. لكن الحذف لا يشمل الإجابات المخزنة مؤقتًا (لفترة محدودة)، أو سجلات المحادثات المحفوظة، أو النسخ الاحتياطية، أو النص الذي سبق إرساله إلى موفر النماذج أثناء المعالجة. يورد دليل حدود الحذف التفاصيل.

الحدود

الحدود المحددة في اتفاقيتك

تحدد اتفاقية مؤسستك الحجم والأعداد المسموح بها في كل تحميل. تفرض المنصة سقفًا تقنيًا لكل حد، ولا يمكن لاتفاقية المؤسسة تجاوزه.

الحد	Enterprise	عند تجاوزه
حجم `artifact`	حسب اتفاقيتك	422 عند التحميل
عدد صفوف CSV دون صف العناوين	حسب اتفاقيتك	422 عند التحميل
عدد المواقع في حزمة JSON	حسب اتفاقيتك	422 عند التحميل
عدد المستندات في حزمة JSON	حسب اتفاقيتك	422 عند التحميل

يعرض GET /shared-api/datahub/limits الحدود الخاصة بمؤسستك.
لا توجد حدود تحميل لخطتي Free وPro لأنهما لا تسمحان بالتحميل أصلًا؛ وتعيد العمليات 403 vendor_data_not_on_plan.
تنطبق الحدود على مستوى المؤسسة. وبما أن النشر يستبدل النسخة السابقة كاملة، تحد هذه الأرقام كل عملية تحميل والبيانات المنشورة معًا.

إذا تجاوز التحميل أحد هذه الحدود، تكون الاستجابة 422 ويذكر كل سبب الحد والخطة المعنيين. يمثّل <count> العدد المُرسل، و<limit> الحد الخاص بمؤسستك:

{ "detail": { "errors": ["<count> places exceed the limit of <limit> (enterprise plan)"] } }

تشبه أسباب الرفض الثلاثة الأخرى الصيغ التالية: <count> documents exceed the limit of <limit> (enterprise plan)، وcsv has more than <limit> rows; the places limit is <limit> (enterprise plan)، وartifact is <size> MB; the limit is <limit> MB (enterprise plan). إذا تجاوز الملف حد الحجم فلا تُستكمل قراءته ويعاد سبب واحد فقط.

الحدود الثابتة لجميع المؤسسات

الحد	القيمة	النتيجة عند التجاوز
حجم طلب التحميل كاملًا	32 MiB	413 `request_body_too_large`
أنواع الغرف في تحميل واحد	10,000	422 لحزمة JSON، أو فشل ingest للجدول المربوط
خطط الأسعار في تحميل واحد	10,000	422 لحزمة JSON، أو فشل ingest للجدول المربوط
صفوف ساعات العمل في حزمة JSON	25,000	422 عند التحميل
صفوف الأسعار الليلية والتوافر معًا لكل عملية رفع	200,000	فشل الاستيعاب: `daily facts: <count> rows exceed the cap of 200000`
إجمالي نصوص المستندات في عملية رفع واحدة	نحو 600,000 حرف كحد أقصى، وأقل عند توزيعها على مستندات كثيرة	فشل الاستيعاب: `documents: chunk count exceeds the cap of 500`
عمق التداخل في JSON	يُرفض التداخل العميق	422 عند التحميل
`mapping_spec`	64 KB	422 عند التحميل
`filename`	200 حرف، ينتهي بـ `.csv` أو `.json`	422 عند التحميل
عدد عمليات التحميل قيد المعالجة لكل مؤسسة	1	409 `org_ingest_in_progress` (عند الرفع والنشر وإعادة بدء المعالجة)
عمليات تحميل جديدة لكل مؤسسة	30 في الساعة	429 `ingest_rate_limited`
`csv_head` للاقتراح	16,384 حرفًا	422
اقتراحات الربط	30 لكل حساب في الساعة، وتستهلك AI	429؛ راجع التمييز بين حالتي 429
محاولات معالجة ingest	3	409 عند إعادة الإرسال
معاينة لم تُنشر	14 يومًا	409 عند محاولة النشر
نسخة لم تعد حالية	30 يومًا	تُزال تلقائيًا

حد حجم الطلب أكبر من حد الملف لأن الملف يُرسل كسلسلة داخل JSON، وقد يزيد حجمه بسبب محارف الهروب. يُرفض الطلب الأكبر من 32 MiB بالرمز 413 قبل قراءته. أما الملف الذي يتجاوز حد مؤسستك مع بقاء الطلب ضمن حجمه فيُرفض بالرمز 422.

يعيد تجاوز حد العدد أو الحجم الاستجابة 422 مع قائمة الأسباب حتى 200 سبب. مثلًا تكون رسالة تجاوز عدد الصفوف لحد ثابت لجميع المؤسسات كالتالي:

{ "detail": { "errors": ["10001 room_types exceed the cap of 10000"] } }

تعيد بنية JSON المتداخلة بعمق زائد شكل الاستجابة نفسه:

{ "detail": { "errors": ["upload is nested too deeply"] } }

يشمل حد CSV جميع صفوف الملف مهما كان محتواها. سيصل جدول يحوي صفًا لكل ليلة إلى الحد بسرعة؛ لذا أرسل مجموعات أسعار وتوافر أكبر كحزمة JSON، حيث تُحصى المواقع والمستندات وأنواع الغرف وخطط الأسعار وساعات العمل عند التحميل.

حدود الحقول

لكل قيمة حجم أقصى. تُقاس النصوص بعدد الأحرف، بينما تُقاس قيم JSON الحرة (كائن أو مصفوفة) بالبايت بعد تحويلها إلى JSON.

القائمة	الحقل	الحد
كل القوائم	`ref`, `place_ref`, `room_type_ref`, `rate_plan_ref`	128 حرفًا
`places`	`name`	200 حرف
`places`	`category`	100 حرف
`places`	`timezone`	64 حرفًا
`places`	`overture_id` (اختياري)	128 حرفًا
`places`	`address`	2,048 بايت بصيغة JSON
`places`	`schema_org` (كائن اختياري)	16,384 بايت بصيغة JSON
`room_types`	`name`	200 حرف
`room_types`	`amenities` (مصفوفة اختيارية)، `attributes` (كائن اختياري)	8,192 بايت بصيغة JSON لكل منهما
`rate_plans`	`name`	200 حرف
`rate_plans`	`currency` (اختياري)	3 أحرف
`rate_plans`	`cancellation_policy` (اختياري)	2,000 حرف
`rate_plans`	`board_basis` (اختياري)	100 حرف
`rate_plans`	`attributes` (كائن اختياري)	8,192 بايت بصيغة JSON
`hours`	`note` (اختياري)	500 حرف
`documents`	`title`	300 حرف

يتوقف موضع الإبلاغ عن تجاوز الحد على نوع الملف المُرسل:

حزمة JSON: تُفحص عند التحميل وتعيد 422، مع تحديد الصف والحقل لكل خطأ، مثل places[3]: name is longer than 200 characters أو room_types[0]: amenities is larger than 8192 bytes as JSON.
CSV مواقع أو جدول مربوط: تُفحص الحقول أثناء معالجة ingest، وتنتهي العملية بحالة failed مع الأسباب نفسها في error_report.errors.

إذا احتوت قيمة JSON حرة على NaN أو Infinity يظهر الخطأ <list>[<row>]: <field> holds a non-finite number.

انتهاء صلاحية المعاينات

تُحال المعاينة التي لم تُنشر إلى التقاعد بعد 14 يومًا من إكمال تجهيزها. تصبح superseded وتظل ظاهرة مؤقتًا في قائمة النسخ، لكن لا يجوز نشرها. تعيد محاولة النشر 409 no_previewed_release_to_publish؛ أعد تحميل الملف للمتابعة. وكغيرها من النسخ المستبدلة تُزال تلقائيًا بعد 30 يومًا إضافية، أو يمكنك حذفها قبل ذلك.

ملاحظات حول الحقول

timezone إلزامي لكل موقع ويؤثر في الإجابات. تُقرأ الأسعار والتوافر وفق التقويم المحلي لكل موقع؛ فـ"الليلة" في فندق بسيدني تاريخ مختلف عن "الليلة" في لندن. إذا لم يحتو الملف على عمود المنطقة الزمنية، اربطه بقيمة ثابتة:

{ "timezone": { "const": "Australia/Sydney" } }

اختر المنطقة الزمنية بعناية. تؤدي المنطقة الخاطئة إلى إجابات صحيحة معظم اليوم وخاطئة قرب منتصف الليل. ويُبلّغ عن غياب المنطقة أو استخدام اسم لا تعتمده IANA كخطأ.

أرسل الإحداثيات متى توفرت. تُستخدم lat وlng كما وردتا. وإذا أُرسل عنوان فقط، تُستخرج إحداثياته؛ وتُرفض المطابقة غير الواثقة بدل التخمين ويُطلب منك توفير الإحداثيات. وجود دبوس في موقع خاطئ أسوأ من الإبلاغ عن موقع غير محدد.

إعادة تحميل الملف المصدَّر نفسه آمنة. في الجداول المربوطة تُشتق المعرّفات من الأعمدة المعينة في ref_from، لذلك ينتج التصدير نفسه المعرّفات نفسها. تستبدل النسخة الجديدة السابقة ولا تُضاف إليها.

كل نسخة مكتملة بذاتها. لا ينتقل أي شيء من النسخة السابقة. فإذا حذف الملف مواقع الشهر الماضي، تختفي من الإجابات بعد نشره.

أرسل نص UTF-8. تُرفض الملفات ZIP أو GZIP أو PDF التي تُعاد تسميتها إلى .csv أو .json.

الأخطاء

تستخدم أخطاء التحميل الصيغة { "detail": "<code>" }، باستثناء الحالات التي تعيد قائمة أسباب.

الحالة	`detail`	المعنى
401		رمز الوصول غائب أو منتهي أو ليس رمز وصول.
403	`org_admin_required`	الحساب ليس مالكًا أو مسؤولًا للمؤسسة.
403	`vendor_data_not_on_plan`	المؤسسة ليست على Enterprise. يحدث عند التحميل والنشر وإعادة الإرسال؛ ولا تُرفض القراءة أو إلغاء النشر أو الحذف بسبب الخطة.
404	`ingest_not_found`	لا توجد معالجة بهذا المعرّف في المؤسسة أو نسختها قيد الحذف أو حُذفت.
404	`release_not_found`	لا توجد نسخة بهذا المعرّف، بما في ذلك النسخ التي اكتمل حذفها.
409	`release_not_published`	طُلب إلغاء نشر نسخة مسودة أو فاشلة.
409	`release_is_published`	طُلب حذف نسخة منشورة؛ ألغ نشرها أولًا.
409	`ingest_conflict`	تعارض تحميلان باستخدام `Idempotency-Key` نفسه؛ أعد الطلب.
409	`ingest_is_not_a_preview`	لم تُجهّز العملية للمعاينة أو طُلب نشرها سابقًا.
409	`ingest_already_running`	المعالجة جارية.
409	`no_previewed_release_to_publish`	فشلت المعاينة أو لم تنته أو انتهت صلاحيتها.
409	`publish_already_in_progress`	تداخل طلبا نشر؛ أحدهما ينفّذ.
409	`ingest_already_succeeded`	طُلبت إعادة معالجة مهمة مكتملة.
409	`ingest_attempts_exhausted`	طُلبت إعادة المعالجة بعد ثلاث محاولات.
409	`org_ingest_in_progress`	يجري تنفيذ ingest آخر للمؤسسة؛ انتظر اكتماله.
413	`request_body_too_large`	تجاوز طلب التحميل 32 MiB. الحد لطلبات النشر وإعادة الإرسال والقراءة 1 MiB.
422	`{ "errors": [ … ] }`	تجاوز حجم الملف أو الربط أو أحد الحقول حدوده، أو تعمّق JSON، أو تعذر قراءة الملف كـCSV أو JSON. تظهر الأسباب كسطور، وتذكر حدود الخطة عند تجاوزها.
429	`ingest_rate_limited`	بدأت المؤسسة 30 عملية تحميل خلال ساعة.
422	قائمة تحقق	حقل مفقود أو غير صحيح مثل غياب `Idempotency-Key` أو لاحقة ملف غير مقبولة أو `source` خارج القيم الثلاث.
422	`unknown_release_status`	قيمة مرشح `status` ليست واحدة من القيم الخمس.

إذا تجاوز الملف حد حجم مؤسستك، تعيد الخدمة 422 مع السبب في errors. تعني 413 أن الطلب كله تجاوز الحد، ويكون جسمها { "detail": "request_body_too_large" }.

للطلب الخاص باقتراح الربط أخطاؤه المبينة في اقتراح الربط. يُرفض بالرمز 403 org_admin_required أو vendor_data_not_on_plan حين لا يحق للحساب التحميل، وبالرمز 429 عند بلوغ الحد بالساعة أو نفاد رصيد AI.

ميزات غير متاحة حاليًا

التحديثات التزايدية: لا توجد عملية upsert أو حذف سجل منفرد أو استعلام "ما الذي تغير منذ". تستبدل النسخة الجديدة السابقة بالكامل، ويمكن إلغاء نشر أو حذف النسخة كاملة.
إعادة نشر نسخة قديمة: لا يجوز جعل نسخة superseded أو غير منشورة حالية؛ أعد تحميل الملف.
حفظ روابط الأعمدة: يُرسل الربط مع كل تحميل ولا يُخزّن لتسميته بمعرّف.
الموصلات: لا يسحب Kaleidr البيانات من قواعد البيانات أو أنظمة الحجز أو خدمات الجداول.
التحميل متعدد الأجزاء أو الثنائي: يُنقل الملف كسلسلة نصية داخل جسم JSON.

صفحات ذات صلة

الإجابات من بياناتك الخاصة: العملية كاملة وخططها وحدودها والتحقق منها، وميزة مجموعات بيانات الخريطة المتاحة لجميع الخطط.
المصادقة والنطاقات: إصدار المفتاح القادر على قراءة البيانات.
الأخطاء: فهرس الأخطاء في المنصة.

موضع هذه الميزة​

الإتاحة​

ما الذي تستطيع مؤسستك تحميله؟​

المصادقة​

البيانات التي يمكنك تحميلها​

ملف CSV للمواقع​

جدول بيانات مع ربط الأعمدة​

حزمة JSON​

تسلسل التحميل​

1. اقتراح ربط الأعمدة (اختياري)​

التمييز بين حالتي 429​

2. تجهيز معاينة​

3. فحص النتيجة​

4. النشر​

النشر في خطوة واحدة​

إعادة بدء عملية معالجة عالقة​

قائمة النسخ​

سحب نسخة من الخدمة​

في Kaleidr Studio​

إلغاء نشر نسخة​

حذف نسخة​

إزالة النسخ القديمة تلقائيًا​

ما لا يشمله الحذف​

الحدود​

الحدود المحددة في اتفاقيتك​

الحدود الثابتة لجميع المؤسسات​

حدود الحقول​

انتهاء صلاحية المعاينات​

ملاحظات حول الحقول​

الأخطاء​

ميزات غير متاحة حاليًا​

صفحات ذات صلة​