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

Node SDK

عميل TypeScript الرسمي لـ Listings API، دون أي تبعيات، مع جلب صفحات النتائج تلقائيًا وتعريفات أنواع مضمّنة لـ Node 18 والإصدارات الأحدث.

listingsapi-js هو عميل Node.js/TypeScript الرسمي لـ Listings API v4. يدير المواقع وإدراجات الأنشطة التجارية في الأدلة والتقييمات والمنشورات والصور وتحليلات الملفات من خلال عميل واحد ذي بنية مسطحة، مع دعم مدمج لتقسيم النتائج إلى صفحات باستخدام المؤشرات، وترميز المعرّفات تلقائيًا، وإعادة المحاولة، والأخطاء ذات الأنواع المحددة.

التثبيت

bash
npm install listingsapi-js

المصادقة

احصل على مفتاح API من مفاتيح API → مفتاح جديد في لوحة التحكم للمطورين في Listings API.

TypeScript
import { ListingsAPI } from 'listingsapi-js'; const client = new ListingsAPI();                              // reads LISTINGSAPI_KEY from envconst explicit = new ListingsAPI({ apiKey: 'your-api-key' });  // or pass it directly

تقبل الدالة البانية أيضًا baseUrl (القيمة الافتراضية https://listingsapi.com)، وtimeout (القيمة الافتراضية 240000 مللي ثانية)، وmaxRetries (القيمة الافتراضية 2). راجع الإعدادات.

مثال سريع

list_locations.ts
import { ListingsAPI } from 'listingsapi-js'; const client = new ListingsAPI(); const result = await client.fetchAllLocations({ first: 5 });if (!Array.isArray(result)) {for (const location of result.locations) {  console.log(location.name, '--', location.city);}}

الموارد

تتوفر جميع الدوال على مثيل العميل:

الدوالما تديره
fetchAllLocations, searchLocations, fetchLocationsByIds, fetchLocationsByStoreCodes, createLocation, updateLocation, archiveLocations, cancelArchiveLocationsمواقع الأنشطة التجارية: عرض القوائم والبحث والإنشاء والتحديث والأرشفة
fetchInteractions, fetchReviewDetails, respondToReview, editReviewResponse, archiveReviewResponse, fetchReviewSettings, editReviewSettings, fetchReviewSiteConfig, fetchReviewPhrases, fetchReviewAnalyticsOverview, fetchReviewAnalyticsTimeline, fetchReviewAnalyticsSitesStatsالتقييمات: عرض القوائم والرد وتعديل الردود وأرشفتها والإعدادات وبيانات العبارات والتحليلات
bulkPublish, createAnnouncement, createEvent, createOffer, createPost, fetchPost, deletePost, fetchLocationPosts, fetchBulkPost, fetchLocationBulkPostsالمنشورات: الإعلانات والأحداث والعروض على Google وFacebook
fetchPremiumListings, fetchVoiceListings, fetchDuplicateListings, fetchAllDuplicateListings, markListingsAsDuplicate, markListingsAsNotDuplicateإدراجات الأنشطة التجارية في الأدلة: المميزة والصوتية والمكررة
fetchGoogleAnalytics, fetchBingAnalytics, fetchFacebookAnalyticsتحليلات الملفات على Google وBing وFacebook
fetchLocationPhotos, addLocationPhotos, removeLocationPhotos, starLocationPhotos, fetchPhotoUploadStatusصور المواقع
fetchConnectedAccounts, fetchConnectedAccountDetails, fetchConnectedAccountFolders, fetchConnectedAccountListings, fetchConnectionSuggestions, connectGoogleAccount, connectFacebookAccount, disconnectGoogleAccount, disconnectFacebookAccount, triggerConnectedAccountMatches, confirmConnectedAccountMatches, getOauthConnectUrl, oauthDisconnect, connectListing, disconnectListing, createGmbListingاتصالات OAuth بـ Google وFacebook وروابط إدراجات الأنشطة التجارية
fetchPlanSites, fetchCountries, fetchSubscriptions, fetchSubcategoriesأدلة الخطة والبلدان المدعومة والاشتراكات وفئات الأنشطة التجارية

لا توفر حزمة SDK هذه بعد واجهة لـ Social API، التي تشمل العلامات التجارية والحسابات الاجتماعية المتصلة والمنشورات على Facebook وInstagram وX وLinkedIn وPinterest؛ استدعها مباشرةً بالرجوع إلى مرجع Social REST.

تقسيم النتائج إلى صفحات

تدعم الدوال التي تُرجع قوائم تقسيم النتائج إلى صفحات باستخدام المؤشرات.

TypeScript
// Single pageconst page = await client.fetchAllLocations({ first: 25 });if (!Array.isArray(page)) {console.log(page.locations);   // Location[]console.log(page.pageInfo);    // { hasNextPage, hasPreviousPage, startCursor, endCursor } // Next pageif (page.pageInfo.hasNextPage) {  const next = await client.fetchAllLocations({    first: 25,    after: page.pageInfo.endCursor!,  });}} // Auto-paginate: returns a flat Location[]const all = await client.fetchAllLocations({ fetchAll: true, pageSize: 100 });

يتبع searchLocations وfetchInteractions النمط نفسه: كائن صفحة افتراضيًا، ومصفوفة مسطحة عند استخدام fetchAll: true.

ترميز المعرّفات

مرّر معرّفات المواقع الرقمية في أي موضع: ترمّزها حزمة SDK تلقائيًا باستخدام base64. تُقبل المعرّفات المرمّزة مسبقًا كما هي، وتُصدَّر دالة الترميز إذا احتجت إلى استخدامها بنفسك.

TypeScript
import { encodeLocationId } from 'listingsapi-js'; // These are equivalentawait client.fetchPremiumListings(16808);await client.fetchPremiumListings('TG9jYXRpb246MTY4MDg='); encodeLocationId(16808); // 'TG9jYXRpb246MTY4MDg='

معالجة الأخطاء

يشتق كل خطأ في حزمة SDK من ListingsAPIError. تؤدي حالات فشل API إلى طرح APIError أو إحدى فئاته الفرعية، سواء أبلغت عنها المنصة برمز حالة HTTP أو ضمن متن استجابة HTTP 200 (تَرِد أخطاء الرموز المميزة غير الصالحة والتحقق من صحة عمليات الكتابة في حمولات errors[]، وقد تُبلغ عمليات الكتابة عن success: false). تطرح حزمة SDK استثناءات لجميع هذه الحالات، لذا لا تحتاج أبدًا إلى فحص علامات success بنفسك. تؤدي حالات فشل الشبكة إلى طرح APIConnectionError.

الفئةتُطرح عند
AuthenticationError401، أو حمولات أخطاء الرموز المميزة غير الصالحة
PermissionDeniedError403، أو حمولات أخطاء الصلاحيات
NotFoundError404
ValidationError400/422، أو عمليات الكتابة التي تُرجع success: false / errors[]
RateLimitError429، وتتضمن retryAfter بالثواني
InternalServerError5xx
APIConnectionErrorفشل الشبكة، ولم يصل شيء إلى API

يتضمن كل APIError القيم statusCode وresponseBody وcode (أول رمز خطأ من المنصة، e.g. "SY10005")، وerrors (يُوحَّد تنسيق كل عنصر إلى { code, message, context }).

TypeScript
import { ListingsAPI, APIError, RateLimitError } from 'listingsapi-js'; const client = new ListingsAPI(); try {await client.fetchAllLocations();} catch (error) {if (error instanceof RateLimitError) {  console.log(error.retryAfter);       // seconds to wait} else if (error instanceof APIError) {  console.log(error.statusCode);       // 401, 404, 500, or 200 for payload-level errors  console.log(error.code);             // first platform code, e.g. 'SY10005'  console.log(error.errors);           // [{ code, message, context }, ...]}}

يعيد العميل المحاولة تلقائيًا عند تلقي استجابات 429 و5xx (2 من المحاولات افتراضيًا، مع الالتزام بـ Retry-After). راجع معالجة الأخطاء للاطلاع على أنماط إعادة المحاولة وإرشادات رموز الحالة.

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