Listings APIListings API
Oturum aç

Apple Business Connect'i bağlayın

Apple Maps'e konumu doğrulanmış Apple Business hesabıyla, yoksa ListingsAPI ile yayımlayın; işletme kaydını inceleyin, müşteri ayrılınca bağlantıyı kesin.

ListingsAPI, bir konumun adını, kategorisini, adresini, telefonunu, web sitesini ve çalışma saatlerini iki yöntemden biriyle Apple Maps ve Siri'de yayımlar.

İşletme sahibinin hesap durumuNe olur?
Doğrulanmış bir Apple Business kuruluş hesabı varİşletme sahibi, bir OAuth bağlantısıyla hesabını konuma bağlar (1. ve 2. adımlar) ve ListingsAPI bu hesap üzerinden yayımlama yapar.
Doğrulanmış bir Apple Business kuruluş hesabı yokBağlantı gerekmez. ListingsAPI, konumu kendi Apple Business Connect hesabı üzerinden gönderir ve Apple, verileri yayımlamadan önce gönderimi doğrular. 3. adıma geçin.

OAuth, site değeri APPLE olarak ayarlanmış şekilde, her seferinde tek bir konumu bağlar.

İşletme sahibinin doğrulanmış bir Apple Business kuruluş hesabı yoksa 1. ve 2. adımları atlayın.

POST /locations/oauth_connect_url, kapsamı tek bir konumla sınırlı olan bir OAuth URL'si döndürür. Konum kimliğini ve iki yönlendirme URL'nizi içeren bir site: "APPLE" isteği gönderin. Başvuru: Bir konumu Apple Business Connect'e bağlama.

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

Yanıt, success, url ve errors içeren data.createConnectUrl biçimindedir. İşletme sahibini url adresine yönlendirin. İşletme sahibi, doğrulanmış Apple Business kuruluş hesabında oturum açar, erişim izni verir ve successUrl adresinize yönlendirilir; işlemi iptal ederse veya izin verme işlemi başarısız olursa errorUrl adresine yönlendirilir.

Bağlantı tek kullanımlıktır, bu nedenle her deneme için yeni bir bağlantı oluşturun. Göreli veya ayrıştırılamayan bir yönlendirme URL'si, url değeri null olan bir success: true yanıtı döndürülmesine neden olur; bu nedenle yönlendirmeden önce url değerini kontrol edin. Bu konum üzerinde işlem yapma yetkisi olmayan bir anahtarla yapılan istek, SY90003 içeren bir 403 yanıtı alır.

2. Bağlantıyı doğrulayın

İşletme sahibi successUrl adresinize döndükten sonra, bağlı hesapları Apple'a göre filtreleyerek listeleyin. Bu, offset tabanlı bir sayfadır: records[] ve pageInfo.totalRecords içerir, page ve perPage ile sayfalanır.

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

connectedAccountId değerini saklayın. status değeri CONNECTED, MATCH_IN_PROGRESS veya CONNECTIVITY_ISSUE olur; CONNECTED dışındaki her değer, güncellemelerin işletme sahibinin hesabı üzerinden iletilebilmesi için işletme sahibinin yeni bir bağlantı kurma bağlantısı açması gerektiği anlamına gelir.

3. Apple Maps işletme kaydını kontrol edin

İşletme sahibi bir hesap bağlamış olsa da olmasa da bu adım aynıdır. GET /locations/{locationId}/listings/premium, plandaki her premium yayın platformu için bir kayıt döndürür. Apple Maps kaydında site.url değeri business.apple.com olarak ayarlanmıştır.

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

Apple yer kartını yayımlayana kadar kayıt SYNCED durumunda değildir ve listingUrl değeri null olur. Konum ListingsAPI hesabı üzerinden gönderilmişse Apple, yayımlamadan önce gönderimi doğrular. Apple yayımladıktan sonra kayıt SYNCED durumuna geçer ve listingUrl değeri yayındaki Apple Maps URL'si olarak ayarlanır. Durum tablosunun tamamı için İşletme kaydı durumunu ve yayındaki bağlantıları kontrol etme bölümüne bakın.

Siri sonuçları, konumun Apple Maps işletme kaydından gelir. Bu sonuçların durumu, GET /locations/{locationId}/voice-assistants tarafından voiceIdentifier değeri SIRI olan kayıtta döndürülür.

4. Önerilen eşleşmeleri onaylayın

Bağlantı önerileri Apple kayıtları içeriyorsa bu kayıtların accountType değeri APPLE olur ve Bağlantı eşleşmelerini onaylama için kodlayacağınız eşleşme kaydı türü AppleLocationMatchedData olur. Kimliği, AppleLocationMatchedData:<matchedDataDatabaseId> değerinin base64 kodlaması olarak oluşturun ve matchRecordIds içinde gönderin.

5. Bir müşteri ayrıldığında konumun bağlantısını kesin

Bu adım yalnızca OAuth ile bağlanan bir konum için geçerlidir. POST /locations/oauth-disconnect, bir konum ile sahibinin Apple Business hesabı arasındaki bağlantıyı kaldırır. site: "APPLE" gönderin. Konum hesabınızda kalır ve diğer yayın platformu bağlantıları etkilenmez. Başvuru: Bir konumun Apple Business Connect bağlantısını kesme.

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

Yanıt, success ve errors içeren data.disconnectConnectedAccountsLocations olur. Etkin bir Apple bağlantısı olmayan bir konum SY10057 döndürür ve ne site ne de providerId içeren bir istek SY10056 döndürür.

6. Bundan sonra ne olur

Apple için connection.* webhook olayı yoktur. Konum sahibi OAuth ile bağlantı kurduysa hesapları listeleyerek bağlantıyı doğrulayın (2. adım). Her iki durumda da Apple Maps kaydını okuyarak yayın durumunu kontrol edin (3. adım). listing.submission olayı, yayın platformlarına yapılan her gönderimi nihai bir duruma ulaştığında bildirir.

Bağlantı daha sonra CONNECTIVITY_ISSUE durumunu bildirirse yeni bir bağlantı kurma bağlantısı oluşturun (1. adım) ve konum sahibinden yeniden oturum açmasını isteyin.

Sonraki adımlar