مرجع الواجهة البرمجية

Listings API

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

اطلب صلاحية الوصول البدء السريع

في هذه الصفحة

نظرة عامة
البدء السريع
المصادقة
نقاط النهاية
قائمة الإعلانات
جلب إعلان
المزامنة
كائن الإعلان
مثال إعلان
الأخطاء
ضمانات التغذية
الدعم

نظرة عامة

العنوان الأساسي: https://api.osyro.com
المصادقة: ترويسة X-API-Key
الصيغة: JSON عبر HTTPS
التوقيت: ISO 8601 بتوقيت UTC

البدء السريع

ثلاث خطوات للحصول على أول استجابة.

1
احصل على مفتاح API من فريق أوسايرو واحفظه كمتغير بيئة، مثل OSYRO_API_KEY.
2
استدعِ GET /listings مع المفتاح في الترويسة X-API-Key.
3
اقرأ total_pages من الاستجابة واطلب بقية الصفحات.

curl "https://api.osyro.com/listings?page=1&page_size=50" \
  -H "X-API-Key: $OSYRO_API_KEY"

200 · الاستجابة

{
  "page": 1,
  "page_size": 50,
  "total": 120,
  "total_pages": 3,
  "listings": [
    { "referenceNumber": "osy-demo-100231", "...": "full listing object" }
  ]
}

المصادقة

يجب أن يتضمن كل طلب مفتاح API في الترويسة X-API-Key. تُرفض الطلبات من دون مفتاح صالح.

يصدر فريق أوسايرو المفاتيح وترتبط بحساب مؤسستك.

احتفظ بالمفتاح على الخادم. لا تضعه في متصفح أو تطبيق جوال ولا في مستودع الشيفرة. إن اعتقدت أنه تسرب، تواصل مع أوسايرو لاستبداله.

HTTP

GET /listings HTTP/1.1
Host: api.osyro.com
X-API-Key: {YOUR_API_KEY}
Accept: application/json

نقاط النهاية

نقطتا نهاية للقراءة فقط، وكلتاهما تعيد كائنات إعلان بالحقول نفسها تماماً.

GET/listingsتعيد الإعلانات النشطة صفحةً صفحة ككائنات إعلان كاملة.
GET/listings/{referenceNumber}تعيد كائن إعلان واحداً برقمه المرجعي.

GET/listings

قائمة الإعلانات

تعيد الإعلانات النشطة صفحةً صفحة ككائنات إعلان كاملة. استخدمها للمزامنة الكاملة والتزايدية. تبدأ الصفحات من 1؛ تابع الطلب حتى تقرأ total_pages.

معاملات الاستعلام

المعامل	النوع	الافتراضي	الوصف
`page`	integer	`1`	رقم الصفحة بدءاً من 1.
`page_size`	integer	`50`	عدد الإعلانات في الصفحة، بحد أقصى 200. الصفحات الأكبر تعني طلبات أقل.
`updated_since`	ISO 8601	`بلا`	الإعلانات التي تغيّرت في هذا الوقت أو بعده فقط (شامل). استخدم وقت بدء آخر مزامنة ناجحة.

الاستجابة

تحيط استجابة القائمة كائنات الإعلان ببيانات الترقيم.

الحقل	النوع	الوصف
`page`	integer	الصفحة المطلوبة.
`page_size`	integer	حجم الصفحة المستخدم.
`total`	integer	عدد الإعلانات المطابقة في كل الصفحات.
`total_pages`	integer	عدد الصفحات. اطلب الصفحات من 1 حتى `total_pages`.
`listings`	object[]	مصفوفة كائنات الإعلان لهذه الصفحة.

curl "https://api.osyro.com/listings?page=2&page_size=200&updated_since=2026-10-01T00:00:00Z" \
  -H "X-API-Key: $OSYRO_API_KEY"

200 · الاستجابة

{
  "page": 1,
  "page_size": 50,
  "total": 120,
  "total_pages": 3,
  "listings": [
    { "referenceNumber": "osy-demo-100231", "...": "full listing object" }
  ]
}

GET/listings/{referenceNumber}

جلب إعلان

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

معامل المسار

المعامل	النوع	الوصف
`referenceNumber`	string	قيمة `referenceNumber` للإعلان.

كائن الإعلان →

curl "https://api.osyro.com/listings/osy-demo-100231" \
  -H "X-API-Key: $OSYRO_API_KEY"

المزامنة

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

مزامنة كاملة

تصفّح /listings من دون updated_since، فتحصل على كل الإعلانات النشطة.

مزامنة تزايدية

مرّر وقت بدء آخر مزامنة ناجحة في updated_since لجلب التغييرات فقط.

اكتشاف التغييرات

referenceNumber جديد يعني إعلاناً جديداً. وlastUpdated أحدث يعني أن الإعلان تغيّر.

تُحذف الإعلانات المباعة أو المؤجرة أو المسحوبة من التغذية بدل وسمها. أي referenceNumber يغيب عن المزامنة الكاملة يجب إلغاء نشره لديك.

وصفة: المزامنة الكاملة

