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

إضافة موقع

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

ترتبط إدراجات الأنشطة التجارية والتقييمات والمنشورات والتحليلات جميعها بمعرّف موقع. ينشئ POST /api/v4/locations الموقع ويضع إدراج نشاط تجاري واحدًا لكل منصة نشر ضمن خطتك في قائمة الانتظار.

1. جمع الحقول المطلوبة

هناك 10 حقول مطلوبة. يرسل النشاط التجاري الذي يخدم منطقة محددة العنوان الكامل أيضًا: عند استخدام hideAddress: true، تخزّن ListingsAPI العنوان ولكنها لا ترسله إلى منصات النشر. تعرض منصات النشر الحقول الاختيارية التي لم تُرسل على أنها فارغة، لذا أرسل كل المعلومات المتاحة لديك.

الحقلمطلوبملاحظات
nameنعممن 2 إلى 150 حرفًا.
descriptionنعم200 حرف على الأقل (SY10005).
countryIsoنعمرمز من حرفين لبلد مدعوم (SY10036).
cityنعممطلوب عندما تكون قيمة hasCity للبلد هي true (SY10126). عندما تكون القيمة false، تُحذف المدينة التي ترسلها.
subCategoryIdنعمقيمة رقمية لـ databaseId من قائمة الفئات الفرعية.
streetنعممن 5 إلى 100 حرف (SY10011).
stateIsoنعممطلوب عندما تكون قيمة stateRequired للبلد هي true، ويجب أن يكون إحدى قيم states لذلك البلد (SY10010). لا ترسله عندما تكون قيمة stateRequired هي false.
postalCodeلااختياري، ولكن أرسله كلما كانت قيمة hasPostalCode للبلد هي true. يجب أن تتطابق أي قيمة ترسلها مع التنسيق الخاص بالبلد (SY10014).
phoneنعميُتحقق من صحته وفقًا للبلد (SY10015).
bizUrlنعميُنشر بوصفه الموقع الإلكتروني. ترفض بعض منصات النشر إدراج نشاط تجاري من دون موقع إلكتروني.
storeIdلارمز المتجر الخاص بك، ويكون فريدًا على مستوى الحساب. استخدمه للعثور على الموقع مجددًا دون تخزين معرّفاتنا.
businessHoursلاعنصر واحد لكل يوم من أيام الأسبوع. راجع تحديث موقع لمعرفة التنسيق.

2. إنشاء الموقع

يأخذ POST /api/v4/locations الحقول ضمن كائن input في جسم طلب JSON. تأخذ الدالة locations.add() في Python SDK الحقول نفسها كوسيطات مسماة وتتحقق من صحة الحقول المطلوبة قبل إرسال الطلب. تأخذ الدالة createLocation() في Node SDK كائنًا بأسماء حقول camelCase مباشرةً.

Create
curl -X POST https://listingsapi.com/api/v4/locations \-H "Authorization: API $LISTINGSAPI_KEY" \-H "Content-Type: application/json" \-d '{  "input": {    "name": "Acme Kitchen",    "storeId": "ACME-NYC-001",    "description": "Acme Kitchen is a family-owned neighborhood restaurant in downtown New York serving wood-fired pizza, hand-rolled pasta, and a short seasonal menu built around produce from nearby farms. Open for lunch and dinner seven days a week, with takeout and delivery available.",    "street": "123 Jump Street",    "city": "New York",    "stateIso": "NY",    "postalCode": "10013",    "countryIso": "US",    "phone": "6443859313",    "bizUrl": "https://acmekitchen.example.com",    "subCategoryId": 1432,    "businessHours": [      { "day": "MONDAY",    "type": "OPEN",   "slots": [{ "start": "11:00am", "end": "10:00pm" }] },      { "day": "TUESDAY",   "type": "OPEN",   "slots": [{ "start": "11:00am", "end": "10:00pm" }] },      { "day": "WEDNESDAY", "type": "OPEN",   "slots": [{ "start": "11:00am", "end": "10:00pm" }] },      { "day": "THURSDAY",  "type": "OPEN",   "slots": [{ "start": "11:00am", "end": "10:00pm" }] },      { "day": "FRIDAY",    "type": "OPEN",   "slots": [{ "start": "11:00am", "end": "11:00pm" }] },      { "day": "SATURDAY",  "type": "OPEN",   "slots": [{ "start": "12:00pm", "end": "11:00pm" }] },      { "day": "SUNDAY",    "type": "CLOSED", "slots": [] }    ]  }}'

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

