/api/v4/connected-accounts/connect-googleربط حساب Google
تُرجع عنوان URL لتفويض OAuth لربط حساب Google Business Profile بحسابك في Listings API.
المعلمات
النص الأساسي
| الاسم | النوع | مطلوب | الوصف |
|---|---|---|---|
| input | object | مطلوب | Wrapper object. The entire request body must be nested under `input`. |
| input.successUrl | string | مطلوب | URL the user is redirected to after they successfully authorize Google. Must be an absolute https URL you control. |
| input.errorUrl | string | مطلوب | URL the user is redirected to if they cancel or the authorization fails. Must be an absolute https URL you control. |
مثال على الطلب
نص جاهز للصق. استبدل المعرّفات والقيم النموذجية بقيمك.
{ "input": { "successUrl": "https://listingsapi.com/docs/api/connected-accounts-trigger-matches", "errorUrl": "https://listingsapi.com/docs/api/connected-accounts-connect" }}الاستجابات
200OAuth URL generated successfully. Redirect the user to `url` to begin the Google authorization flow. The `url` shown is a placeholder; send the user to the `url` returned in your own response.
{ "data": { "bulkConnectLinkForGoogle": { "errors": null, "success": true, "url": "https://connect.example.com/oauth?token=8f3c1d92-..." } }}400Bad request, the body was not wrapped in `input`, or `successUrl`/`errorUrl` was omitted (error message: `Variable "$input" of required type "GoogleOauthBulkInput!" was not provided`).
401Unauthenticated, missing or invalid API key.
تُنشئ عنوان URL قصير الأجل لتفويض OAuth يزوره المستخدم للسماح لـ Listings API بإدارة مواقعه على Google Business Profile بشكل جماعي. أعد توجيه المستخدم إلى url المُرجَع؛ ليُكمل خطوات شاشة الموافقة في Google، ثم يُعاد توجيهه إلى أحد عناوين URL التي قدّمتها. يظل الرابط صالحًا لمدة 24 ساعة.
بنية الطلب. يجب تغليف جسم الطلب في كائن input يحتوي على حقلين مطلوبين، هما successUrl وerrorUrl. وهما عنوانا URL مطلقان بالبروتوكول https، يُعاد المستخدم إلى أحدهما بعد إكمال خطوات شاشة الموافقة في Google (أو التخلي عنها)؛ مرّر نقطتي نهاية في تطبيقك تستأنفان عملية الإعداد عند النجاح وتتيحان إعادة المحاولة عند حدوث خطأ. لا يوجد حقل accountId، ويقتصر نطاق رابط الربط دائمًا على الحساب الذي يملك مفتاح API، ويُرفض إرسال accountId (أو جسم طلب مسطّح غير مغلّف) برمز حالة HTTP 400.
هذه هي الخطوة الأولى في سير عمل الربط الجماعي. بمجرد منح التفويض للحساب، يظهر في نقطة نهاية عرض الحسابات المتصلة (GET /connected-accounts) مع connectedAccountId تستخدمه في كل استدعاء لاحق.
حالة استخدام: إعداد الملفات التجارية على Google لعميل وكالة. يمنحك عميل جديد صلاحية الوصول إلى ملفه على Google Business Profile. استدعِ نقطة النهاية هذه، وأعد توجيهه إلى url المُرجَع، وبعد موافقته تصبح إدراجات أنشطته التجارية على Google متاحة ضمن الحساب المتصل الجديد. ثم شغّل POST /connected-accounts/trigger-matches لمطابقة إدراجات الأنشطة التجارية تلك على Google مع مواقعك في Listings API، وراجع أزواج المطابقة باستخدام GET /connected-accounts/{connectedAccountId}/connection-suggestions، واعتمدها نهائيًا باستخدام POST /connected-accounts/confirm-matches.
حالة استخدام: إصلاح بيانات الاعتماد المنتهية الصلاحية. عندما تنتهي صلاحية رمز Google المميز لحساب متصل، تتوقف مزامنة تحديثات إدراجات الأنشطة التجارية. أعد إصدار رابط ربط باستخدام نقطة النهاية هذه، واطلب من مالك الحساب منح التفويض مجددًا؛ إذ يُحدَّث الاتصال الحالي بدلًا من إنشاء نسخة مكررة منه.
بالنسبة إلى Facebook، استخدم نقطة النهاية connect-facebook. تشير success: true مع قيمة غير null للحقل url إلى أن الرابط قد أُنشئ؛ ولا تُسنَد قيمة إلى errors إلا عند فشل الإنشاء.
curl -X POST 'https://listingsapi.com/api/v4/connected-accounts/connect-google' \ -H "Authorization: API $LISTINGSAPI_KEY" \ -H 'Content-Type: application/json' \ -d '{ "input": { "successUrl": "https://listingsapi.com/docs/api/connected-accounts-trigger-matches", "errorUrl": "https://listingsapi.com/docs/api/connected-accounts-connect" } }'