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

إنشاء Google Business Profile لموقع ليس لديه ملف

أرسل طلب إنشاء Google Business Profile جديد لموقع بحساب Google متصل، وتابع التحقق عبر الموقع وإدراجاته وأحداث webhooks.

لا تعمل المطابقة والربط إلا إذا كان هناك إدراج نشاط تجاري على Google بالفعل. المتجر الجديد ليس لديه إدراج نشاط تجاري، لذا تطلب من واجهة API إنشاء إدراج له ضمن حساب Google متصل. الإنشاء غير متزامن، وتتحقق Google من الملف وفق جدولها الزمني الخاص، لذا يركز معظم هذا الدليل على متابعة النتيجة.

1. تأكد من أن الموقع ليس لديه إدراج نشاط تجاري على Google

اقرأ إدراجات الأنشطة التجارية المميزة الخاصة بالموقع وابحث عن الصف الذي تكون قيمة site.name فيه هي Google Maps. يُظهر الموقع الذي ليس له وجود على Google القيمة REQUIRING_ACTION مع connectedAccountId بقيمة null.

Google row
curl https://listingsapi.com/api/v4/locations/TG9jYXRpb246MTgwMDI4OQ==/listings/premium \-H "Authorization: API $LISTINGSAPI_KEY"
JSON
{  "site": { "name": "Google Maps", "url": "maps.google.com" },  "syncStatus": "REQUIRING_ACTION",  "displayStatus": "Connect your account to sync the listing",  "listingUrl": null,  "connectedAccountId": null,  "verified": false}

إذا كان الصف بالفعل في حالة SYNCED، أو كانت قيمة connectedAccountId معيّنة، فإن الموقع لديه إدراج نشاط تجاري على Google ولا ينطبق عليه هذا الدليل. اربط إدراج النشاط التجاري أو حدّثه بدلًا من ذلك.

2. اختر مجلدًا (اختياري)

تنظم Google إدراجات الأنشطة التجارية ضمن الحساب في مجلدات، تُسمى أيضًا مجموعات الحساب. اعرض مجلدات الحساب المتصل ومرّر أحدها في folderId إذا أراد المالك وضع الملف الجديد داخل مجموعة محددة. تجاوز هذه الخطوة لإنشائه في جذر الحساب.

Folders
curl https://listingsapi.com/api/v4/connected-accounts/4f712c17-4f95-42dd-90f4-97171a2e67b5/folders \-H "Authorization: API $LISTINGSAPI_KEY"
JSON
{  "data": {    "getFoldersUnderGoogleAccount": [      { "folderId": "accounts/104890024806530350198", "folderName": "Bright Smile Dental", "locationCount": null }    ]  }}

استخدم folderId دون تغيير؛ فهو السلسلة النصية accounts/{id} وليس رقمًا. قد تكون قيمة locationCount هي null عندما لا توفرها Google. نقطة النهاية صالحة فقط لاتصالات GoogleAccount.

3. أنشئ إدراج النشاط التجاري

أرسل id الخاص بالموقع بترميز base64 والحساب، بالإضافة إلى المجلد إذا اخترت واحدًا. تفيد الاستجابة بأن الطلب قد قُبل، ولا تفيد بأكثر من ذلك.

Create listing
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",    "folderId": "accounts/104890024806530350198"  }}'
JSON
{  "data": {    "createGmbListingForLocation": { "clientMutationId": null, "success": true, "errors": null }  }}

تعني success: true أن عملية الإنشاء قد بدأت، ولا تعني أن الملف أصبح منشورًا. تراجع Google كل ملف جديد قبل نشره، وقد يستغرق ذلك أيامًا. عندما تكون قيمة success هي false، يوضح errors السبب: يفتقر الموقع إلى حقول مطلوبة، أو لديه بالفعل إدراج نشاط تجاري على Google، أو أنه مؤرشف، أو أن الحساب المتصل لم يعد نشطًا.

