مزامنة نسخة محلية

تحتفظ معظم التكاملات بنسخة محلية من الإعلانات المهمة لها. صُمم API لذلك، ويمكن اتباع نمط واحد:

1. استعلم باستخدام sort=updated_asc ووقت تختاره في updated_since.
2. تصفح بالمؤشر واحفظ كل إعلان في مخزنك.
3. عند نهاية النتائج، أو عند إشارة result_window_reached إلى بلوغ عمق خطتك، ابدأ استعلامًا جديدًا واضبط updated_since على آخر updated_at استلمته.
4. كرر وفق جدول يناسبك. يقرأ دارك مصادره مرتين يوميًا، فلا يضيف التكرار أكثر من مرة في الساعة فائدة كبيرة.

curl "https://api.darak.app/v1/listings?city=riyadh&listing_type=rent\
&sort=updated_asc&updated_since=2026-09-01T00:00:00Z&limit=100" \
  -H "Authorization: Bearer $DARAK_API_KEY"

لماذا updated_asc لا newest؟ تحمل المؤشرات إزاحة داخل مجموعة النتائج. مع ترتيب آخر، تحرّك الإعلانات المضافة أو المحذوفة أثناء التصفح الصفوف بين الصفحات، فتفقد بعضها وترى بعضها مرتين دون تنبيه. الترتيب التصاعدي بـupdated_at وتحريك مؤشر الوقت يجعل ما فات في جولة يصل في التالية.

توقع إعلانات رأيتها من قبل. updated_at وقت تحديث المصدر إن نشره، وإلا فهو آخر وقت رأى دارك الإعلان. يتحرك في كل جمع لتلك المصادر، فتعود إعلاناتها إلى المزامنة مرتين يوميًا حتى دون تغيير. قارن قبل الكتابة أو تقبّل التكرار.

اكتشاف الإزالة. لا تدفع هذه المزامنة إشعار اختفاء إليك. يتوقف ظهور الإعلان المباع أو المؤجر أو المسحوب أو المدمج كنسخة مكررة؛ يعيد GET /listings/{id} الحالة 404 ويضع GET /listings/batch المعرّف في missing_ids. أعد فحص المعرّفات دوريًا؛ تُحسب وحدة لكل عشرة في الجلب الدفعي. اعتبر المفقود محذوفًا؛ لديك 7 أيام لإيقاف عرضه وفق الشروط.

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

تقدير الحجم. يحد عمق التصفح نتائج الاستعلام الواحد: 500 في Free، 5,000 في Starter، 5,000 في Growth، 20,000 في Pro. تتجاوزه مزامنة مدينة كاملة، وهذا سبب تحريك مؤشر الوقت. تكلف صفحة 100 نتيجة 10 وحدات، فتكلّف جولة من 20,000 إعلان 2,000 وحدة.