ثلاثة أنواع من العقارات (kind): property للبيع، وrental للإيجار، وcomplex مجمع سكني. القراءة مجانية ومتاحة لأي مفتاح؛ والإنشاء والتعديل والحذف تتطلب النطاق objects:write ولا تُخصم أيضا.
القائمة
curl "https://developers.grem.capital/api/v1/objects?kind=property&city=Berlin&limit=20" \
-H "Authorization: Bearer gsk_live_xxx"
GET /objects:
| المعامل | الوصف |
|---|---|
kind | إلزامي: property أو rental أو complex؛ لا يهم حجم الأحرف |
city، country | مرشحات بمطابقة تامة |
priceMin، priceMax | السعر بالدولار الأمريكي (حسب السعر الموحد) |
areaMin، areaMax | المساحة، م² |
rooms | الغرف (البيع والإيجار)؛ قد تكون كسرية |
type، residentialType | الفئة: رموز من القواميس (البيع والإيجار) |
page | الصفحة، من 1؛ القيمة الأصغر تُعد 1 |
limit | لكل صفحة، الافتراضي 20، من 1 إلى 50؛ القيمة خارج المدى تُردّ إليه |
sort | newest (افتراضي) أو oldest |
scope | لمفاتيح الوكالة فقط: افتراضيا عقارات الوكالة؛ catalog الكتالوج العام |
الرد: data العقارات، وpaginate يحتوي currentPage وtotalPages وtotalCount.
limit وpage خارج المدى يُردّان إليه ولا يُرفضان. أما القيم غير الصالحة الأخرى لمعامل معروف (قيمة تعداد غير معروفة، أو page غير صحيح، أو نص بدل رقم) فتُرفض بـ 400 validation مع اسم الحقل.
عقار واحد
GET /objects/{kind}/{id}: عقار واحد بالشكل نفسه. المعرّف غير المعروف: 404. يمكن لمفتاح الوكالة إضافة scope=catalog للحصول على العرض العام.
شكل العقار
| الحقل | الوصف |
|---|---|
id، kind، name، slug | الهوية |
status | لعقار غيرك: active أو sold |
type | الفئة: رمز |
price، currency | السعر؛ وللمجمع price: { from, to, currency } |
constructionYear | سنة البناء، عدد صحيح أو null |
address | العنوان الكامل مع الشارع والإحداثيات |
nativeAreaUnit | الوحدة التي أُدخل بها العقار (للعرض)؛ تأتي المساحات بصيغة { "value": 50, "unit": "m2" } |
photos | الصور: id، isMain، mimetype، variants، ready |
processingStatus | ready أو processing أو failed: هل الصور جاهزة |
promoted | العقار مروَّج |
author | وكيل العقار أو وكالته |
الفئات والسمات الأخرى رموز؛ والتسميات المترجمة في القواميس. وللمجمع أيضا apartmentPlans (المخططات) وprogress (تقدم البناء).
ready: false في صورة يعني أن النسخ ذات العلامة المائية ما زالت قيد الإنشاء. اعرض عنصرا نائبا وأعد قراءة العقار لاحقا، ولا تحفظ صورة غير مكتملة في الذاكرة المؤقتة.
ما الذي تراه: أي عقار، البطاقة العامة كما في الموقع؛ وعقاراتك، العرض الكامل للمالك. لا أحد يحصل على جهات اتصال المالك، أو بيانات البائع من الاستيراد، أو ملاحظات الإشراف، أو الأصول دون علامة مائية.
الإنشاء والتعديل والحذف
| الإجراء | الطلب | الرد |
|---|---|---|
| إنشاء | POST /objects/{kind} | 201 مع العقار |
| تعديل | PUT /objects/{kind}/{id} | العقار؛ للمالك فقط، وإلا 404 |
| حذف | DELETE /objects/{kind}/{id} | المسودة تُحذف نهائيا، والعقار المنشور يُؤرشف؛ والعقار المرتبط بعقد عمولة ساري: 409 conflict |
curl -X POST https://developers.grem.capital/api/v1/objects/property \
-H "Authorization: Bearer gsk_live_xxx" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: 9a1d2c3b-4e5f-4a6b-8c7d-0e1f2a3b4c5d" \
-d '{
"name": "شقة من غرفتين، Torstraße 12",
"type": "Residential",
"address": { "country": "Germany", "city": "Berlin", "street": "Torstraße", "streetNumber": "12" },
"price": 320000, "currency": "EUR",
"spaceAll": 64, "rooms": 2, "floor": 3, "buildingFloor": 5,
"photos": ["https://example.com/1.jpg"],
"publish": false
}'
publish: false(افتراضي) مسودة خارج الكتالوج؛publish: trueمنشور. للنشر تحتاجpropertyوrentalإلى صورة واحدة على الأقل، وcomplexإلى صورتين.- ليس كل دور في الحساب يستطيع إنشاء كل الأنواع، كما في لوحة التحكم.
- الحقول غير المعروفة تُتجاهل. خذ رموز الفئات من القواميس. رموز
conditionوconditionTypeوamenities(بصيغة camelCase مثلneedsRenovationوfridge) مدرجة في مخطط الكتابة نفسه (الجداول أدناه و/openapi.json)، ولا يفكGET /dictionariesترميزها. - المساحات: رقم بالمتر المربع أو
{ "value": 700, "unit": "ft2" }. PUTدونphotosيُبقي الصور الحالية.Idempotency-Keyعند الإنشاء يمنع التكرار عند الإعادة.
الصور
photos مصفوفة، وكل عنصر فيها:
- عنوان عام
https://...: ينزّل GREM الصورة بنفسه؛ - معرّف ملف مرفوع عبر
POST /uploads(الملفات).
العنوان الذي يتعذر تنزيله يُتخطى ويُذكر في warnings ضمن الرد. ومع strictPhotos: true يفشل هذا الطلب بدلا من ذلك بـ 422.
حقول البيع
الإلزامية: name، type، address، price.
| الحقل | الوصف |
|---|---|
type | Residential أو Commercial أو Industrial أو Land plot |
residentialType، commercialType، industrialType | النوع الفرعي: رمز أو مصفوفة رموز |
marketSegment | primary (بناء جديد) أو secondary |
description | الوصف، حتى 5000 حرف |
address | country، city (إلزامي)، district، region، street، streetNumber، postalCode، location |
price، currency | السعر؛ والعملة UAH، USD، EUR، AZN، GBP، AED، CNY، TRY، GEL |
constructionYear | السنة من 1700 إلى 2100 |
spaceAll، spaceLiving، spaceKitchen، effectiveArea، auxiliaryArea، landPlotArea | المساحات |
rooms، bedrooms، numberOfBathrooms، balconies، numberWindows، unitsCount | الأعداد |
floor، buildingFloor، ceilingHeight | الطابق، وعدد الطوابق، وارتفاع السقف |
condition | needsRenovation، partialRenovation، renovated، designer، shellCore، newFromDeveloper |
buildingType | newBuilding، secondary، stalinka، khrushchevka، brezhnevka، czech، gostinka، prerevolutionary، townhouseRow، detached، other |
wallMaterialType، constructionTech، kitchenType | مادة الجدران، وتقنية البناء، ونوع المطبخ |
amenities، buildingAmenities | مرافق الوحدة والمبنى: مصفوفات رموز |
utilitySystem، heating، windowView، balcony، parking | الخدمات، والتدفئة، والإطلالة، والشرفة، والموقف |
safety | shelterNearby، powerBackup، autonomousHeating، waterReserve، starlink، gasAvailable، internetAvailable، elevatorWorks (نعم/لا) |
accessibility | ramp، groundLevelEntrance، wideDoors، disabledParking، wheelchairElevator (نعم/لا) |
programs | eOselya، eVidnovlennya، mortgageEligible، installment |
monthRentalRate، annualIncome، annualYield، paybackPeriod، propertyTax، insuranceCost، managementFee، repairsReserve | أرقام الاستثمار |
commission | عمولة الوكلاء: payer، type، value |
tour | الجولة ثلاثية الأبعاد: kind، url |
complexId | المجمع الذي تنتمي إليه الوحدة |
photos، video | الوسائط |
publish، strictPhotos | انظر أعلاه |
حقول الإيجار
الإلزامية: name، type (Residential، Commercial، Industrial)، address، price. معظم الحقول كما في البيع؛ والخاصة بالإيجار:
| الحقل | الوصف |
|---|---|
rentalType | long طويل الأمد، short يومي |
price، dayPrice، deposit | الإيجار، والسعر اليومي، والتأمين |
totalArea، totalFloors، bathrooms | المساحة، والطوابق، والحمامات |
minRentTime، minTermMonths | الحد الأدنى للمدة |
availableFrom | متاح من |
checkIn، checkOut | وقت الدخول والمغادرة: from، to — ساعة اليوم (15 = 15:00) |
withChildren، withPets | الأطفال مسموح بهم؛ الحيوانات: yes، no، with someone |
furniture، furnitureList | الأثاث |
conditionType | الحالة: القيم نفسها لـ condition في البيع |
onsiteAmenities، internalFeature | المرافق |
utilitiesIncluded، utilitiesCost | الخدمات |
checkInPay، onlinePay، bankTransfer، reportingDocuments | طرق الدفع والمستندات |
حقول المجمع
الإلزامية: name، address.
| الحقل | الوصف |
|---|---|
description، descriptionPresentation، descriptionSocial | الأوصاف |
price | from، to، currency |
space | مساحات الوحدات: from، to |
apartType | أنواع الوحدات |
class | economy، comfort، comfortPlus، business، premium، elite |
stage | planning، excavation، construction، finishing، commissioned، delivered |
completionQuarter | ربع سنة الإنجاز |
queues | المراحل: name، stage، completionQuarter |
sectionsNumber، floors، apartmentsNumber، parkingSpaces | الأعداد |
installment، installmentTerms | التقسيط: downPaymentPct، termMonths، interestRate |
infrastructure | البنية التحتية: مصفوفة رموز |
territoryDescription، parkingDescription، infrastructureDescription | الأوصاف |
apartmentPlans | المخططات: apartType، area، price، description، photos |
progress | تقدم البناء: title، date، description، photos |
المخطط الكامل لكل نوع بكل قيمه: المكونات ObjectWriteProperty وObjectWriteRental وObjectWriteComplex في /openapi.json. تُولَّد من عمليات التحقق نفسها التي يجريها الخادم.
مفتاح الوكالة
| الطلب | ماذا يفعل |
|---|---|
PATCH /objects/{kind}/{id}/agency | نقل عقار إلى الوكالة أو إعادته إلى الشخصي: الجسم {"targetAgencyId": "<id>"} أو {"targetAgencyId": null}؛ ودون الحقل إلى وكالة المفتاح |
PATCH /objects/{kind}/{id}/assignee | تعيين وكيل: {"assignTo": "<user id>"} |
بمفتاح شخصي يعيد كلاهما 403. لا يمكن نقل عقار مباشرة من وكالة إلى أخرى (409 conflict): انقله إلى الشخصي أولا. وتعيين وكيل لعقار شخصي، أو لشخص ليس عضوا نشطا في الوكالة، يعيد أيضا 409 conflict. الصلاحيات: إلى الوكالة، كاتب العقار؛ والعودة إلى الشخصي، المدير أو مالك الوكالة أو الكاتب؛ وتعيين أي شخص، من المدير فما فوق؛ والوكيل يعيّن نفسه فقط.
الأحداث
object.created، object.updated، object.published، object.deleted: انظر Webhooks.
مقالات ذات صلة
- القواميس: رموز الفئات والسمات.
- الملفات: رفع الصور.
- مواد الإعلان: صفحة الهبوط وPDF للعقار.