Docs

الإصدارات وتغييرات API

آخر تحديث: 2026-10-0310 دقيقة قراءة

الإصدار

الإصدار الرئيسي في المسار: /api/v1. داخل v1 لا نكسر التكاملات القائمة. الإصدار الحالي للعقد هو info.version في /openapi.json، ويزداد مع كل تغيير.

ما الذي قد يتغير دون إشعار

هذه التغييرات متوافقة، ويجب أن يتعامل عميلك معها:

  • عمليات وأدوات جديدة؛
  • حقول طلب جديدة اختيارية؛
  • حقول رد جديدة؛
  • قيم جديدة في تعدادات الردود (الحالات، والرموز)، ورموز أخطاء جديدة في title، وأنواع جديدة من أحداث webhook؛
  • تغييرات في نص detail؛
  • حدود أعلى.

كيف تكتب العميل

  • تجاهل حقول الرد غير المعروفة.
  • تعامل مع قيمة تعداد أو رمز خطأ أو نوع حدث غير معروف على أنه «آخر» لا على أنه عطل.
  • ابنِ التفرع على status وtitle وcode، لا على نص detail.
  • لا تعتمد على ترتيب الحقول أو طول المعرّفات.
  • اعتمد على حالة المهمة state، لا على status الخام للأداة.

ما الذي يُعد كاسرا

حذف عملية أو حقل أو نطاق أو حدث أو إعادة تسميته؛ حقل طلب إلزامي جديد؛ تغيير نوع الحقل أو معناه؛ تغيير رمز الحالة للحالة نفسها؛ تضييق القيم المسموح بها. لا نجري هذه التغييرات في v1 دون إشعار: تُعلَّم العملية أولا بأنها deprecated في /openapi.json وفي هذا السجل، وتستمر في العمل 6 أشهر على الأقل. الاستثناء هو سد ثغرة أمنية.

التصحيح الذي يجعل الرد مطابقا لهذا التوثيق ليس تغييرا كاسرا.

سجل التغييرات

2026-10-03: الإصدار 1.16

تغيّر:

  • يحمل 429 الحقل code: minute_limit أو daily_limit (الحد اليومي للمفتاح، يُعاد ضبطه عند 00:00 UTC).
  • العقار المكتوب بمفتاح وكالة يخص الوكالة؛ وتصل ويب هوك object.* وlead.* لعقارات الوكالة وعملائها إلى عناوين الوكالة أيضا.
  • صور العقار: حتى 50 لكل نوع، كما في لوحة التحكم.
  • SDK 1.7.2: لم يعد جزء فارغ من التدفق يقسم حدث الدردشة.

أُصلح:

  • يحافظ PUT /objects/{kind}/{id} على حالة الإشراف وisSold ونشر العقار؛ وكان يعيد ضبطها (تعديل عادي كان يلغي نشر عقار منشور).
  • لم يعد GET /objects يعرض عقارات المالكين الموقوفين؛ ولا تُقدَّم بالمعرّف بطاقة مخفية عن الزوار.
  • PATCH /leads/{id}: يستطيع مرسل العميل بلا عقد تغيير حالته كما في لوحة التحكم؛ ويُسجَّل التغيير والأرشفة في سجل العميل.

2026-10-03: الإصدار 1.15

تغيّر:

  • يتبع PATCH /leads/{id} (الحالة) وDELETE /leads/{id} قواعد لوحة التحكم: الإنهاء وتحصيل العمولة والعقد أو الاتفاق الساري: 422 مع السبب في code. ولم يعد ?expand=history يحمل بيانات وصفية داخلية (رموز، ومعرّفات مستخدمين آخرين).
  • يرد الحد اليومي للدردشة المجانية بـ code: free_daily_limit مع Retry-After حتى الساعة 00:00 UTC.
  • GET /works: الحقول previewUrl وlink وobject.photoUrl مسارات /files/... لـ GET /artifacts/{path}؛ وفي الصفحة الأخيرة تكون nextCursor بقيمة null.
  • إنشاء العميل: تُسقط الحقول غير المعروفة (ولا تُرفض)؛ وتذكر المواصفة الأطوال التي تتحقق منها الخدمة؛ وpool: true يسلّم العميل إلى مجمع المنصة.
  • SDK 1.7.1: ينتظر jobs.wait انقضاء 429؛ ويعالج chat.stream CRLF المقسوم بين الأجزاء؛ ويقبل artifact() المعامل signal.