نفّذ مزامنة كاملة عند الربط الأول ثم دورياً (مثلاً كل ليلة) لالتقاط الإعلانات المحذوفة.

# Full sync: fetch every page, then unpublish anything not seen.
page=1
while :; do
  body=$(curl -s "https://api.osyro.com/listings?page=$page&page_size=200" \
    -H "X-API-Key: $OSYRO_API_KEY")
  echo "$body" | jq -c '.listings[]' >> listings.ndjson
  total_pages=$(echo "$body" | jq '.total_pages')
  [ "$page" -ge "$total_pages" ] && break
  page=$((page + 1))
done

وصفة: المزامنة التزايدية

نفّذ المزامنة التزايدية بشكل متكرر (مثلاً كل 15 دقيقة) لالتقاط الجديد والمتغيّر بسرعة.

# Incremental sync: only listings changed since your last successful run.
curl "https://api.osyro.com/listings?page=1&page_size=200&updated_since=$LAST_SYNC_START" \
  -H "X-API-Key: $OSYRO_API_KEY"

احفظ وقت بدء المزامنة لا وقت انتهائها، واستخدمه كقيمة updated_since التالية. ولأن updated_since شامل، لا يضيع أي تغيير.
حدّث أو أدرج بحسب referenceNumber، فتكون إعادة المعالجة آمنة دائماً.
المزامنة التزايدية لا تخبرك بالحذف؛ ادمجها مع مزامنة كاملة منتظمة.
استخدم page_size=200 في المزامنة لتقليل عدد الطلبات.

كائن الإعلان

للإعلان الشكل نفسه في نقطتي النهاية. أسماء الحقول حساسة لحالة الأحرف، وقيم التعداد نصوص ثابتة تُطابَق دون اعتبار لحالة الأحرف.

الدائمة فقط

موجود دائماًعند الانطباقعند التوفر

الهوية

الحقل	القيم والملاحظات
`referenceNumber`string موجود دائماً	معرّف فريد وثابت لا يتغير ولا يُعاد استخدامه. استخدمه مفتاحاً أساسياً.
`lastUpdated`ISO 8601 موجود دائماً	يتغير عند تغيّر أي حقل، بما في ذلك السعر والصور.

التصنيف

الحقل	القيم والملاحظات
`category`enum موجود دائماً	فئة العقار. `Residential` `Commercial`
`purpose`enum موجود دائماً	للبيع أم للإيجار. `For Sale` `For Rent`
`frequency`enum عند الانطباق	للإيجار فقط. المدة التي يشير إليها السعر. `Monthly` `Weekly` `Daily`
`completionStatus`enum عند التوفر	حالة الإنشاء. `Completed` `Off Plan`
`unitType`string موجود دائماً	نوع الوحدة. القائمة مفتوحة؛ تعامل مع القيم غير المعروفة بمرونة. `Apartment` `Villa` `Townhouse` `Office` `Shop` `Warehouse` `Land` `…`

المحتوى

الحقل	القيم والملاحظات
`title`string موجود دائماً	عنوان الإعلان.
`description`string موجود دائماً	الوصف الكامل وقد يحتوي HTML؛ نقّه قبل العرض.
`images`string[] موجود دائماً	روابط HTTPS مرتبة؛ الأولى صورة الغلاف. 1024 بكسل على الأقل للضلع الأطول.

المساحة والتخطيط

الحقل	القيم والملاحظات
`unitBuiltupArea`number موجود دائماً	المساحة المبنية بوحدة unitMeasure.
`unitMeasure`enum عند التوفر	القيمة الافتراضية sqm عند الغياب. `sqm` `sqft`
`bedrooms`number \| string عند الانطباق	للسكني فقط. الاستوديو 0 أو "Studio".
`bathrooms`number عند التوفر	عدد الحمامات.
`furnishing`enum عند التوفر	مستوى التأثيث. `Fully furnished` `Semi-furnished` `Unfurnished`
`facilities`string[] عند التوفر	أسماء المرافق، مثل Balcony وShared Pool وSecurity.

السعر

الحقل	القيم والملاحظات
`price`number موجود دائماً	بالريال القطري. سعر البيع أو الإيجار لكل frequency.

الموقع

الحقل	القيم والملاحظات
`city`string موجود دائماً	مثل Doha وLusail وAl Wakrah، بالأسماء المعتمدة لدى البوابات القطرية.
`area`string موجود دائماً	أدق مجتمع أو برج، مثل Porto Arabia وWest Bay.
`latitude`number موجود دائماً	درجات عشرية WGS84.
`longitude`number موجود دائماً	درجات عشرية WGS84.

شروط الإيجار

الحقل	القيم والملاحظات
`rentalPeriod`enum عند التوفر	مدة العقد. `Less than 1 year` `Annual contract` `More than 1 year`
`deposit`enum عند التوفر	مبلغ التأمين. `1 Month` `2 Months` `Negotiable` `None`
`commission`enum عند التوفر	عمولة الوكالة. `1 Month` `1/2 Month` `Negotiable` `None` `Percentage` `Cash` `Other` `Not applicable`
`freeMonths`enum عند التوفر	الأشهر المجانية المعروضة. `0` `1` `2` `3` `4`

