/api/v4/connected-accounts/create-location-from-listingإنشاء موقع من إدراج نشاط تجاري في حساب متصل
ينشئ موقعًا جديدًا في Listings API من إدراج نشاط تجاري موجود على Google Business Profile أو Facebook ضمن حساب متصل.
المعلمات
النص الأساسي
| الاسم | النوع | مطلوب | الوصف |
|---|---|---|---|
| input | object | مطلوب | Wrapper object. The entire request body must be nested under `input`. |
| input.connectedAccountId | string | مطلوب | ID of the connected account (Google or Facebook) that owns the listing. Taken from `GET /connected-accounts`. |
| input.connectedAccountListingId | string | مطلوب | ID of the listing to import into a new location. Taken from the `id` of a record returned by `POST /connected-accounts/connected-account-listings`. |
مثال على الطلب
نص جاهز للصق. استبدل المعرّفات والقيم النموذجية بقيمك.
{ "input": { "connectedAccountId": "4f712c17-4f95-42dd-90f4-97171a2e67b5", "connectedAccountListingId": "R21iQnVsa0RhdGFMYWtlOjU3NzU5MzRiLTUwOTgtNGQwYS04YjQ0LTNjY2ZlZmZkZmUzNw==" }}الاستجابات
200Request accepted. `success` is `true` and `locationId` holds the new location's database ID; on failure `success` is `false`, `locationId` is `null`, and `errors` carries a structured, coded reason.
{ "data": { "createLocationFromConnectedAccountListing": { "success": true, "locationId": 88277, "errors": null } }}400Bad request, the body was not wrapped in `input`, or a required field was omitted. The field is `connectedAccountListingId`, not `listingId` (the latter is rejected by the schema).
401Unauthenticated, missing or invalid API key.
ينشئ موقعًا جديدًا في Listings API عن طريق جلب بيانات النشاط التجاري من إدراج نشاط تجاري موجود في حساب Google Business Profile أو Facebook متصل. يجب أن يكون إدراج النشاط التجاري موجودًا بالفعل في الحساب (وقد جُلب عبر POST /connected-accounts/connected-account-listings)، ويجب ألا يكون مرتبطًا بالفعل بموقع آخر في Listings API.
بنية الطلب. يجب تغليف محتوى الطلب في كائن input يحتوي على حقلين مطلوبين: connectedAccountId (الحساب الذي يملك إدراج النشاط التجاري) وconnectedAccountListingId (إدراج النشاط التجاري المحدد المراد استيراده). لا يوجد حقل listingId، إذ يرفضه المخطط.
بالنسبة إلى إدراجات الأنشطة التجارية على Google، تستورد واجهة API الاسم والعنوان والإحداثيات ورقم الهاتف والموقع الإلكتروني والوصف وساعات العمل العادية والخاصة والفئة الأساسية والفئات الإضافية وتاريخ الافتتاح ورمز المتجر والمنطقة الزمنية. تُستخلص طرق الدفع وروابط الملفات الشخصية على شبكات التواصل الاجتماعي من سمات Google الخاصة بإدراج النشاط التجاري. تُقرأ سمات Google الأخرى غير طرق الدفع وروابط شبكات التواصل الاجتماعي، لكن لا يُحتفظ بها. أما بالنسبة إلى Facebook، فتستورد الاسم والموقع وساعات العمل والفئات والوصف ومعلومات الاتصال.
يُربط الموقع الجديد تلقائيًا بالحساب المتصل الذي استُورد منه. عند الاستيراد من Google، لا تُعاد إرسال البيانات إلى Google. يبقى الملف التجاري الذي استوردت منه كما هو، ويُظهر إدراج النشاط التجاري الخاص به الحالة syncStatus: IN_PROGRESS إلى أن تنشر فيه لأول مرة باستخدام POST /api/v4/locations/update. تُعامل كل منصة نشر أخرى بالطريقة المعتادة: تُنشأ بنود الطلب ويُرسل الموقع إلى كل موقع إلكتروني آخر مفعّل في الحساب.
لا تقبل نقطة النهاية هذه أي نطاق للمواقع الإلكترونية ولا أي خيار لتعطيل الإرسال، لذا يُنشأ الموقع دائمًا لجميع منصات النشر في حسابك. لقصره على منصة نشر واحدة، اضبط enabledSiteIds للموقع الجديد عبر POST /api/v4/locations/update فور إنشائه. أرسل هذا التحديث بمجرد إنشاء الموقع: تُنشأ بنود الطلب لمنصات النشر الأخرى بعد وقت قصير من الإنشاء، ولا يسحب التحديث أي بنود أُنشئت بالفعل.
حالة استخدام: إنشاء المواقع دفعة واحدة أثناء الإعداد الأولي. تربط وكالة حساب Google لأحد عملائها، وهو حساب يدير 40 متجرًا لم تُدخلها الوكالة من قبل في Listings API. بدلًا من إنشاء كل موقع يدويًا، اسرد إدراجات الأنشطة التجارية في الحساب واستدعِ نقطة النهاية هذه مرة واحدة لكل connectedAccountListingId لإنشاء جميع المواقع الـ40 في Listings API ببيانات معبأة مسبقًا من Google، ثم أصدر فواتيرها وأدرها بالطريقة المعتادة.
تعني success: true أن الموقع قد أُنشئ، وlocationId هو معرّفه في قاعدة البيانات. عند الفشل، تكون قيمة success هي false، وقيمة locationId هي null، ويحتوي errors على سبب منظّم مصحوب برمز، مثل { "code": "SY81067", "message": "Invalid connected account listing ID" } عندما لا يشير connectedAccountListingId إلى سجل موجود. تشمل الحالات الشائعة الأخرى إدراج نشاط تجاري مرتبطًا بالفعل بموقع آخر، أو حسابًا انتهت صلاحية بيانات اعتماده ويجب إعادة ربطه عبر نقطة النهاية connect-google أو connect-facebook. لربط إدراج نشاط تجاري بموقع موجود بدلًا من إنشاء موقع جديد، استخدم نقطة النهاية connect-listing.
curl -X POST 'https://listingsapi.com/api/v4/connected-accounts/create-location-from-listing' \ -H "Authorization: API $LISTINGSAPI_KEY" \ -H 'Content-Type: application/json' \ -d '{ "input": { "connectedAccountId": "4f712c17-4f95-42dd-90f4-97171a2e67b5", "connectedAccountListingId": "R21iQnVsa0RhdGFMYWtlOjU3NzU5MzRiLTUwOTgtNGQwYS04YjQ0LTNjY2ZlZmZkZmUzNw==" } }'