أُصلح:

  • معاينة الموسيقى: Range بعد نهاية الملف يعطي 416 (كان يعطي 404)؛ وعطل خدمة الملفات يعطي 502 لا 404.
  • الملف الأكبر من 15 ميغابايت في POST /uploads يعطي 413. ورفض strictPhotos يذكر الصور التي فشل تحميلها (code: photo_fetch_failed).
  • رفض حزمة المحتوى يذكر form.media.photos. بيئة الاختبار: تأخذ مراجعة التقرير أول ملف بأي اسم؛ ولا تُرفض نصوص الإيجار ولا مفاتيح الصورة الداخلية.

2026-10-03: الإصدار 1.14

تغيّر:

  • إعادة التقييم السريع بالمفتاح Idempotency-Key نفسه أصبحت مجانية تماما: لا يُخصم استدعاء API أيضا.
  • GET /works: قيمة cursor التي ليست nextCursor تعطي 400 (كانت القائمة تبدأ من جديد بصمت).
  • POST /webhooks/{id}/test: قيمة eventType غير الموجودة في القائمة تعطي 400 (كان يُرسل اختبار عام).
  • Swipe Match: لا يقبل reasonCode إلا الأسباب المدرجة، كما كانت الخدمة تشترط دائما؛ ويمكن أن تكون قيمة kind للعميل pool.
  • SDK 1.7.0: يصمد jobs.wait أمام استعلام فاشل واحد؛ ويقبل artifact() المعامل range؛ ويقرأ chat.stream تدفقات CRLF ويستدعي مرة لكل حدث.

أُصلح:

  • معاينة الموسيقى: bytes=-N تعيد آخر N بايت، وRange بعد نهاية الملف يعطي 416.
  • انتهاء مهلة الاتصال قبل إرسال الطلب يحرر Idempotency-Key.
  • بيئة الاختبار: صور الفيديو بأي اسم حقل تقرؤه الخدمة، وأرقام الإيجار كنصوص، وصور PNG للمنشور بالحجم المذكور.

2026-10-03: الإصدار 1.13

أُضيف:

  • يعيد GET /works ما تعرضه لوحة التحكم لكل نتيجة: street وstreetNumber وpreviewUrl وlink وrepeatIndex وerror والعقار (object).
  • يوثّق GET /chat/sessions معاملاته: limit وcursor وq وprojectId وarchivedOnly وsort.
  • يتضمن Problem.title في المواصفة القيمة range_not_satisfiable؛ وتحمل قائمة الويب هوك requestId.
  • SDK 1.6.1: يقبل chat.listSessions معاملات القائمة.

تغيّر:

  • تذكر المواصفة حدودا كان الإنتاج يطبقها أصلا: scriptText للأفاتار حتى 1200 حرف، وformats للمنشور حتى 3 وlayouts حتى 5، وأطوال حقول contacts للمنشور، وseed للصورة حتى 2147483647، ولا مفاتيح غير معروفة في data للصورة.
  • التقييم السريع: لا ترفض البوابة إلا طلبا بلا مساحة إطلاقا وبلا نوع عقار؛ والخدمة تقرر هل تُحتسب landPlotArea (وتُحتسب أيضا للأرض المذكورة في propertyType أو apartmentType).

