/api/v4/locations/oauth_connect_urlربط موقع بخدمة Apple Business Connect
ينشئ رابط OAuth لخدمة Apple Business Connect لموقع واحد، لتنشر ListingsAPI الموقع على Apple Maps عبر حساب المالك الموثّق في Apple Business.
المعلمات
النص الأساسي
| الاسم | النوع | مطلوب | الوصف |
|---|---|---|---|
| input | object | مطلوب | Wrapper object. The entire request body must be nested under `input`. |
| input.locationId | string | مطلوب | Location to connect. Accepts a Base64-encoded Relay ID (e.g. `TG9jYXRpb246MTgwMDI4OQ==`) or a raw numeric location ID. |
| input.site | string | مطلوب | Set to `APPLE`. |
| input.successUrl | string | مطلوب | Absolute URL in your application the owner returns to after granting access. |
| input.errorUrl | string | مطلوب | Absolute URL in your application the owner returns to if they cancel or the grant fails. |
مثال على الطلب
نص جاهز للصق. استبدل المعرّفات والقيم النموذجية بقيمك.
{ "input": { "locationId": "TG9jYXRpb246MTgwMDI4OQ==", "site": "APPLE", "successUrl": "https://app.example.com/locations/1800289/apple/connected", "errorUrl": "https://app.example.com/locations/1800289/apple/connect-failed" }}الاستجابات
200A single-use link to send the owner to. `errors` is `null` on success. The `url` shown is a placeholder; send the owner 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`).
استخدم نقطة النهاية هذه عندما يكون لدى مالك النشاط التجاري حساب مؤسسة مُتحقَّق منه في Apple Business. وجّه المالك إلى url؛ حيث يسجّل الدخول إلى Apple Business Connect، ويمنح إذن الوصول، ثم يعود إلى successUrl الخاص بك. من تلك اللحظة، تنشر ListingsAPI اسم ذلك الموقع وفئته وعنوانه ورقم هاتفه وموقعه الإلكتروني وساعات عمله على Apple Maps من خلال حساب المالك. إذا ألغى المالك العملية أو فشل منح الإذن، فسيعود إلى errorUrl ولن يُربط أي شيء.
إذا لم يكن لدى المالك حساب مؤسسة مُتحقَّق منه في Apple Business، فتجاوز هذا الاستدعاء. تنشر ListingsAPI الموقع من خلال حسابها الخاص في Apple Business Connect، وتتحقّق Apple من طلب النشر قبل نشره.
تربط Apple موقعًا واحدًا لكل رابط. لربط عدة مواقع، أنشئ رابطًا لكل موقع. يجب أن يكون عنوانا URL لإعادة التوجيه مطلقَين؛ فإذا أرسلت قيمة نسبية أو قيمة يتعذّر تحليلها، تعود الاستجابة بـ success: true وurl قيمته null، لذا تحقّق من url قبل إعادة التوجيه. الرابط صالح للاستخدام مرة واحدة، لذا أنشئ رابطًا جديدًا لكل محاولة.
تأكيد الربط
بعد عودة المالك إلى successUrl، استدعِ عرض الحسابات المتصلة باستخدام publisher=AppleAccount. إذا كانت قيمة status هي CONNECTED، فهذا يعني أن التحديثات تمر عبر حساب المالك. أما MATCH_IN_PROGRESS أو CONNECTIVITY_ISSUE فيعني أن على المالك فتح رابط ربط جديد.
لإيقاف النشر من خلال حساب المالك، استخدم قطع اتصال موقع بـ Apple Business Connect. للاطلاع على سير العملية الكامل، بما في ذلك كيفية التحقّق من إدراج النشاط التجاري على Apple Maps، راجع ربط Apple Business Connect.
توثّق هذه الصفحة حالة site: "APPLE" من إنشاء عنوان URL للربط عبر OAuth لموقع واحد.
تنشئ نقطة النهاية هذه بيانات اعتماد 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": "APPLE", "successUrl": "https://app.example.com/locations/1800289/apple/connected", "errorUrl": "https://app.example.com/locations/1800289/apple/connect-failed" } }'