أربع أدوات للتقييم. الشقق والمنازل والأراضي مدعومة؛ التقييم السريع والتقرير يرفضان العقارات التجارية والمجمعات السكنية بـ 422 business_rule؛ أما تقدير الإيجار فيعمل للعقارات التجارية أيضا.
التقييم السريع
POST /valuation/express: النطاق tools:valuation، فوري. استدعاء API واحد مع سعر التقييم السريع.
| الحقل | النوع | إلزامي | الوصف |
|---|---|---|---|
propertyCategory | نص | لا | apartment (افتراضي)، house، land؛ القيمة commercial تُرفض بـ 422، وأي قيمة أخرى (لا توجد complex) بـ 400 |
totalArea | رقم | واحد من ثلاثة | المساحة، م² |
areaM2 | رقم | واحد من ثلاثة | مثل totalArea |
landPlotArea | رقم | واحد من ثلاثة | مساحة الأرض، م²؛ تُحتسب مساحةً فقط مع land |
addressText | نص | موصى به | العنوان في سطر واحد |
country، city، postalCode | نص | لا | العنوان على أجزاء |
lat، lon | رقم | لا | الإحداثيات |
rooms | رقم | لا | الغرف |
yearBuilt | رقم | لا | سنة البناء |
floor، floorsTotal | رقم | لا | الطابق وعدد الطوابق |
houseLevels | رقم | لا | مستويات المنزل |
heatingType | نص | لا | التدفئة |
price | رقم | لا | سعرك: يُقارن بالتقدير |
currency | نص | لا | عملة النتيجة |
language | نص | لا | غير مستخدم: الرد السريع لا يتضمن نص شرح |
targetId | نص | لا | معرّف عقارك: التقديرات المتكررة للعقار نفسه تأتي من الذاكرة المؤقتة لمدة 7 أيام |
curl -X POST https://developers.grem.capital/api/v1/valuation/express \
-H "Authorization: Bearer gsk_live_xxx" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: 5b8c3f7e-2a71-4c55-8d0e-9f1a6b2c4d10" \
-d '{"propertyCategory":"apartment","addressText":"Torstraße 12, Berlin","totalArea":64,"rooms":2,"currency":"EUR"}'
الرد:
| الحقل | الوصف |
|---|---|
estimate.pricePoint | القيمة المقدرة |
estimate.rangeLow، estimate.rangeHigh | النطاق |
estimate.confidence | مستوى الموثوقية: low أو medium أو high |
estimate.confidenceScore | الموثوقية رقما من 0 إلى 1 |
estimate.currency | العملة |
estimate.analogs | العقارات المماثلة التي وُجدت: title, address, area, rooms, pricePerM2, originalPrice, adjustedPrice, adjustments, weight, provenance, source, sourceUrl |
degraded | true في تقدير تقريبي دون بيانات سوق؛ ومثله لا يُخصم |
دون مساحة أو مع propertyCategory غير معروفة: 400 validation؛ العقار التجاري: 422 business_rule مع code: commercial_unsupported.
تقرير التقييم الكامل
POST /valuation/report: النطاق tools:valuation، مهمة. تقرير مع تحليل السوق وملف PDF. الحقول الإلزامية تعتمد على propertyCategory. أرسل حقول فئتك فقط: حقل فئة أخرى (مثلا houseLevels لشقة، أو parking لمنزل) يُرفض بـ 400. للشقة فقط: livingArea، kitchenArea، bathrooms، ceilingHeight، floor، storeys، balcony، elevator، parking، houseType، apartmentType. للمنزل فقط: houseLevels. للأرض فقط: zoning. للمنزل والأرض: utilities.
| الحقل | النوع | الوصف |
|---|---|---|
propertyCategory | نص | apartment أو house أو land: إلزامي |
address | كائن | إلزامي: country، city، street (يمكن أن يكون فارغا)، streetNumber، location (lat، lng) |
totalArea | رقم | م²؛ إلزامي للشقة والمنزل |
landPlotArea | رقم | م²؛ إلزامي للمنزل؛ للأرض هذا الحقل أو totalArea |
condition | نص | الحالة؛ إلزامي للشقة والمنزل |
apartmentType | نص | الشقة: Residential أو Commercial أو Industrial أو Land plot أو Complex، إلزامي |
houseType | نص | الشقة: نوع المبنى، إلزامي |
floor، storeys | رقم | الشقة: الطابق وطوابق المبنى، إلزاميان |
balcony، elevator | نعم/لا | الشقة: إلزاميان |
houseLevels | رقم | المنزل: المستويات من 1 إلى 10، إلزامي |
rooms | رقم | الشقة والمنزل: الغرف |
livingArea، kitchenArea، bathrooms، ceilingHeight | رقم | للشقة فقط: تفاصيل اختيارية |
yearConstruction | رقم | الشقة والمنزل: سنة البناء |
wallMaterial، heatingType | نص | الشقة والمنزل: مادة الجدران، التدفئة؛ للمنزل تكون heatingType إحدى القيم central، autonomous، boiler، fireplace، mixed، gas، electric، heat_pump، solid_fuel، underfloor، none |
furnished | نعم/لا | الشقة والمنزل: مفروش |
parking | نعم/لا | للشقة فقط: موقف سيارات |
zoning | نص | للأرض فقط: الاستخدام |
utilities | كائن | المنزل والأرض: gas، water، sewage، electricity (نعم/لا) |
price | رقم | سعرك: يُقارن بالتقدير |
currency | نص | UAH، USD، EUR، AZN، GBP، AED، CNY، TRY، GEL |
language | نص | لغة التقرير: eng، rus، ukr، deu، spa، aze، arb، fra، zho، tur |
objectId | نص | معرّف عقارك إذا كنت تقيّمه |
comments | نص | تعليق على التقييم |
curl -X POST https://developers.grem.capital/api/v1/valuation/report \
-H "Authorization: Bearer gsk_live_xxx" \
-H "Content-Type: application/json" \
-d '{
"propertyCategory": "apartment",
"address": { "country": "Germany", "city": "Berlin", "street": "Torstraße", "streetNumber": "12" },
"currency": "EUR", "language": "arb",
"apartmentType": "Residential", "houseType": "panel",
"totalArea": 64, "rooms": 2, "floor": 3, "storeys": 5,
"balcony": true, "elevator": false, "condition": "good"
}'
الرد 202: { "jobId": "...", "status": "processing", "state": "running" }. المهمة المنتهية (GET /valuation/report/jobs/{id}) تحتوي على:
| الحقل | الوصف |
|---|---|
metrics | الأرقام: potPrice, priceRangeLow, priceRangeHigh, avgPrice, analogCount, growth - القيمة السوقية ونطاقها وسعر المتر المربع وعدد العقارات المماثلة ونسبة النمو |
confidence، priceMethod، estimateType | مدى موثوقية القيمة (high…very_low) وطريقة الحساب ونقطة أم نطاق |
currency | عملة جميع الأرقام |
justification | لماذا القيمة هكذا |
recommendations | توصيات بشأن السعر والبيع |
pdfMeta | بيانات تقرير PDF |
analogs | العقارات المماثلة التي بُنيت عليها القيمة (الجدول نفسه في PDF): title, address, area, rooms, pricePerM2, originalPrice, adjustedPrice, adjustments, weight, provenance, source, sourceUrl. provenance: model_estimate - مرجع بلا إعلان خلفه |
العقار التجاري (ومنه apartmentType بقيمة Commercial أو Industrial) يُرفض بـ 422 business_rule وcode: commercial_unsupported؛ ويُقدَّر إيجاره عبر POST /valuation/rent. المجمع السكني (apartmentType: Complex): 422 مع code: complex_unsupported؛ قيّم شقة أو منزلا واحدا فيه.
PDF: GET /artifacts/v1/ai/appraisal/reports/{id}/pdf. الأحداث: valuation.completed / valuation.failed.
تقدير الإيجار
POST /valuation/rent: النطاق tools:rent، فوري. صف العقار بالحقول أو مرر objectId لعقار تملكه أو عقار عام.
| الحقل | النوع | الوصف |
|---|---|---|
objectId | نص | عقار بدلا من الوصف |
city | نص | إلزامي دون objectId |
totalArea | رقم | م²؛ إلزامي دون objectId |
country، district، street | نص | العنوان |
propertyCategory | نص | نوع العقار |
rooms، floor | رقم | الغرف، الطابق |
furnished | نعم/لا | مفروش |
condition | نص | الحالة |
rentTerm | نص | long: إيجار شهري (افتراضي)؛ short: يومي. سوقان مختلفان |
occupancyPct | رقم | اليومي: نسبة الإشغال المتوقعة من 10 إلى 100 % |
monthRentalRate | رقم | إيجارك الشهري: يبين الرد المقارنة بالسوق |
declaredDayRate | رقم | سعرك اليومي |
currency | نص | عملة النتيجة |
curl -X POST https://developers.grem.capital/api/v1/valuation/rent \
-H "Authorization: Bearer gsk_live_xxx" \
-H "Content-Type: application/json" \
-d '{"propertyCategory":"apartment","country":"Germany","city":"Berlin","totalArea":50,"rooms":2,"currency":"EUR"}'
الرد:
| الحقل | الوصف |
|---|---|
id | معرّف التقدير؛ PDF: GET /artifacts/v1/ai/appraisal/rent/{id}/pdf |
currency | العملة |
rent.monthlyRent | إيجار السوق شهريا |
rent.low، rent.high | النطاق |
rent.annualRent | سنويا |
rent.pricePerM2 | للمتر المربع شهريا |
rent.grossYieldPct | العائد الإجمالي من سعر العقار، %، إذا كان السعر معروفا |
rent.confidence | الموثوقية |
rent.basedOn | على كم إعلانا مماثلا يستند التقدير |
rent.termBasis | long أو short |
comps | كل الإعلانات التي دُرست ودورها في التقدير: address, area, rooms, monthlyRent/dayRent, effectiveMonthly, term, status, usedInEstimate, source, url |
دون مساحة أو مدينة: 400 مع detail مثل "Missing or invalid: totalArea".
مراجعة التقرير
POST /valuation/review: النطاق tools:review. ارفع تقرير تقييم (PDF، DOCX، DOC، RTF؛ حتى 40 ميغابايت): يقرأه GREM ويتحقق من القيمة مقابل بيانات السوق.
الجسم: multipart/form-data:
| الجزء | الوصف |
|---|---|
file | مستند التقرير (أو جزء document) |
language | لغة النتيجة، الافتراضية rus |
currency | العملة، الافتراضية USD |
curl -X POST https://developers.grem.capital/api/v1/valuation/review \
-H "Authorization: Bearer gsk_live_xxx" \
-F "[email protected]" \
-F "language=arb" -F "currency=EUR"
يُقرأ المستند فورا. رد 202 يحتوي على jobId وstatus وstate:
action_required(status: need_confirm): يحتويextractedعلى البيانات المقروءة من المستند. راجعها وأكّد:POST /valuation/review/jobs/{id}/confirm(المهام والنتائج). بعد التأكيد تنتقل المهمة إلىrunning.failed(status: rejected): المستند ليس تقرير تقييم عقاري.
النتيجة المنتهية: GET /valuation/review/jobs/{id}؛ وتقرير المراجعة: GET /artifacts/v1/ai/appraisal/reviews/{id}/report.pdf أو report.docx. الأحداث: review.completed / review.failed؛ وتبدأ متابعة webhook بعد التأكيد.