/api/v4/locations/oauth_connect_urlإنشاء عنوان URL للربط عبر OAuth لموقع واحد
ينشئ رابط OAuth لمنصة نشر يربط موقعًا واحدًا، مع عناوين إعادة التوجيه الخاصة بك للنجاح والخطأ.
المعلمات
النص الأساسي
| الاسم | النوع | مطلوب | الوصف |
|---|---|---|---|
| input | object | مطلوب | Wrapper object. The entire request body must be nested under `input`. |
| input.locationId | string | مطلوب | Location the connection will be attached to. Accepts a Base64-encoded Relay ID (e.g. `TG9jYXRpb246MTgwMDI4OQ==`) or a raw numeric location ID. |
| input.site | string | مطلوب | Publisher to connect: `GOOGLE`, `FACEBOOK`, or `APPLE`. |
| input.successUrl | string | مطلوب | Absolute URL the publisher returns the user to after they grant access. |
| input.errorUrl | string | مطلوب | Absolute URL the publisher returns the user to if they cancel or the grant fails. |
مثال على الطلب
نص جاهز للصق. استبدل المعرّفات والقيم النموذجية بقيمك.
{ "input": { "locationId": "TG9jYXRpb246MTgwMDI4OQ==", "site": "GOOGLE", "successUrl": "https://app.example.com/locations/1800289/connected", "errorUrl": "https://app.example.com/locations/1800289/connect-failed" }}الاستجابات
200A single-use OAuth URL to send the user to. `errors` is `null` on success. The `url` shown is a placeholder; send the user to the `url` returned in your own response.
{ "data": { "createConnectUrl": { "success": true, "url": "https://connect.example.com/oauth?token=8f3c1d92-...", "errors": null } }}401Unauthenticated, missing or invalid API key.
403The key is valid but not permitted to connect this location (`SY90003`).
يعيد عنوان URL للمصادقة عبر OAuth لدى منصة نشر، يقتصر نطاقه على موقع واحد. وجّه المستخدم النهائي إلى url؛ وعندما ينتهي، تعيد منصة النشر توجيهه إلى successUrl (أو errorUrl) الخاص بك، وتُربط بيانات الاعتماد الناتجة بالموقع بوصفها حسابًا متصلًا.
هذا هو المسار المخصص لموقع واحد، المقابل لمساري الربط الجماعي، ربط حسابات Google جماعيًا وربط حسابات Facebook جماعيًا، اللذين ينشئان رابطًا على مستوى الحساب ثم يعتمدان على المطابقة لربط إدراجات الأنشطة التجارية. استخدم هذا المسار عندما تعرف مسبقًا الموقع الذي يربطه المستخدم وتريد أن يعود إلى صفحة ذلك الموقع في منتجك.
عنوانا URL لإعادة التوجيه مطلوبان ويجب أن يكونا مطلقَين؛ فإذا أرسلت قيمة نسبية أو قيمة يتعذّر تحليلها، تعود الاستجابة بـ success: true وurl قيمته null، لذا تحقّق من url ولا تكتفِ بالتحقق من success. الرابط مخصص للاستخدام مرة واحدة ومرتبط بالموقع الذي حددته، لذا أنشئ رابطًا جديدًا لكل محاولة بدلًا من تخزينه مؤقتًا.
حالة استخدام: ربط متجر واحد من تطبيقك
عندما يربط مستخدم متجرًا واحدًا من تطبيقك، أرسل طلب POST إلى هذا المسار مع معرّف الموقع وsite: "GOOGLE" وعناوين URL لإعادة التوجيه تعيد المستخدم إلى تطبيقك. وجّه المستخدم إلى url في نافذة منبثقة أو عبر إعادة توجيه الصفحة بالكامل. عندما يعود، راجع الحصول على تفاصيل الحساب المتصل أو معلومات اتصال الموقع للتأكد من إتمام الربط، ثم اعرض حالة الاتصال في تطبيقك. إذا ترك المستخدم العملية قبل إكمالها، فسيصل إلى errorUrl ولن يُربط أي شيء، لذا أنشئ رابطًا جديدًا وأتح له المحاولة مرة أخرى.
حالة استخدام: النشر عبر حساب المالك في Apple Business
أرسل site: "APPLE" لربط موقع واحد بحساب المؤسسة المُتحقَّق منه التابع للمالك في Apple Business. يفتح المالك url، ويسجّل الدخول إلى ذلك الحساب، ويمنح إذن الوصول. ومن ذلك الحين فصاعدًا، تنشر ListingsAPI بيانات Apple Maps الخاصة بذلك الموقع عبر حساب المالك.
إذا لم يكن لدى المالك حساب مؤسسة مُتحقَّق منه في Apple Business، فتجاوز هذه العملية. تنشر ListingsAPI الموقع عبر حسابها الخاص في Apple Business Connect، وتتحقق Apple من طلب النشر قبل نشره. يُربط كل موقع على حدة، لذا يمكن أن يضم حساب واحد مواقع من كلا النوعين.
بعد عودة المالك إلى successUrl، استدعِ عرض الحسابات المتصلة مع publisher=AppleAccount وتحقّق من أن قيمة status للحساب هي CONNECTED. للاطلاع على العملية كاملة، بما في ذلك كيفية التحقق من إدراج النشاط التجاري على Apple Maps، راجع ربط Apple Business Connect.
تنشئ نقطة النهاية هذه بيانات اعتماد OAuth فعلية. نموذج الطلب ونموذج الاستجابة أعلاه مثالان توضيحيان.
curl -X POST 'https://listingsapi.com/api/v4/locations/oauth_connect_url' \ -H "Authorization: API $LISTINGSAPI_KEY" \ -H 'Content-Type: application/json' \ -d '{ "input": { "locationId": "TG9jYXRpb246MTgwMDI4OQ==", "site": "GOOGLE", "successUrl": "https://app.example.com/locations/1800289/connected", "errorUrl": "https://app.example.com/locations/1800289/connect-failed" } }'