Listings APIListings API
Masuk
POST/api/v4/social/brands/{brandId}/connections/link

Dapatkan tautan koneksi

Mengembalikan URL yang dihosting dan berumur pendek untuk memandu pengguna akhir menghubungkan satu platform sosial ke sebuah merek.

Memerlukan kunci API. Lihat Autentikasi untuk format header dan rotasi kunci.

Parameter

Path

NamaTipeWajibDeskripsi
brandIdstringwajibBrand UUID the connection will be attached to.

Body

NamaTipeWajibDeskripsi
channelstringwajibPlatform to connect: `FACEBOOK`, `INSTAGRAM`, `TWITTER` (X), `LINKEDIN` or `PINTEREST`.
redirectUrlstringwajibAbsolute https URL in your application the user is returned to when the flow finishes. Must be a URL you control.
errorUrlstringopsionalAbsolute https URL the user is returned to if they cancel or the platform rejects the authorization. Defaults to `redirectUrl` when omitted.
statestringopsionalOpaque string echoed back on the return URL unchanged. Use it to correlate the return with the session that started the flow; it is not validated or interpreted.

Contoh permintaan

Body siap tempel. Ganti ID dan nilai placeholder dengan milik Anda.

Request body
{  "channel": "INSTAGRAM",  "redirectUrl": "https://app.example.com/social/connected",  "errorUrl": "https://app.example.com/social/connect-failed",  "state": "sess_9f2c1e64"}

Respons

200Link generated. Redirect the end user to `url`; `expiresIn` is how many seconds it stays valid.
Response
{  "data": {    "connectSocialAccount": {      "status": "success",      "url": "https://social.listingsapi.com/connect/start?token=bfac8e06-8d72-4810-9c50-ae7ee12a7b52",      "title": null,      "token": null,      "expiresIn": 900    }  }}
200The link could not be issued. `status` is `failed` and `title` carries the reason: most often the account is at its connection cap (`SY95042`, counted on billable connections, so recent disconnects have not freed room) or the platform is not enabled for the account (`SY95044`).
Response
{  "data": {    "connectSocialAccount": {      "status": "failed",      "url": null,      "title": "SY95042: Connection limit reached for this account",      "token": null,      "expiresIn": null    }  }}
401Unauthenticated, missing or invalid API key.
404No brand with that ID on this account (`SY95043`).

Menerbitkan URL berumur pendek yang menghubungkan satu platform sosial ke satu merek. Anda tidak pernah menangani kredensial OAuth platform tersebut: arahkan pengguna akhir Anda ke url yang dikembalikan, mereka menyelesaikan layar persetujuan platform dan memilih Halaman, papan, atau organisasi sebagai tujuan publikasi, lalu mereka diarahkan kembali ke redirectUrl Anda.

Ini adalah satu-satunya operasi tulis Social dengan struktur isi datar. Semua operasi tulis lainnya di Social API dibungkus dalam objek input; operasi ini tidak. Kirim channel, redirectUrl, serta errorUrl dan state jika diperlukan, di tingkat teratas.

Kasus penggunaan: koneksi kanal secara mandiri di dalam produk Anda. Tampilkan kelima platform kepada pengguna, dan saat mereka memilih salah satunya, panggil endpoint ini dengan channel tersebut dan state yang mengidentifikasi sesi mereka. Arahkan mereka ke url. Saat mereka kembali ke redirectUrl Anda dengan status=success, periksa GET /social/brands/{brandId}/connections secara berkala hingga kanal baru muncul, lalu izinkan mereka menyusun postingan pertama dengan POST /social/posts.

Tujuan pengalihan kembali pengguna

Saat alur berakhir, pengguna diarahkan ke redirectUrl (atau errorUrl) Anda dengan parameter kueri yang ditambahkan:

