/api/v4/connected-accounts/connect-listingربط إدراج نشاط تجاري بموقع
يربط إدراج نشاط تجاري محددًا على Google Business Profile أو Facebook بموقع في Listings API.
المعلمات
النص الأساسي
| الاسم | النوع | مطلوب | الوصف |
|---|---|---|---|
| input | object | مطلوب | Wrapper object. The entire request body must be nested under `input`. |
| input.locationId | string | مطلوب | Base64-encoded location Relay ID (e.g. `TG9jYXRpb246MTgwMDI4OQ==`) of the Listings API location to link the listing to. |
| 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 within that connected account to link. Taken from the `id` of a record returned by `POST /connected-accounts/connected-account-listings`. |
مثال على الطلب
نص جاهز للصق. استبدل المعرّفات والقيم النموذجية بقيمك.
{ "input": { "locationId": "TG9jYXRpb246MTgwMDI4OQ==", "connectedAccountId": "4f712c17-4f95-42dd-90f4-97171a2e67b5", "connectedAccountListingId": "R29vZ2xlTG9jYXRpb246ODc3NTkzNGItNTA5OC00ZDBhLThiNDQ=" }}الاستجابات
200Request accepted. `success` is `true` when the listing was linked; when it cannot be linked `success` is `false` and `message` explains why (for example, `Listing record not found`).
{ "data": { "connectListing": { "message": null, "success": true } }}400Bad request, the body was not wrapped in `input`, or a required field was omitted. Note the field is `connectedAccountListingId`, not `listingId` (the API rejects `listingId` with `did you mean locationId?`).
401Unauthenticated, missing or invalid API key.
يربط إدراج نشاط تجاري على منصة نشر (Google Business Profile أو صفحة Facebook) بموقع في Listings API للحفاظ على مزامنة بيانات إدراج النشاط التجاري. بخلاف مسار العمل القائم على الاقتراحات، تربط نقطة النهاية هذه إدراج نشاط تجاري واحدًا سبق أن اخترته، دون الحاجة إلى خطوة تأكيد المطابقة.
بنية الطلب. يجب تضمين جسم الطلب داخل كائن input يحتوي على ثلاثة حقول مطلوبة: locationId (معرّف Relay ID للموقع بترميز base64)، وconnectedAccountId (الحساب الذي يملك إدراج النشاط التجاري)، وconnectedAccountListingId (إدراج النشاط التجاري المحدد المراد ربطه). لا يوجد حقل listingId، إذ يرفضه المخطط. استرجع connectedAccountId من GET /connected-accounts، وconnectedAccountListingId من id في سجل يُرجعه POST /connected-accounts/connected-account-listings.
حالة استخدام: الربط اليدوي عندما تكون المطابقة التلقائية ملتبسة. يحمل متجران متقاربان اسمين متشابهين، ولا يستطيع trigger-matches تحديد إدراج النشاط التجاري على Google الذي يخص كل موقع في Listings API. استرجع إدراجات الأنشطة التجارية للحساب المتصل، ودع أحد المشغّلين يختار الإدراج الصحيح، ثم اربطه مباشرة باستخدام نقطة النهاية هذه، متجاوزًا مسار الاقتراحات والتأكيد بالكامل.
إذا فشل الربط، تُرجع الاستجابة success: false مع قيمة غير null للحقل message توضّح السبب، مثل Listing record not found عندما يتعذّر العثور على ما يشير إليه connectedAccountListingId، أو رسالة تشير إلى أن إدراج النشاط التجاري مرتبط بالفعل بموقع آخر. لقبول المطابقات التي يقترحها النظام دفعة واحدة بدلًا من ذلك، استخدم نقطة النهاية confirm-matches.
curl -X POST 'https://listingsapi.com/api/v4/connected-accounts/connect-listing' \ -H "Authorization: API $LISTINGSAPI_KEY" \ -H 'Content-Type: application/json' \ -d '{ "input": { "locationId": "TG9jYXRpb246MTgwMDI4OQ==", "connectedAccountId": "4f712c17-4f95-42dd-90f4-97171a2e67b5", "connectedAccountListingId": "R29vZ2xlTG9jYXRpb246ODc3NTkzNGItNTA5OC00ZDBhLThiNDQ=" } }'