/api/v4/locations/create/gmb-listingإنشاء إدراج نشاط تجاري على GMB لموقع
ينشئ إدراج نشاط تجاري جديدًا على Google Business Profile لموقع موجود في Listings API ويربطه بحساب Google متصل.
المعلمات
النص الأساسي
| الاسم | النوع | مطلوب | الوصف |
|---|---|---|---|
| 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 location to create the Google listing for. |
| input.connectedAccountId | string | مطلوب | UUID of the connected Google account the new listing should be created under. Taken from `GET /connected-accounts`. |
| input.folderId | string | اختياري | Google account group to create the listing inside, as the `accounts/{id}` string from the folders endpoint. Omit to create it at the account root. |
مثال على الطلب
نص جاهز للصق. استبدل المعرّفات والقيم النموذجية بقيمك.
{ "input": { "locationId": "TG9jYXRpb246MTgwMDI4OQ==", "connectedAccountId": "4f712c17-4f95-42dd-90f4-97171a2e67b5" }}الاستجابات
200Request accepted. `success: true` means GMB listing creation was initiated.
{ "data": { "createGmbListingForLocation": { "clientMutationId": null, "success": true, "errors": null } }}400Bad request, the body was not wrapped in `input` (error message: `Variable "$input" of required type "CreateGmbListingForLocationInput!" was not provided`).
401Unauthenticated, missing or invalid API key.
ينشئ إدراج نشاط تجاري جديدًا تمامًا على Google Business Profile لموقع في Listings API ويربطه بحساب Google متصل. استخدم نقطة النهاية هذه عندما لا يكون للموقع أي إدراج نشاط تجاري على Google بعد، بخلاف connect-listing الذي يربط موقعًا في Listings API بإدراج نشاط تجاري موجود بالفعل في حساب Google.
بنية الطلب. يجب تضمين جسم الطلب داخل كائن input يحتوي على حقلين مطلوبين: locationId (معرّف Relay للموقع بترميز base64) وconnectedAccountId (حساب Google الذي سيُنشأ إدراج النشاط التجاري ضمنه). الحقل folderId اختياري؛ مرّره لوضع إدراج النشاط التجاري الجديد في مجموعة محددة ضمن حساب Google، مع أخذ قيمته دون تغيير من عرض المجلدات. يُرفض إرسال جسم طلب مسطّح غير مضمّن داخل الكائن بحالة HTTP 400.
الإنشاء غير متزامن: تعني success: true أن الطلب قد قُبل، ولا تعني أن إدراج النشاط التجاري أصبح منشورًا على الفور. تراجع Google الملفات التجارية الجديدة قبل نشرها.
حالة استخدام: إنشاء ملف تجاري على Google لمتجر جديد تمامًا. يفتح عميل موقعًا جديدًا ليس لديه ملف تجاري على Google Business Profile بعد. أنشئ الموقع في Listings API، واربط حساب Google الخاص بالعميل، ثم استدعِ نقطة النهاية هذه باستخدام معرّف الموقع وconnectedAccountId لتتولى Listings API إرسال إدراج النشاط التجاري الجديد إلى Google ضمن ذلك الحساب. استعلم دوريًا عن إدراجات النشاط التجاري الخاصة بالموقع بعد ذلك لمتابعة انتقاله من حالة الانتظار إلى حالة التحقق.
يجب أن يحتوي الموقع مسبقًا على معلومات صالحة عن النشاط التجاري (الاسم والعنوان ورقم الهاتف) قبل إنشاء إدراج نشاط تجاري، ولا يمكن أن يوجد سوى إدراج نشاط تجاري واحد على Google لكل موقع. عند الفشل، يوضح errors السبب، ويكون عادةً أن الموقع يفتقر إلى حقول مطلوبة، أو أن لديه بالفعل إدراج نشاط تجاري على Google، أو أنه مؤرشف، أو أن الحساب المتصل غير نشط. أعِد ربط حساب لم يعد اتصاله صالحًا باستخدام نقطة النهاية connect-google. لاحظ أن نقطة النهاية تُرجع حاليًا success: true حتى عندما لا يكون connectedAccountId حساب Google حقيقيًا ومتصلًا، لذا تأكد من ظهور إدراج النشاط التجاري فعليًا (عبر إدراجات النشاط التجاري الخاصة بالموقع) بدلًا من الاعتماد على success وحده.
curl -X POST 'https://listingsapi.com/api/v4/locations/create/gmb-listing' \ -H "Authorization: API $LISTINGSAPI_KEY" \ -H 'Content-Type: application/json' \ -d '{ "input": { "locationId": "TG9jYXRpb246MTgwMDI4OQ==", "connectedAccountId": "4f712c17-4f95-42dd-90f4-97171a2e67b5" } }'