مزايا الوحدة

الحقل	القيم والملاحظات
`kitchen`enum عند التوفر	نوع المطبخ. `Closed` `Open` `Fitted` `Unfitted` `Kitchenette` `None`
`parking`enum عند التوفر	نوع المواقف. `Covered` `Uncovered` `Underground` `Dedicated - Covered` `Dedicated - Uncovered` `Dedicated - Underground` `On street parking`
`acType`enum عند التوفر	نوع التكييف. `Central` `Split` `Windows` `None`
`kahramaa`boolean عند التوفر	الكهرباء والماء (كهرماء) مشمولة في الإيجار.
`internet`boolean عند التوفر	الإنترنت مشمول في الإيجار.

الوسيط

الحقل	القيم والملاحظات
`agent.name`string موجود دائماً	الاسم الكامل.
`agent.phone`string موجود دائماً	بالصيغة الدولية ‎+974XXXXXXXX.
`agent.email`string موجود دائماً	البريد الإلكتروني.
`agent.photo`string عند التوفر	رابط صورة الملف الشخصي.

مثال إعلان

إعلان إيجار سكني كامل ببيانات توضيحية.

listing.json

{
  "referenceNumber": "osy-demo-100231",
  "lastUpdated": "2026-09-22T07:47:10Z",
  "category": "Residential",
  "purpose": "For Rent",
  "frequency": "Monthly",
  "rentalPeriod": "Annual contract",
  "deposit": "1 Month",
  "commission": "1 Month",
  "freeMonths": 1,
  "completionStatus": "Completed",
  "unitType": "Apartment",
  "title": "Elegant 1BR Apartment, Porto Arabia",
  "description": "<p>Spacious 1BHK with sea view</p>",
  "unitBuiltupArea": 95,
  "unitMeasure": "sqm",
  "bedrooms": 1,
  "bathrooms": 2,
  "furnishing": "Fully furnished",
  "facilities": ["Balcony", "Shared Pool", "Security"],
  "kitchen": "Fitted",
  "parking": "Covered",
  "acType": "Central",
  "kahramaa": true,
  "internet": true,
  "price": 7500,
  "city": "Doha",
  "area": "Porto Arabia",
  "latitude": 25.3725,
  "longitude": 51.541,
  "images": [
    "https://cdn.example.com/100231/1.jpg",
    "https://cdn.example.com/100231/2.jpg"
  ],
  "agent": {
    "name": "Jane Doe",
    "phone": "+97455500000",
    "email": "jane.doe@example.com",
    "photo": "https://cdn.example.com/agents/1.jpg"
  }
}

الأخطاء

تعيد الطلبات الفاشلة حالة HTTP خاطئة وجسم JSON يحتوي رمزاً ورسالة. اعتمد على Code؛ الرسالة للقراءة البشرية وقد تتغير.

الرمز	الوصف	ما يجب فعله
`201`	مفتاح API مفقود أو غير صالح.	تحقق من الترويسة `X-API-Key` ولا تعِد المحاولة قبل الإصلاح.
`202`	المفتاح صالح لكنه لا يملك صلاحية التغذية.	تواصل مع أوسايرو للتحقق من حسابك. لا تعِد المحاولة.
`203`	خطأ مؤقت في الخادم.	أعد المحاولة مع تأخير متزايد. تواصل مع أوسايرو إن استمر.

4xx / 5xx · الاستجابة

{
  "Code": 201,
  "Message": "Invalid access token"
}

إعادة المحاولة بأمان

كل نقاط النهاية للقراءة، فإعادة المحاولة آمنة دائماً. أعد المحاولة لأخطاء الخادم فقط مع تأخير متزايد.

سجّل قيمة Code ووقت الطلب عند التواصل مع الدعم، ولا ترسل مفتاحك أبداً.

# Retry server errors (code 203) with backoff: 1s, 2s, 4s, 8s, 16s
for delay in 1 2 4 8 16; do
  status=$(curl -s -o page.json -w "%{http_code}" \
    "https://api.osyro.com/listings?page=1" -H "X-API-Key: $OSYRO_API_KEY")
  [ "$status" -lt 500 ] && break
  sleep "$delay"
done

ضمانات التغذية

تعيد المزامنة الكاملة كل الإعلانات النشطة دون حذف أي منها لأسباب الأداء.
referenceNumber ثابت ولا يُعاد استخدامه.
يتغير lastUpdated مع أي تعديل، بما في ذلك السعر والصور.
updated_since شامل: في الوقت المحدد أو بعده.
روابط الصور عامة وثابتة عبر HTTPS، والصورة الأولى هي الغلاف.
الأسعار بالريال القطري، والإيجارات بحسب frequency.
أرقام هواتف الوسطاء بالصيغة ‎+974XXXXXXXX.
كل الأوقات بتوقيت UTC.

تحتاج مفتاحاً أو مساعدة؟

مفاتيح الواجهة والأسئلة التقنية ودعم التكامل تأتي مباشرة من فريق أوسايرو.

تواصل مع فريق أوسايرو

Listings APIListings API