4. تابع حالة التحقق من الموقع

تُرجع كل عملية قراءة للموقع googleVerificationStatus متضمنًا status وmessage. اقرأ الموقع مجددًا لمعرفة المرحلة التي وصلت إليها Google في العملية.

Verification status
curl -G https://listingsapi.com/api/v4/locations-by-ids \--data-urlencode 'ids=["TG9jYXRpb246MTgwMDI4OQ=="]' \-H "Authorization: API $LISTINGSAPI_KEY"
JSON
{  "id": "TG9jYXRpb246MTgwMDI4OQ==",  "databaseId": 1800289,  "googleVerificationStatus": { "status": "PENDING_VERIFICATION", "message": null }}
statusالمعنىنهائية
NOT_CONNECTEDلم يُربط أي إدراج نشاط تجاري على Google بعد. توقّع هذه الحالة قبل أن تؤتي الخطوة 3 نتيجتها.لا
NOT_VERIFIEDإدراج النشاط التجاري موجود، ولم يبدأ التحقق بعد.لا
PENDING_VERIFICATIONتتحقق Google من الملف.لا
UNDER_REVIEWتراجع Google الملف.لا
VERIFIEDالملف منشور.نعم
SUSPENDEDعلّقت Google الملف.نعم
DUPLICATEاعتبرت Google الملف نسخة مكررة من ملف موجود.نعم
ERROR_WHILE_FETCHINGتعذرت قراءة الحالة من Google. أعد المحاولة لاحقًا.نعم

تكفي قراءة واحدة يوميًا لعملية تستغرق أيامًا. التزم بـ Retry-After عند تلقي 429 إذا كنت تتحقق من مواقع كثيرة في وقت واحد.

5. تابع صف Google في إدراجات الأنشطة التجارية

يتتبع صف إدراجات الأنشطة التجارية المميزة الوارد في الخطوة 1 التقدم نفسه من جانب إدراج النشاط التجاري. أعد تنفيذ الاستدعاء الوارد في الخطوة 1 واقرأ syncStatus وverified وlistingUrl.

syncStatusالمعنى
REQUIRING_ACTIONلم يُنشأ شيء بعد، أو أن الحساب يحتاج إلى معالجة. راجع displayStatus.
IN_PROGRESSأُرسل إلى Google، وفي انتظار الرد.
PENDING_APPROVALفي انتظار موافقة Google.
SYNCEDمنشور. يحتوي listingUrl على قيمة، ويحدد connectedAccountId اسم الحساب.
FAILEDرفضت Google الطلب المرسل. يوضح syncIssue السبب.

6. استمع إلى أحداث webhooks الخاصة بالتحقق

إذا عُيّن عنوان URL لـ webhook في لوحة التحكم، فهناك حدثان يغطيان الحالات النهائية، لذا لا تحتاج إلى الاستعلام الدوري. يحمل كلاهما location_id ويتضمنان دائمًا data.connected_account_id: null.

الحدثيُطلَق عندماحقول data
connection.google_verification_verifiedيصل الملف إلى VERIFIED.platform: "google"
connection.google_verification_failedيصل الملف إلى SUSPENDED أو DUPLICATE (failure_type: "rejected") أو ERROR_WHILE_FETCHING (failure_type: "transient").platform, failure_type, reason
JSON
{  "event": "connection.google_verification_failed",  "timestamp": "2026-08-25T14:52:31Z",  "account_id": 11073,  "location_id": "279381",  "data": { "platform": "google", "connected_account_id": null, "failure_type": "rejected", "reason": "This profile is suspended." }}

حالات الفشل من نوع transient وحدها تستحق إعادة المحاولة. لا تُطلِق الحالات قيد التنفيذ أي حدث على الإطلاق، لذا فإن غياب الأحداث لا يدل على شيء: أثناء إجراء التحقق، اقرأ googleVerificationStatus كما في الخطوة 4.

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