أُصلح:

  • ترفض بيئة الاختبار الصور كما يرفضها الإنتاج (JPEG أو PNG أو WebP حتى 25 ميغابايت: JOB_CREATE_FAILED؛ والقناع خارج cleanup: MASK_NOT_SUPPORTED) وتقبل ما يقصّه الإنتاج أو يستبدله (عنوان الفيديو ومستوى الصوت والإطار الختامي وخيارات العبارة الختامية، ولغة صفحة الهبوط، وأكثر من 20 صورة للمحتوى، وfurnished كلمةً في الإيجار). ولم تعد مهمة التقرير تُظهر pending بعد running.
  • إعادة توجيه التنزيل المرفوضة تُذكر كما هي لا كانتهاء مهلة؛ ولاحقة Range الأطول من الملف تعيد الملف كله.
  • SDK 1.6.1: تعمل verifyWebhookSignature في Node 18.

2026-10-03: الإصدار 1.12

أُضيف:

  • 416 range_not_satisfiable كمشكلة RFC 9457 (كان يصل بجسم فارغ).
  • priceMinor عند بدء تحسين الصور: ما يُخصم مقابل الاستدعاء كما تعرضه لوحة التحكم.
  • SDK 1.6.0: يقبل works المعاملين from/to، ويقبل chat.history المعاملين limit/cursor، ويقبل chat.sendMessage المعامل style.

تغيّر:

  • GET /match/leads: قيمة limit أكبر من 50 أو page أكبر من 1000 تعطي 400 (لم تكن تُقصّ قط). POST /match/leads/{id}/events: مفتاح Idempotency-Key بصيغة أخرى يعطي 400 بدل تجاهله بصمت.
  • الحقل الذي يرفضه المنشور الإعلاني يعطي 400 validation مع اسم الحقل (كان 422).
  • الاستدعاء الذي ما زال دفعه قيد الحجز تحت Idempotency-Key نفسه يعطي 409 idempotency_conflict (كان 422).
  • التقييم السريع: تُحتسب landPlotArea مساحةً فقط مع land، كما في الخدمة.
  • انتهاء المهلة أو انقطاع الاتصال أو إغلاق المقبس في منتصف الرد يُبقي Idempotency-Key محجوزا؛ ولا يحرره إلا طلب لم يصل إلى الخدمة.
  • SDK 1.6.0: لا يُعاد الرفع أبدا بعد 503؛ ويُزال مستمع الإلغاء بعد كل فترة انتظار.

أُصلح:

  • رفض PDF وصفحة الهبوط يحمل سببه: 402 مع INSUFFICIENT_FUNDS أو QUOTA_EXCEEDED (كان 422 دون code).
  • بيئة الاختبار ترفض تماما ما يرفضه الإنتاج: نوع الملفات المرفوعة وحجمها؛ والنصوص تُقصّ بدل رفضها؛ وقيم length وaspect وlanguage غير المعروفة للفيديو تعود إلى الافتراضي؛ ورموز المنشور الإعلاني لا تميّز حالة الأحرف؛ ومسودة دون type. ومحاكاة نقص الرصيد ترد بالرمز INSUFFICIENT_FUNDS الذي يرسله الإنتاج.
  • البوابة نفسها تقصّ limit وpage إلى النطاق (GET /chat/history?limit=500 كان يرد 400؛ وlimit=0 كان يعطي 20 بدل 1).

2026-10-03: الإصدار 1.11

أُضيف:

  • نتائج المهام تحمل الحقول التي تعرضها لوحة التحكم: حزمة المحتوى والنصوص والفيديو progress وmasterProfile (الإطار القصصي الذي بُنيت عليه النصوص والتعليق الصوتي) وerror للمهمة الفاشلة؛ الصور metadata.error؛ المخطط rooms[].stable وrooms[].placement وsourceFileId.
  • يمكن للمتصفحات (CORS) قراءة الترويسات RateLimit-* وRetry-After وGrem-Sandbox وX-Request-Id وContent-Range.

