/api/v4/locations/oauth_connect_urlBuat URL koneksi OAuth untuk satu lokasi
Membuat tautan OAuth platform publikasi yang menghubungkan satu lokasi, dengan URL pengalihan Anda sendiri untuk keberhasilan dan kesalahan.
Parameter
Body
| Nama | Tipe | Wajib | Deskripsi |
|---|---|---|---|
| input | object | wajib | Wrapper object. The entire request body must be nested under `input`. |
| input.locationId | string | wajib | 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 | wajib | Publisher to connect: `GOOGLE`, `FACEBOOK`, or `APPLE`. |
| input.successUrl | string | wajib | Absolute URL the publisher returns the user to after they grant access. |
| input.errorUrl | string | wajib | Absolute URL the publisher returns the user to if they cancel or the grant fails. |
Contoh permintaan
Body siap tempel. Ganti ID dan nilai placeholder dengan milik Anda.
{ "input": { "locationId": "TG9jYXRpb246MTgwMDI4OQ==", "site": "GOOGLE", "successUrl": "https://app.example.com/locations/1800289/connected", "errorUrl": "https://app.example.com/locations/1800289/connect-failed" }}Respons
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`).
Mengembalikan URL OAuth platform publikasi yang cakupannya terbatas pada satu lokasi. Arahkan pengguna akhir ke url; setelah mereka selesai, platform publikasi mengalihkan mereka ke successUrl (atau errorUrl) Anda, dan kredensial yang dihasilkan ditautkan ke lokasi tersebut sebagai akun terhubung.
Ini adalah versi untuk satu lokasi dari alur massal, Hubungkan akun Google secara massal dan Hubungkan akun Facebook secara massal, yang membuat tautan dengan cakupan seluruh akun lalu mengandalkan pencocokan untuk menautkan profil bisnis. Gunakan rute ini jika Anda sudah mengetahui lokasi mana yang dihubungkan pengguna dan ingin mereka kembali ke halaman lokasi tersebut di produk Anda sendiri.
Kedua URL pengalihan wajib diisi dan harus berupa URL absolut; nilai relatif atau yang tidak dapat diurai akan menghasilkan success: true dengan null url, jadi periksa url dan bukan hanya success. Tautan ini hanya dapat digunakan sekali dan terikat pada lokasi yang Anda tentukan, jadi buat tautan baru untuk setiap percobaan alih-alih menyimpannya dalam cache.
Kasus penggunaan: menghubungkan satu toko dari aplikasi Anda sendiri
Saat pengguna menghubungkan satu toko dari aplikasi Anda, kirim permintaan POST ke rute ini dengan ID lokasi, site: "GOOGLE", dan URL pengalihan yang mengarah kembali ke aplikasi Anda. Arahkan pengguna ke url melalui jendela pop-up atau pengalihan halaman penuh. Setelah mereka kembali, baca Dapatkan detail akun terhubung atau informasi koneksi lokasi untuk memastikan penautan berhasil, lalu tampilkan status terhubung di aplikasi Anda. Jika pengguna meninggalkan alur, mereka akan diarahkan ke errorUrl dan tidak ada yang ditautkan, jadi buat tautan baru dan izinkan mereka mencoba lagi.
Kasus penggunaan: memublikasikan melalui akun Apple Business milik pemilik
Kirim site: "APPLE" untuk menghubungkan satu lokasi ke akun organisasi Apple Business terverifikasi milik pemilik. Pemilik membuka url, masuk ke akun tersebut, dan memberikan akses. Sejak saat itu, ListingsAPI memublikasikan data Apple Maps untuk lokasi tersebut melalui akun milik pemilik.
Jika pemilik tidak memiliki akun organisasi Apple Business yang terverifikasi, lewati alur ini. ListingsAPI memublikasikan lokasi tersebut melalui akun Apple Business Connect miliknya sendiri, dan Apple memverifikasi pengajuan tersebut sebelum memublikasikannya. Setiap lokasi dihubungkan secara terpisah, sehingga satu akun dapat memiliki kedua jenis lokasi tersebut.
Setelah pemilik kembali ke successUrl, panggil Daftar akun terhubung dengan publisher=AppleAccount dan periksa bahwa status akun tersebut bernilai CONNECTED. Untuk alur lengkap, termasuk cara memeriksa profil bisnis di Apple Maps, lihat Hubungkan Apple Business Connect.
Endpoint ini membuat kredensial OAuth aktif. Sampel permintaan dan respons di atas merupakan contoh.
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" } }'