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

ربط Apple Business Connect

انشر موقعًا على Apple Maps بحساب Apple Business الموثّق للمالك أو حساب ListingsAPI إن لم يملكه، وتحقق من الإدراج وافصل الربط عند مغادرة العميل.

تنشر ListingsAPI اسم الموقع وفئته وعنوانه ورقم هاتفه وموقعه الإلكتروني وساعات عمله على Apple Maps وSiri بإحدى طريقتين.

ما لدى مالك النشاط التجاريما يحدث
حساب مؤسسة موثّق في Apple Businessيربطه المالك بالموقع باستخدام رابط OAuth (الخطوتان 1 و2)، وتنشر ListingsAPI من خلال حسابه.
لا يوجد حساب مؤسسة موثّق في Apple Businessلا حاجة إلى الربط. تُرسل ListingsAPI الموقع من خلال حساب Apple Business Connect الخاص بها، وتتحقّق Apple من الطلب قبل نشر البيانات. انتقل إلى الخطوة 3.

يربط OAuth موقعًا واحدًا في كل مرة، مع ضبط site على APPLE.

تجاوز الخطوتين 1 و2 إذا لم يكن لدى المالك حساب مؤسسة موثّق في Apple Business.

يُرجع POST /locations/oauth_connect_url عنوان URL لـ OAuth يقتصر نطاقه على موقع واحد. أرسل site: "APPLE" مع معرّف الموقع وعنوانَي URL لإعادة التوجيه. المرجع: ربط موقع بـ Apple Business Connect.

Connect link
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"  }}'

تكون الاستجابة data.createConnectUrl مع success وurl وerrors. أعِد توجيه المالك إلى url. يسجّل المالك الدخول إلى حساب المؤسسة الموثّق الخاص به في Apple Business، ويمنح إذن الوصول، ثم يُعاد توجيهه إلى successUrl الخاص بك؛ وإذا ألغى العملية أو فشل منح الإذن، يُعاد توجيهه إلى errorUrl.

الرابط مخصّص للاستخدام مرة واحدة، لذا أنشئ رابطًا جديدًا لكل محاولة. إذا كان عنوان URL لإعادة التوجيه نسبيًا أو غير قابل للتحليل، فستكون الاستجابة success: true مع null في url، لذا تحقّق من url قبل إعادة التوجيه. إذا استُخدم مفتاح غير مخوّل بالتعامل مع هذا الموقع، فستكون الاستجابة 403 مع SY90003.

2. تأكّد من الربط

بعد عودة المالك إلى successUrl الخاص بك، اعرض الحسابات المتصلة مع تصفيتها لتقتصر على Apple. هذه صفحة تعتمد على الإزاحة: records[] بالإضافة إلى pageInfo.totalRecords، ويُتنقّل بين الصفحات باستخدام page وperPage.

List accounts
curl "https://listingsapi.com/api/v4/connected-accounts?publisher=AppleAccount&page=1&perPage=20" \-H "Authorization: API $LISTINGSAPI_KEY"

احتفظ بـ connectedAccountId. تكون قيمة status هي CONNECTED أو MATCH_IN_PROGRESS أو CONNECTIVITY_ISSUE؛ وأي قيمة بخلاف CONNECTED تعني أن على المالك فتح رابط ربط جديد قبل أن تتمكّن التحديثات من المرور عبر حسابه.

3. تحقّق من إدراج النشاط التجاري على Apple Maps

هذه الخطوة هي نفسها سواء ربط المالك حسابًا أم لم يربطه. يُرجع GET /locations/{locationId}/listings/premium سجلًا واحدًا لكل منصة نشر مميزة ضمن الخطة. يحتوي سجل Apple Maps على site.url مضبوطًا على business.apple.com.

Apple Maps status
curl https://listingsapi.com/api/v4/locations/TG9jYXRpb246MTgwMDI4OQ==/listings/premium \-H "Authorization: API $LISTINGSAPI_KEY"

لا يكون السجل SYNCED، وتكون قيمة listingUrl هي null إلى أن تنشر Apple بطاقة المكان. إذا أُرسل الموقع من خلال حساب ListingsAPI، فتتحقّق Apple من الطلب قبل النشر. بمجرد أن تنشر Apple بطاقة المكان، يصبح السجل SYNCED مع ضبط listingUrl على عنوان URL المنشور على Apple Maps. للاطّلاع على جدول الحالات الكامل، راجع التحقّق من حالة إدراج النشاط التجاري والروابط المنشورة.

تأتي نتائج Siri من إدراج النشاط التجاري الخاص بالموقع على Apple Maps. يُرجع GET /locations/{locationId}/voice-assistants حالتها ضمن voiceIdentifier بالقيمة SIRI.

4. أكّد المطابقات المقترحة

إذا تضمنت اقتراحات الربط سجلات Apple، فإن قيمة accountType فيها تكون APPLE، ونوع سجل المطابقة الذي ترمّزه من أجل تأكيد مطابقات الربط هو AppleLocationMatchedData. أنشئ المعرّف بترميز AppleLocationMatchedData:<matchedDataDatabaseId> باستخدام base64 وأرسله في matchRecordIds.

5. افصل اتصال الموقع عندما يغادر العميل

تنطبق هذه الخطوة فقط على موقع متصل باستخدام OAuth. يزيل POST /locations/oauth-disconnect الاتصال بين موقع واحد وحساب المالك على Apple Business. أرسل site: "APPLE". يبقى الموقع في حسابك ولا تتأثر اتصالاته بمنصات النشر الأخرى. المرجع: فصل اتصال موقع عن Apple Business Connect.

Disconnect
curl -X POST https://listingsapi.com/api/v4/locations/oauth-disconnect \-H "Authorization: API $LISTINGSAPI_KEY" \-H "Content-Type: application/json" \-d '{ "input": { "locationId": "TG9jYXRpb246MTgwMDI4OQ==", "site": "APPLE" } }'

تكون الاستجابة data.disconnectConnectedAccountsLocations مع success وerrors. يُرجَع SY10057 لموقع ليس لديه اتصال نشط بـ Apple، ويُرجَع SY10056 لطلب لا يتضمن site ولا providerId.

6. ما يحدث بعد ذلك

لا يوجد حدث webhook من نوع connection.* لـ Apple. إذا أجرى المالك الاتصال باستخدام OAuth، فتحقق من الاتصال عبر سرد الحسابات (الخطوة 2). في كلتا الحالتين، تحقق من حالة النشر عبر قراءة سجل Apple Maps (الخطوة 3). يُبلغ الحدث listing.submission عن كل عملية إرسال إلى منصة نشر عندما تصل إلى حالة نهائية.

إذا أظهر الاتصال لاحقًا الحالة CONNECTIVITY_ISSUE، فأنشئ رابط ربط جديدًا (الخطوة 1) واطلب من المالك تسجيل الدخول مرة أخرى.

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