اختر طريقة التكامل

قارن بين REST API وحزمتي SDK للغتي Python وNode وخادم MCP وwebhooks بناءً على بنية تطبيقك ومتطلبات التكامل.

تستخدم جميع طرق التكامل مفتاح API وعنوان URL الأساسي نفسيهما: https://listingsapi.com/api/v4. يمكنك استخدام REST API أو إحدى حزم SDK لإرسال طلبات API، وwebhooks لتلقي التحديثات المستندة إلى الأحداث، وخادم MCP لإجراء التكامل بمساعدة وكيل ذكاء اصطناعي.

1. اختر كيفية استدعاء API

REST API. استخدم REST API للوصول إلى جميع نقاط النهاية مباشرةً عبر HTTP. يجب أن يحلّل تطبيقك الاستجابة، ويتعامل مع كلتا طريقتي تقسيم النتائج إلى صفحات، ويفحص المصفوفة errors[] بحثًا عن أخطاء API.

حزمة Python SDK. ثبّت حزمة Python SDK باستخدام pip install listingsapi. توفر الحزمة فئات للموارد عبر واجهات مثل client.locations وclient.reviews. وتتعامل مع تقسيم النتائج إلى صفحات باستخدام المؤشر عبر auto_paging_iter()، وتعيد محاولة الطلبات التي تُرجع استجابات 429 أو 5xx، وتتحقق من صحة حمولات بيانات المواقع في locations.add() قبل إرسال طلب API. اقرأ حزمة Python SDK.

حزمة Node SDK. ثبّت حزمة Node SDK باستخدام npm install listingsapi-js. تتطلب الحزمة Node.js بالإصدار 18 أو أحدث، وتتضمن تعريفات أنواع TypeScript، وليس لها أي تبعيات وقت التشغيل. تتوفر دوال SDK مباشرةً على مثيل العميل، مثل client.fetchAllLocations(). اضبط fetchAll: true لاسترجاع جميع النتائج المقسّمة إلى صفحات في استجابة واحدة. تُرمَّز المعرّفات الرقمية تلقائيًا باستخدام Base64 قبل إرسال طلبات API. اقرأ حزمة Node SDK.

خادم MCP. وصّل عملاء الذكاء الاصطناعي مثل Claude وChatGPT وCursor وGemini بخادم ListingsAPI MCP على https://listingsapi.com/mcp باستخدام Streamable HTTP. لا يلزم تثبيت خادم MCP محلي. يتيح الخادم أدوات للبحث في وثائق ListingsAPI، واكتشاف نقاط نهاية REST، وتنفيذ عمليات API المدعومة. تستخدم المصادقة مفتاح API أو OAuth. افتح /dashboard/mcp للاطلاع على إعدادات العميل وأدوات MCP المتاحة ومستوى صلاحيات مفتاح API المطلوب لكل أداة. ربط وكيل ذكاء اصطناعي باستخدام MCP.

Webhooks. استخدم webhooks مع REST API أو حزم SDK أو خادم MCP لتلقي التحديثات المستندة إلى الأحداث. عندما يتغير موقع أو إدراج نشاط تجاري أو تقييم أو منشور، ترسل ListingsAPI طلب HTTP بطريقة POST إلى عنوان URL الخاص بـwebhook والمُعدّ لحسابك. يتيح ذلك لتطبيقك معالجة التغييرات دون الاستعلام الدوري من API عن التحديثات. اقرأ نظرة عامة على webhooks.

2. تعرّف على نموذج المصادقة

تُجري REST API وحزم SDK مصادقة الطلبات باستخدام مفتاح API. مرّر المفتاح في ترويسة طلب HTTP المسماة Authorization باستخدام مخطط المصادقة API:

Authorization: API <YOUR_API_KEY>

تمنح مفاتيح API صلاحية Read (قراءة) أو Write (كتابة). يتيح مفتاح Read الوصول إلى عمليات القراءة، بما فيها عمليات البحث والتقارير. يلزم مفتاح Write للعمليات التي تنشئ الموارد أو تحدّثها. عند إرسال مفتاح Read إلى نقطة نهاية للكتابة، تُرجع نقطة النهاية حالة HTTP 400 مع رمز الخطأ SY90016.

