Listings APIListings API
Masuk

Hubungkan Apple Business Connect

Kirim lokasi ke Apple Maps via akun Apple Business pemilik terverifikasi atau ListingsAPI jika tak ada; cek profil bisnis, putus koneksi saat klien pergi.

ListingsAPI memublikasikan nama, kategori, alamat, nomor telepon, situs web, dan jam operasional lokasi ke Apple Maps dan Siri melalui salah satu dari dua cara.

Pemilik bisnis memilikiYang terjadi
Akun organisasi Apple Business yang terverifikasiPemilik menghubungkan akun tersebut ke lokasi melalui tautan OAuth (langkah 1 dan 2), dan ListingsAPI memublikasikan data melalui akun tersebut.
Tidak memiliki akun organisasi Apple Business yang terverifikasiTidak diperlukan koneksi. ListingsAPI mengirimkan lokasi melalui akun Apple Business Connect miliknya sendiri, dan Apple memverifikasi pengajuan tersebut sebelum memublikasikan datanya. Lanjutkan ke langkah 3.

OAuth menghubungkan satu lokasi dalam satu waktu, dengan site diatur ke APPLE.

Lewati langkah 1 dan 2 jika pemilik tidak memiliki akun organisasi Apple Business yang terverifikasi.

POST /locations/oauth_connect_url mengembalikan URL OAuth dengan cakupan satu lokasi. Kirim site: "APPLE" dengan ID lokasi dan kedua URL pengalihan Anda. Referensi: Hubungkan lokasi ke 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"  }}'

Responsnya adalah data.createConnectUrl dengan success, url, dan errors. Arahkan pemilik ke url. Pemilik masuk ke akun organisasi Apple Business terverifikasi miliknya, memberikan akses, lalu diarahkan ke successUrl Anda; jika pemilik membatalkan atau pemberian akses gagal, pemilik diarahkan ke errorUrl.

Tautan hanya dapat digunakan sekali, jadi buat tautan baru untuk setiap percobaan. URL pengalihan yang relatif atau tidak dapat diurai menghasilkan respons success: true dengan url bernilai null, jadi periksa url sebelum mengarahkan pemilik. Kunci yang tidak diizinkan mengakses lokasi ini menerima respons 403 dengan SY90003.

2. Konfirmasikan koneksi

Setelah pemilik kembali ke successUrl Anda, ambil daftar akun yang terhubung dengan filter untuk Apple. Ini adalah halaman berbasis offset: records[] ditambah pageInfo.totalRecords, dengan paginasi menggunakan page dan perPage.

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

Simpan connectedAccountId. Nilai status adalah CONNECTED, MATCH_IN_PROGRESS, atau CONNECTIVITY_ISSUE; nilai selain CONNECTED berarti pemilik harus membuka tautan koneksi baru sebelum pembaruan dapat dikirim melalui akun miliknya.

3. Periksa profil bisnis di Apple Maps

Langkah ini sama, baik pemilik telah menghubungkan akun maupun belum. GET /locations/{locationId}/listings/premium mengembalikan satu catatan untuk setiap platform publikasi premium dalam paket tersebut. Catatan Apple Maps memiliki site.url yang diatur ke business.apple.com.

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

Catatan tersebut bukan SYNCED dan nilai listingUrl adalah null hingga Apple memublikasikan kartu tempat. Jika lokasi dikirimkan melalui akun ListingsAPI, Apple memverifikasi pengajuan tersebut sebelum memublikasikannya. Setelah Apple memublikasikannya, catatan tersebut menjadi SYNCED dengan listingUrl diatur ke URL Apple Maps yang aktif. Untuk tabel status lengkap, lihat Periksa status profil bisnis dan tautan aktif.

Hasil Siri berasal dari profil bisnis lokasi tersebut di Apple Maps. Status hasil tersebut dikembalikan oleh GET /locations/{locationId}/voice-assistants pada voiceIdentifier SIRI.

4. Konfirmasikan kecocokan yang disarankan

Jika saran koneksi mencakup catatan Apple, nilai accountType catatan tersebut adalah APPLE, dan jenis catatan kecocokan yang Anda enkode untuk Konfirmasikan kecocokan koneksi adalah AppleLocationMatchedData. Buat ID dengan mengenkode AppleLocationMatchedData:<matchedDataDatabaseId> dalam base64, lalu kirimkan ID tersebut dalam matchRecordIds.

5. Putuskan koneksi lokasi saat klien berhenti menjadi pelanggan

Langkah ini hanya berlaku untuk lokasi yang terhubung melalui OAuth. POST /locations/oauth-disconnect menghapus koneksi antara satu lokasi dan akun Apple Business pemiliknya. Kirim site: "APPLE". Lokasi tetap berada di akun Anda dan koneksinya ke platform publikasi lain tidak terpengaruh. Referensi: Putuskan koneksi lokasi dari 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" } }'

Responsnya adalah data.disconnectConnectedAccountsLocations dengan success dan errors. Lokasi tanpa koneksi Apple yang aktif mengembalikan SY10057, dan permintaan yang tidak menyertakan site maupun providerId mengembalikan SY10056.

6. Apa yang terjadi selanjutnya

Tidak ada peristiwa webhook connection.* untuk Apple. Jika pemilik terhubung melalui OAuth, konfirmasikan koneksinya dengan mengambil daftar akun (langkah 2). Dalam kedua kasus tersebut, periksa status publikasi dengan membaca catatan Apple Maps (langkah 3). Peristiwa listing.submission melaporkan setiap pengajuan ke platform publikasi saat pengajuan tersebut mencapai status akhir.

Jika koneksi kemudian melaporkan CONNECTIVITY_ISSUE, buat tautan koneksi baru (langkah 1) dan minta pemilik untuk masuk kembali.

Langkah selanjutnya