واجهات API المساعدة

كل نقاط نهاية API المساندة بأمثلة cURL وPython وNode: البلدان والولايات المدعومة، ودليل الفئات الفرعية، ومواقع منصات النشر المشمولة بخطتك.

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

نظرة سريعة على نقاط النهاية

عرض قائمة البلدان والولايات المدعومة

GET /countries

تُرجع نقطة النهاية الدليل الكامل ضمن data.supportedCountries. يتضمن كل بلد رمز ISO، وقيمة id بترميز base64، وقيمة رقمية للحقل databaseId، ومصفوفة states لكل عنصر فيها رمز ISO خاص به، وثلاث علامات للعنوان: hasCity (المدينة مطلوبة)، وstateRequired (الولاية مطلوبة ويُتحقق من صحتها بالرجوع إلى states)، وhasPostalCode (البلد يستخدم الرموز البريدية). بالنسبة إلى البلد غير المقسّم إلى ولايات، تُرجع نقطة النهاية مصفوفة states فارغة.

المعاملات

لا تقبل نقطة النهاية هذه أي معاملات. وهي تُرجع المجموعة الكاملة دائمًا.

curl https://listingsapi.com/api/v4/countries \-H "Authorization: API $LISTINGSAPI_KEY"

{  "data": {    "supportedCountries": [      {        "databaseId": 13,        "hasCity": true,        "id": "Q291bnRyeToxMw==",        "iso": "AU",        "name": "Australia",        "states": [          { "countryId": 13, "id": "139", "iso": "VIC", "name": "Victoria" },          { "countryId": 13, "id": "142", "iso": "NSW", "name": "New South Wales" }        ]      },      {        "databaseId": 17,        "hasCity": true,        "id": "Q291bnRyeToxNw==",        "iso": "BE",        "name": "Belgium",        "states": []      }    ]  }}

قيمتا حقلي iso هما القيمتان اللتان تحتاج إليهما. تصبح قيمة iso الخاصة بالبلد قيمة countryIso عند الإنشاء والتحديث، وتصبح قيمة iso الخاصة بالولاية قيمة stateIso. يتيح لك التحقق من صحة القيمتين بالرجوع إلى هذه القائمة قبل عملية الكتابة تحويل 400 من جهة الخادم إلى رسالة واضحة في النموذج الخاص بك.

عرض قائمة الفئات الفرعية

GET /sub-categories

تُرجع نقطة النهاية نحو 6,000 سجل فئة ضمن data.subcategories في مصفوفة واحدة غير مقسّمة إلى صفحات. وهي المرجع الذي يحوّل نوع النشاط التجاري الذي تعرفه كنص حر إلى المعرّف الرقمي الذي تتطلبه عملية كتابة بيانات موقع.

المعاملات

لا توجد. يُرجع الدليل كاملًا في كل استدعاء.

curl https://listingsapi.com/api/v4/sub-categories \-H "Authorization: API $LISTINGSAPI_KEY"

{  "data": {    "subcategories": [      {        "databaseId": 4589,        "id": "U3ViQ2F0ZWdvcnk6NDU4OQ==",        "key": "3d-printing-service",        "name": "3D printing service",        "primary": true      }    ]  }}

يتضمن كل سجل خمسة حقول، ويعتمد الحقل الذي تستخدمه على موضع استخدامه.

يقبل الموقع فئة أساسية واحدة في subCategoryId وما يصل إلى 9 فئات إضافية في additionalCategoryIds.

عرض قائمة المواقع المشمولة في الخطة

GET /plan-sites

تُرجع نقطة النهاية كل دليل تابع لمنصة نشر مشمول في خطة حسابك، ضمن data.planSites. هذه هي القائمة المرجعية المعتمدة لمعرّفات المواقع الرقمية، ولا تكون المعرّفات صالحة في مواضع أخرى من واجهة API إلا إذا وردت هنا.

المعاملات

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

curl https://listingsapi.com/api/v4/plan-sites \-H "Authorization: API $LISTINGSAPI_KEY"

{  "data": {    "planSites": [      {        "id": 1,        "name": "Google Maps",        "url": "maps.google.com",        "supportedCountries": ["US", "CA", "IN", "GB", "DE"],        "hideAddressSupportedCountries": ["US", "CA", "AU", "IN", "GB"]      },      {        "id": 184,        "name": "Facebook",        "url": "facebook.com",        "supportedCountries": ["US", "CA", "IN", "GB", "DE"],        "hideAddressSupportedCountries": ["US", "CA", "AU", "IN", "GB"]      }    ]  }}

تجيب مصفوفتا البلدان عن سؤالين مختلفين. تحدد supportedCountries البلدان التي يقبل فيها الموقع إدراج نشاط تجاري من الأساس، لذا صفِّ النتائج بحسب قيمة countryIso الخاصة بموقعك قبل عرض منصة نشر للاختيار. تحدد hideAddressSupportedCountries البلدان التي يلتزم فيها الموقع بإخفاء العنوان، وهو ما يحتاج إليه النشاط التجاري الذي يخدم منطقة محددة. يمكن أن تتضمن كلتا المصفوفتين 50 رمزًا أو أكثر؛ وقد اختُصر المثال أعلاه.

معرّفات المواقع ثابتة ومن المفيد معرفتها: 1 هو معرّف Google Maps و184 هو معرّف Facebook، وهما منصتا النشر اللتان تستهدفهما معظم مسارات الربط.

روابط إجراءات الموقع

ليست نقطة نهاية مستقلة. روابط إجراءات الموقع هي أزرار Google مثل الطلب عبر الإنترنت وحجز طاولة وحجز موعد، وتديرها المنصة بوصفها حقلًا في الموقع بدلًا من مورد منفصل. يمكنك تعيينها عبر المصفوفة placeActionLinks عند الإنشاء والتحديث، وقراءتها من أي نقطة نهاية لقراءة بيانات الموقع.

يتطلب كل عنصر placeActionType وuri، ويدعم علامة isPreferred اختيارية مع السماح برابط مفضّل واحد على الأكثر لكل نوع، ويقبل action بالقيمة add أو delete عند التحديث. تتوفر الأنواع الصالحة وقواعد الحذف وسلوك المزامنة جميعها في روابط إجراءات الموقع.

الأخطاء التي ستواجهها

لا تُجري أي من نقاط النهاية هذه عمليات كتابة، لذا لا يؤدي استخدام مفتاح Read إلى إرجاع SY90016 هنا مطلقًا. تتوفر القائمة الكاملة في رموز الأخطاء.

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

• البحث عن البلدان والفئات: النسخة الموجّهة لتنفيذ المهمة، مع شرح خطوات الانتقال إلى إنشاء موقع.
• إضافة موقع: حيث يُستخدم countryIso وsubCategoryId.
• العثور على أخطاء إدراجات الأنشطة التجارية وإصلاحها: يستخدم مواقع الخطة للتمييز بين منصة نشر مفقودة وأخرى تواجه خللًا.
• مرجع واجهات API المساندة للاطلاع على القائمة الكاملة للحقول في نقاط النهاية الثلاث جميعها.