Listings APIListings API
تسجيل الدخول

أجرِ أول استدعاء لواجهة API

أجرِ المصادقة، واعرض قائمة مواقعك، واقرأ بنية الاستجابة، وتصفّح صفحات النتائج، وتعرّف على كيفية عمل المعرّفات.

يفترض هذا الدليل أن لديك حسابًا ومفتاح API من البدء. يُنفَّذ كل طلب على واجهة API الفعلية على https://listingsapi.com، لذا فإن استدعاء كتابة باستخدام مفتاح API عادي يغيّر بيانات حقيقية. لتجربة واجهة API دون التأثير في منصات النشر الحقيقية، استخدم تصريح ليوم واحد مجاني للبيئة التجريبية.

1. اضبط مفتاح API

انسخ المفتاح من مفاتيح API في لوحة التحكم وصدّره مرة واحدة في الصدفة:

bash
export LISTINGSAPI_KEY="your-api-key"

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

2. اسرد مواقعك

تشير نقاط النهاية الأخرى إلى الموقع باستخدام معرّفه، لذا ابدأ بسرد المواقع التي لديك. تستخدم ترويسة Authorization في REST المخطط API، متبوعًا بمسافة ثم مفتاح API الخاص بك: Authorization: API <YOUR_API_KEY>.

List locations
curl "https://listingsapi.com/api/v4/locations?first=5" \-H "Authorization: API $LISTINGSAPI_KEY"

3. اقرأ الاستجابة

تُرجع واجهة REST API استجابة ذات بنية متداخلة بدلًا من مصفوفة مجردة. يرد اسم العملية تحت data، وتُرجع نتائج القائمة في بنية اتصال تضم edges، وتحتوي كل حافة على node:

JSON
{  "data": {    "allLocations": {      "edges": [        {          "cursor": "TG9jYXRpb246MTgwMDI4OQ==",          "node": {            "id": "TG9jYXRpb246MTgwMDI4OQ==",            "databaseId": 1800289,            "name": "Jenny Home",            "city": "Austin",            "stateIso": "TX",            "approved": "APPROVED",            "subCategoryName": "Restaurants"          }        }      ],      "pageInfo": {        "hasNextPage": false,        "endCursor": "TG9jYXRpb246MTgwMDI4OQ=="      }    }  }}

تُرجع Python SDK صفحة من الكائنات يمكن التكرار عليها. تُرجع Node SDK ‏locations وpageInfo. عند استدعاء واجهة REST API مباشرةً، اقرأ data.allLocations.edges[].node.

4. تنقّل بين صفحات النتائج

تستخدم نقاط النهاية الخاصة بسرد المواقع والتقييمات تقسيم النتائج إلى صفحات باستخدام المؤشرات. اطلب صفحة باستخدام first، ثم مرّر pageInfo.endCursor بوصفه قيمة after لجلب الصفحة التالية. يمكن لحزمتي SDK قراءة جميع الصفحات نيابةً عنك.

Next page
curl "https://listingsapi.com/api/v4/locations?first=50&after=TG9jYXRpb246MTgwMDI4OQ==" \-H "Authorization: API $LISTINGSAPI_KEY"

لا تقسّم جميع نقاط النهاية النتائج إلى صفحات بهذه الطريقة. تستخدم الحسابات المتصلة وملخصات التكرارات والمنشورات page وperPage مع مصفوفة records. يوضح كل دليل صيغة تقسيم النتائج إلى صفحات التي تستخدمها نقاط النهاية الواردة فيه.

5. نوعان من المعرّفات

لكل سجل معرّفان. id سلسلة نصية بترميز base64 مثل TG9jYXRpb246MTgwMDI4OQ==، تصبح Location:1800289 عند فك ترميزها. أما databaseId فهو الرقم غير المرمّز، 1800289.

خزّن id بترميز base64. تتطلب كل نقطة نهاية للكتابة معرّفات بترميز base64، وهي القيم التي تُرجعها حمولات webhook. تقبل أيضًا نقاط نهاية كثيرة للقراءة، والتي تأخذ موقعًا في المسار، الرقم غير المرمّز، وتقبل كلتا حزمتي SDK أيًا من الصيغتين وتتوليان الترميز نيابةً عنك.

6. الأخطاء وحدود معدل الطلبات

تُرجع استجابات الفشل حالة HTTP المقابلة مع مصفوفة errors. تبدأ الرسالة برمز خطأ SY مدرج في رموز الأخطاء:

JSON
{  "data": { "allLocations": null },  "errors": [{ "message": "SY90005: Invalid Token" }]}

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

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