ParameterSelalu adaDeskripsi
statusyasuccess atau error.
brandIdyaMerek yang dikaitkan dengan koneksi tersebut. Sesuai dengan parameter jalur yang Anda gunakan saat melakukan pemanggilan.
platformyaPlatform yang dihubungkan, e.g. INSTAGRAM.
statehanya jika Anda mengirimkannyaNilai Anda yang tidak diinterpretasikan, dikembalikan tanpa perubahan.
connectedAccountIdhanya pada status=successUUID koneksi baru, yaitu id yang sama dengan yang muncul dalam daftar koneksi.
Code
https://app.example.com/social/connected  ?status=success  &brandId=6f2c9a41-7b0e-4d55-9a2f-3c8e1d47b902  &platform=INSTAGRAM  &state=sess_9f2c1e64  &connectedAccountId=b81d5b3c-4a90-4f6a-9c11-71e0dd2fa4a7

Catatan.

  • Tautan memiliki masa berlaku. expiresIn memuat masa berlakunya dalam detik. Tautan ini hanya dapat digunakan sekali: terbitkan saat pengguna mengeklik "hubungkan", bukan sebelumnya, dan jangan pernah menyimpannya. Jika pengguna meninggalkan alur, panggil endpoint ini lagi untuk mendapatkan URL baru.
  • Koneksi dibuat secara asinkron. Pengguna kembali ke redirectUrl Anda sesaat sebelum baris koneksi tersedia, sehingga pembacaan daftar koneksi segera setelah pengguna kembali memang dapat menghasilkan daftar yang belum memuat koneksi tersebut. Periksa daftar koneksi secara berkala selama beberapa detik, alih-alih menganggap hasil pembacaan pertama yang kosong sebagai kegagalan.
  • Instagram memerlukan akun Business atau Creator yang ditautkan ke Halaman Facebook. Akun Instagram pribadi tidak dapat dihubungkan, dan layar persetujuan platform tidak akan menawarkannya. Jika pengguna Anda mengalami hal ini, minta mereka mengonversi akun tersebut di aplikasi Instagram dan menautkannya ke Halaman yang mereka kelola, lalu terbitkan ulang tautannya.
  • TWITTER adalah X. Nilai enum tetap TWITTER demi kompatibilitas dengan versi sebelumnya; produknya adalah X. Nilai platform berupa nama enum dalam huruf kapital — pengiriman "instagram" akan ditolak.
  • redirectUrl dan errorUrl harus berupa URL https absolut. URL relatif atau http ditolak dengan SY95049.
  • Koneksi adalah sumber daya yang dihitung penggunaannya. Setiap penautan menggunakan satu kuota bersama untuk seluruh akun — 20 koneksi pada Social Launch, 125 pada Social Growth, ditambah lima untuk setiap paket koneksi seharga $25/bulan, hingga batas maksimum layanan mandiri sebesar 250. Jumlah merek sendiri tidak dibatasi, sehingga pemanggilan inilah yang selalu kehabisan kapasitas, bukan pembuatan merek. Saat kuota penuh, permintaan tautan mengembalikan status: "failed" dengan SY95042. Lihat Paket dan tambahan dan periksa sisa kapasitas Anda dari GET /social/limits.
  • Ini adalah padanan Social untuk tautan koneksi Facebook di tingkat lokasi, tetapi keduanya merupakan produk terpisah dan koneksi yang dibuat di salah satunya tidak terlihat di produk lainnya.

Operasi tulis: tidak dijalankan pada akun aktif. Permintaan dan respons yang ditampilkan dibuat berdasarkan skema API.

Request
curl -X POST 'https://listingsapi.com/api/v4/social/brands/<brandId>/connections/link' \  -H "Authorization: API $LISTINGSAPI_KEY" \  -H 'Content-Type: application/json' \  -d '{    "channel": "INSTAGRAM",    "redirectUrl": "https://app.example.com/social/connected",    "errorUrl": "https://app.example.com/social/connect-failed",    "state": "sess_9f2c1e64"  }'
Run in playground