تغيّر:

  • Webhooks: مفتاح الاختبار ينشئ ويدير عناوين بيئة الاختبار فقط؛ وهذه لا تتلقى إلا أحداث مهام بيئة الاختبار، والعناوين الفعلية لا تتلقاها أبدا.
  • limit وpage خارج المدى يُردّان إليه بدلا من 400؛ وkind في GET /objects لا يتأثر بحجم الأحرف؛ وrooms قد تكون كسرية.
  • Idempotency-Key يرتبط بمفتاح API والطريقة والمسار الفعلي (POST /objects/property وPOST /objects/rental عمليتان مختلفتان). بعد انتهاء المهلة يحجز إنشاء العقار والعميل المحتمل المفتاح 15 دقيقة مثل الأدوات؛ والطلب الذي لم يصل إلى الخدمة يحرر المفتاح.
  • text/generate: تُقص customDirection إلى 500 حرف.
  • SDK 1.5.1: الرد 503 على الكتابة يُعاد فقط مع Idempotency-Key؛ ولا يُنتظر Retry-After أطول من 30 ثانية؛ وmaxRetries حده الأقصى 10؛ وAbortSignal الخاص بك يلغي الانتظار؛ ومعرّفات الرسائل تعمل في Node 18.

أُصلح:

  • بيئة الاختبار تعمل كالإنتاج: فحص حقول multipart وحقول التقرير حسب الفئة وقيم تدفئة المنزل وقيم apartmentType التجارية والمجمعات؛ الملفات فقط للمهام المكتملة، على مسار أداتها ومع معرّفات عناصر معروفة؛ Grem-Sandbox أيضا في الردود الصادرة قبل فحص المفتاح؛ Grem-Simulate لا يتأثر بحجم الأحرف.
  • دون مفتاح، تعيد معاملات الاستعلام غير الصالحة 401 أولا.
  • مفتاح الوكالة المرتبط بوكيل لم يعد يقرأ المهام التي بدأت بمفتاح الوكالة العام.
  • عناوين webhook المحفوظة سابقا بمنفذ آخر تستمر في تلقي التسليمات.
  • Range غير القابل للتلبية يعيد 416 بدلا من 404؛ ويُقبل مستند مراجعة التقرير حتى 40 ميغابايت.

2026-10-03: الإصدار 1.10

أُضيف:

  • رمز الخطأ conflict (409): المورد في حالة لا تسمح بالإجراء (الأخطاء).
  • حقول العبارة الختامية للفيديو في POST /video/create: ctaMode، ctaIntent، ctaText، ctaMarket؛ وخيارات GET /video/endings تحمل intent وtext.
  • GET /works: المرشحان from وto.
  • SDK 1.5.0: الخيار maxRetries؛ يُعاد 429 و503 بعد Retry-After.

تغيّر:

  • معاملات الاستعلام تُفحص: المعامل المعروف بقيمة غير صالحة يعيد 400 validation مع اسم الحقل.
  • Webhooks: https على المنفذ 443 فقط، دون بيانات دخول في URL؛ والعنوان الحادي عشر يعيد 422؛ وتُدار Webhooks الوكالة بمفتاح الوكالة كلها فقط.
  • Idempotency-Key يرتبط بمفتاح API وبالعملية؛ وبعد انتهاء مهلة أداة يبقى المفتاح محجوزا 15 دقيقة.
  • الرفض لأسباب مالية (الحصة، الدين، الاستخدام العادل، الرصيد) هو 402 insufficient_funds مع code.
  • مفتاح الوكيل في الوكالة يرى مهامه وملفاته فقط.
  • تنزيل الملفات يُحسب ضمن حد المعدل.

أُصلح:

  • كل خطأ، بما فيه الجسم الكبير جدا أو التالف، يصل بصيغة RFC 9457 application/problem+json؛ والجسم الذي يتجاوز الحد يعيد 413 payload_too_large.
  • حقل الفيديو ending لم يكن يُقرأ أبدا؛ استخدم ctaIntent أو ctaText.
  • SDK: simulate مع مفتاح حقيقي يرمي خطأ بدلا من تنفيذ الاستدعاء.

2026-10-03: الإصداران 1.8-1.9

أُضيف:

  • العقارات المماثلة: estimate.analogs في التقييم السريع، وanalogs في التقرير الكامل، وcomps في تقدير الإيجار - كما في لوحة التحكم وملف PDF.
  • حقول المهام المكتملة موصوفة بالكامل: أرقام التقرير بأسمائها الحقيقية (potPrice، priceRangeLow، priceRangeHigh، …)، ومراجعة التقرير، والمخطط، والصورة، والنشرة، والمسودة.
  • SDK 1.4.0: النوع Analog.

