المواقع

اعرض مواقع الأنشطة التجارية وابحث عنها وأنشئها وحدّثها وأرشفها باستخدام حزمة SDK المسماة listingsapi-js.

المواقع هي الكيان الأساسي في Listings API: يرتبط كل إدراج نشاط تجاري وتقييم وسجل تحليلات ومنشور بموقع واحد. تتوفر جميع دوال المواقع في نسخة العميل ListingsAPI.

fetchAllLocations

اعرض مواقع الحساب مع تقسيم النتائج إلى صفحات باستخدام المؤشرات. تُرجع الدالة كائنًا يحتوي على locations وpageInfo وsuccess وحمولة API ‏raw. عند استخدام fetchAll: true، تجلب الدالة الصفحات تلقائيًا وتُرجع Location[] أحادي المستوى بدلًا من ذلك.

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, total? } // Next pageconst next = await client.fetchAllLocations({  first: 25,  after: page.pageInfo.endCursor!,});} // All pages at once, returns Location[]const all = await client.fetchAllLocations({ fetchAll: true, pageSize: 100 });

الخيارات

المعاملالنوعالوصف
firstnumberحجم الصفحة عند التصفح للأمام.
afterstringمؤشر من pageInfo.endCursor سابق.
beforestringمؤشر لتصفح الصفحات للخلف.
lastnumberحجم الصفحة عند التصفح للخلف.
fetchAllbooleanجلب الصفحات تلقائيًا وإرجاع Location[] أحادي المستوى.
pageSizenumberحجم الصفحة المستخدم داخليًا عندما تكون قيمة fetchAll هي true (القيمة الافتراضية 100).

fetchLocationsByIds

اجلب مواقع محددة باستخدام معرّفاتها. تقبل الدالة معرّفات رقمية أو معرّفات مرمّزة بصيغة base64 وتُرجع Location[] أحادي المستوى. إذا كانت مصفوفة الإدخال فارغة، تُرجع الدالة [] دون إرسال طلب.

TypeScript
const locations = await client.fetchLocationsByIds([16808, 16809, 'TG9jYXRpb246MTY4MTA=']);console.log(locations); // Location[]

fetchLocationsByStoreCodes

اجلب المواقع التي تطابق رموز المتاجر المحددة. تُرجع الدالة Location[] أحادي المستوى؛ وإذا كانت مصفوفة الإدخال فارغة، تُرجع [] دون إرسال طلب.

TypeScript
const locations = await client.fetchLocationsByStoreCodes(['AD-SF-001', 'AD-NY-001']);

searchLocations

ابحث عن المواقع باستخدام كلمة مفتاحية في الاسم والعنوان ومعرّف المتجر. تُرجع الدالة النتائج المقسمة إلى صفحات بالبنية نفسها التي تُرجعها fetchAllLocations، وتدعم fetchAll بالطريقة نفسها.

TypeScript
// Single pageconst result = await client.searchLocations('Brooklyn', { first: 20 });if (!Array.isArray(result)) {console.log(result.locations, result.pageInfo);} // All matching results, returns Location[]const all = await client.searchLocations('Brooklyn', { fetchAll: true }); // Restrict which fields are searchedconst byName = await client.searchLocations('Acme Dental', { fields: ['name'] });

الخيارات

جميع خيارات تقسيم النتائج إلى صفحات في fetchAllLocations، بالإضافة إلى:

المعاملالنوعالوصف
fieldsstring[]حصر البحث في حقول محددة.

createLocation

أنشئ موقعًا جديدًا. تتطلب API الحقل name والحقل description بطول لا يقل عن 200 حرف، والحقول subCategoryId وcountryIso وcity. تُرجع الدالة حمولة الاستجابة التي تتضمن الموقع الذي أُنشئ؛ وإذا رفضت API المدخلات، يطرح العميل استثناءً من النوع ValidationError بدلًا من ذلك، لذا لا توجد علامة نجاح للتحقق منها.

TypeScript
const result = await client.createLocation({name: 'Acme Dental',description:  'Acme Dental is a family-owned dental practice offering cleanings, ' +  'checkups, fillings, crowns, and cosmetic dentistry for patients of all ' +  'ages. Our gentle, experienced team uses modern digital imaging and ' +  'same-day scheduling to make every visit fast and comfortable.',subCategoryId: 1432,countryIso: 'US',city: 'San Francisco',street: '2100 Mission St',stateIso: 'CA',postalCode: '94110',phone: '4155550100',storeId: 'AD-SF-003',});console.log(result.location.id);

updateLocation

حدّث حقلًا واحدًا أو أكثر في موقع موجود. مرّر id الخاص بالموقع مع أي حقول تريد تغييرها. تُرمَّز المعرّفات الرقمية تلقائيًا.

TypeScript
await client.updateLocation({id: 16808,phone: '4155550199',name: 'Acme Dental Mission District',});

archiveLocations

أرشف موقعًا واحدًا أو أكثر. تتوقف مزامنة المواقع المؤرشفة مع الأدلة.

TypeScript
await client.archiveLocations([16808, 16809]);

cancelArchiveLocations

ألغِ الأرشفة المجدولة للمواقع المحددة. تقبل الدالة معرّفات المواقع وselectionType ومعرّف changedBy كوسائط موضعية.

TypeScript
await client.cancelArchiveLocations([16808],'manual',           // selectionType'ops@example.com',  // changedBy);

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

تقبل كل دالة من دوال المواقع معرّفًا رقميًا أو معرّفًا مرمّزًا بصيغة base64. تُرمِّز SDK المعرّفات الرقمية (والسلاسل النصية الرقمية) تلقائيًا باستخدام التنسيق Location:<id>؛ أما القيم المرمّزة مسبقًا فتُمرَّر كما هي.

TypeScript
// These are equivalentawait client.fetchLocationsByIds([16808]);await client.fetchLocationsByIds(['TG9jYXRpb246MTY4MDg=']);

تُصدَّر دالة الترميز أيضًا إذا كنت بحاجة إلى الصيغة المرمّزة مباشرةً:

TypeScript
import { encodeLocationId } from 'listingsapi-js'; encodeLocationId(16808);                  // 'TG9jYXRpb246MTY4MDg='encodeLocationId('16808');                // 'TG9jYXRpb246MTY4MDg='encodeLocationId('TG9jYXRpb246MTY4MDg='); // unchanged