يقتصر نطاق مفاتيح API على حساب واحد. تستهلك الطلبات التي تستخدم مفاتيح من الحساب نفسه الحصة نفسها لحد معدل الطلبات على مستوى الحساب.

يدعم خادم MCP أيضًا المصادقة باستخدام OAuth. يمكن لعملاء MCP إجراء المصادقة عبر المتصفح باستخدام OAuth بدلًا من تقديم مفتاح API. تُجرى مصادقة طلبات REST API وحزم SDK باستخدام الترويسة Authorization. راجع وثائق المصادقة للاطلاع على تفاصيل الإعداد.

3. فهم نماذج تقسيم النتائج إلى صفحات

تستخدم نقاط نهاية REST لسرد العناصر تقسيم النتائج إلى صفحات إما بالمؤشر أو بالإزاحة. تتولى حزم SDK التعامل مع تفاصيل هذه النماذج.

تقبل نقاط النهاية المستندة إلى المؤشر first وafter. تُعاد النتائج عبر edges[].node، ويوفر pageInfo.endCursor المؤشر للطلب التالي.

تقبل نقاط النهاية المستندة إلى الإزاحة page وperPage. تُعاد النتائج في records[]، ويبيّن pageInfo.totalRecords العدد الإجمالي للسجلات المتاحة.

تنفّذ الأمثلة التالية عملية سرد المواقع نفسها باستخدام 3 طرق للتكامل. يتطلب التنفيذ باستخدام cURL أن يحلّل التطبيق بنية استجابة API مباشرةً.

curl "https://listingsapi.com/api/v4/locations?first=5" \-H "Authorization: API $LISTINGSAPI_KEY" # Read data.allLocations.edges[].node, then pass# data.allLocations.pageInfo.endCursor back as ?after= for the next page.

في جميع طرق التكامل، تُعاد أخطاء API في المصفوفة errors[]، وتبدأ كل رسالة خطأ برمز خطأ SY. قد تُعيد طلبات الكتابة حالة HTTP 200 مع success: false، لذا يجب التحقق من جسم الاستجابة قبل اعتبار العملية ناجحة.

عندما يتجاوز الحساب حد معدل الطلبات المسموح به، تُعيد API حالة HTTP 429 مع ترويسة Retry-After. تدعم خطة Launch ما يصل إلى 10 طلبات في الدقيقة. راجع وثائق رموز الأخطاء وحدود معدل الطلبات للاطلاع على التفاصيل.

4. الاختيار بين webhooks والاستقصاء الدوري

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

اضبط عنوان URL واحدًا لـ webhook لكل حساب في /dashboard/webhooks. يتضمن كل طلب webhook ترويسة X-ListingsAPI-Signature بالتنسيق التالي:

X-ListingsAPI-Signature: sha256=<base64 HMAC>

يجب أن تُعيد نقطة نهاية webhook استجابة 2xx خلال 5 ثوانٍ. لا تُعاد محاولة عمليات التسليم الفاشلة.

استخدم حدث webhook لبدء استرجاع الحالة الحالية للمورد من API. بما أن عمليات تسليم webhooks لا تُعاد محاولتها، شغّل عملية مطابقة مجدولة لاكتشاف التحديثات التي ربما فاتت. راجع الاستجابة للأحداث باستخدام webhooks للاطلاع على مثال للتنفيذ.

5. مقارنة سريعة

الخطوات التالية

• إضافة موقع: أول استدعاء كتابة لك، باستخدام أي خيار اخترته.
• الاستجابة للأحداث باستخدام webhooks: إعداد مُستقبِل يتحقق من التوقيع.
• Python SDK وNode SDK: التثبيت والتهيئة وقراءة جداول الدوال.
• المصادقة، وحدود معدل الطلبات، ورموز الأخطاء: المراجع الثلاثة المشتركة بين جميع الخيارات.