تغيّر:

  • ردود الأدوات تحمل الحقول الموصوفة فقط؛ الحقول الداخلية التي كانت تتسرب لم تعد تُعاد.
  • الأداة التي يُظهرها GET /tools/status غير متاحة تردّ 503 service_unavailable قبل أي خصم (سابقًا فقط حزمة المحتوى والنصوص والفيديو).
  • رد تأكيد مراجعة التقرير يحمل حقول المهمة فقط (jobId، state، status)؛ ولم يعد فيه _id القديم.

أُصلح:

  • فيديو الأفاتار: artifacts يحوي المعرّفات اللازمة لرابط التنزيل.
  • checkIn/checkOut للإيجار موصوفان كساعة من اليوم.

2026-10-02: الإصدار 1.7

أُضيف:

  • بيئة الاختبار: مفاتيح الاختبار (gsk_test) تحاكي الأدوات دون خصم؛ والترويسة Grem-Simulate تختار النتيجة.
  • estimate.confidenceScore في التقييم السريع.

تغيّر:

  • الاستدعاءات التي تشغّل أداة تنتظر حتى 5 دقائق بدلا من 60 ثانية.
  • التقييم السريع المعاد بالمفتاح Idempotency-Key نفسه يعيد النتيجة الجاهزة دون خصم ثان، بما في ذلك بعد انتهاء المهلة.

أُصلح:

  • كان estimate.confidence في التقييم السريع دائما null.
  • لم تعد ردود المخطط تحتوي على حقول داخلية.
  • GET /objects دون kind وحالات رفض العقارات والعملاء المحتملين تشرح الآن السبب في detail.

2026-10-02: الإصدار 1.6

تغيّر:

  • كل رد مهمة يحتوي على الحقل نفسه jobId. الأسماء السابقة id و_id وcontentGenJobId ما زالت تُعاد لكنها مهملة.
  • SDK 1.2.0: الحقل Job.jobId موجود دائما.

2026-10-02: الإصدارات من 1.2 إلى 1.5

أُضيف:

  • GET /voices، GET /avatar/avatars، GET /video/music، GET /video/endings: معرّفات للأدوات (البيانات المرجعية).
  • GET /tools/status: إتاحة الأدوات؛ GET /works: سجل الأعمال.
  • POST /flyer/create: النشرة الشخصية، النطاق tools:flyer.
  • POST /valuation/review/jobs/{id}/confirm: تأكيد بيانات مراجعة التقرير.
  • الحقل state في كل رد مهمة.
  • في الأخطاء: الحقلان code وerrors، والرموز forbidden وpayload_too_large وservice_unavailable.
  • في وصف API: مخططات كاملة للطلب والرد لكل أداة، وعقد كتابة العقارات الكامل لكل نوع، وفئة الفوترة لكل عملية (x-grem-billing)، وقائمة النطاقات والأحداث.
  • توثيق المعاملين scope (العقارات) وpool (العملاء المحتملون).

تغيّر:

  • الرفض بسبب نقص البيانات (مثلا نصوص دون وصف أو مدينة) صار 422 business_rule مع سبب ورمز. كان سابقا 502 provider_error.
  • الرفض بسبب صلاحيات على مورد صار 403 forbidden مع سبب. كان سابقا 500.
  • التسليم التجريبي لـ webhook الخاص بالأدوات صار بشكل التسليم الحقيقي نفسه: { jobId, status, state }.

أُصلح:

  • مفاتيح الوكالة تعمل مع كل الأدوات والمحادثة وتنزيل الملفات.
  • مراجعة التقرير والمخطط: حالة المهمة متاحة بالمعرّف الوارد في الرد، وتصل webhooks.
  • تنزيل ملفات حزمة المحتوى والنصوص والفيديو متاح لمالك المهمة فقط.

مقالات ذات صلة

هل كانت هذه المقالة مفيدة؟