تُرجع عملية الإنشاء الناجحة success: true والموقع الجديد ضمن data.createLocation.location. احتفظ بكلا المعرّفين: id هو قيمة base64 التي تأخذها كل عملية كتابة لاحقة، وdatabaseId هو القيمة الرقمية التي تظهر في لوحات التحكم وحمولات webhook.

JSON
{  "data": {    "createLocation": {      "success": true,      "errors": null,      "location": {        "id": "TG9jYXRpb246MTgwMDI5MA==",        "databaseId": 1800290,        "storeId": "ACME-NYC-001",        "name": "Acme Kitchen",        "city": "New York",        "stateIso": "NY",        "countryIso": "US",        "status": "PENDING"      }    }  }}

تكون قيمة status هي PENDING أثناء التحقق من صحة الموقع وإدراجه في قائمة الانتظار. وتتغير هذه القيمة مع تقدّم المعالجة دون استدعاء إضافي لواجهة API.

4. التعامل مع أخطاء التحقق

قد تفشل عملية الإنشاء في موضعين. يؤدي الطلب ذو البنية غير الصحيحة أو المفتاح غير الصالح إلى إرجاع 4xx مع مصفوفة errors في المستوى الأعلى. أما الطلب ذو البنية الصحيحة الذي يحتوي على حقل ترفضه واجهة API فيؤدي إلى إرجاع 200 مع success: false وتفاصيل المشكلة داخل data.createLocation.errors، لذا افحص جسم الاستجابة لكل عملية كتابة، ولا تكتفِ برمز الحالة.

JSON
{  "data": {    "createLocation": {      "success": false,      "errors": [        {          "code": "SY10005",          "message": "SY10005: description must be at least 200 characters",          "path": ["input", "description"]        }      ],      "location": null    }  }}

تُطلق كلتا حزمتي SDK استثناءً عند الفشل. تتحقق locations.add() في Python من الحقول المطلوبة محليًا وتُطلق ValidationError قبل إرسال الطلب. تُطلق createLocation() في Node الاستثناء ValidationError عندما ترفض واجهة API المدخلات، ولهذا لا يفحص المثال أعلاه أي علامة نجاح.

الرموز التي ستصادفها غالبًا:

الرمزالسببالحل
SY10005الوصف مفقود أو يقل عن 200 حرف.اكتب وصفًا أكثر تفصيلًا.
SY10011street مفقود أو يقل عن 5 أحرف.أرسل street.
SY10010stateIso مفقود أو غير صالح للبلد.أرسل رمز ولاية من نقطة نهاية البلدان.
SY10036countryIso ليس بلدًا مدعومًا.استخدم رمزًا من نقطة نهاية البلدان.
SY10126city مفقود لبلد يتطلبه.أرسل city.
SY90016المفتاح بصلاحية Read فقط.استخدم مفتاحًا بصلاحية Write.

5. التأكد من بدء الإرسال

يؤدي إنشاء الموقع إلى إضافة إدراج نشاط تجاري واحد لكل منصة نشر ضمن خطتك إلى قائمة انتظار الإرسال. يبدأ كل إدراج نشاط تجاري بالحالة AVAILABLE أو IN_PROGRESS، ثم ينتقل إلى الحالة SYNCED مع listingUrl بمجرد أن تقبله منصة النشر.

Listing status
curl https://listingsapi.com/api/v4/locations/TG9jYXRpb246MTgwMDI5MA==/listings/premium \-H "Authorization: API $LISTINGSAPI_KEY"

عند إعداد webhooks، لا حاجة إلى الاستقصاء الدوري. يُطلَق حدث profile.created عندما يصبح السجل موجودًا، ويُطلَق حدث listing.submission لكل منصة نشر عند تغيّر حالتها.

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