Social

Semua endpoint Social: merek, tautan koneksi terhosting, publikasi tunggal dan massal, penjadwalan, wawasan, serta batas koneksi untuk semuanya.

Social API memublikasikan postingan ke Facebook, Instagram, X, LinkedIn, dan Pinterest. Seluruh model ini bertumpu pada dua objek. Merek adalah identitas yang Anda gunakan untuk memublikasikan postingan: nama, zona waktu, dan akun media sosial yang terhubung dengannya. Koneksi adalah satu akun media sosial yang telah diotorisasi pada satu merek di satu platform. Jumlah merek tidak dibatasi dalam paket API dan tidak dikenai biaya. Paket menghitung penggunaan berdasarkan jumlah koneksi, jadi batas koneksi adalah kendala yang perlu Anda perhitungkan dalam desain.

Menghubungkan akun tidak dapat dilakukan dari server Anda. Pengguna akhir harus memberikan otorisasi di platform tersebut, jadi Anda meminta tautan yang dihosting lalu mengarahkan mereka ke tautan itu. Publikasi bersifat asinkron: setiap panggilan pembuatan langsung mengembalikan respons begitu postingan diterima, dan Anda melakukan polling untuk mendapatkan hasil per kanal.

Sekilas tentang endpoint

Nilai yang akan Anda gunakan di seluruh endpoint

Nilai platform berupa nama enum dalam huruf kapital. Pengiriman "instagram" akan ditolak. TWITTER adalah X; nama enum tidak berubah ketika nama produknya berubah.

Membuat merek

POST /social/brands

profileName dan timezone wajib diisi. Zona waktu berupa objek, dan tzCode adalah field yang menentukan: field ini berisi pengenal IANA yang digunakan untuk menafsirkan setiap scheduleDate dan scheduleTime pada postingan merek ini. Tiga key lainnya adalah label tampilan.

curl -X POST https://listingsapi.com/api/v4/social/brands \  -H "Authorization: API $LISTINGSAPI_KEY" \  -H "Content-Type: application/json" \  -d '{    "input": {      "profileName": "Jenny Home",      "timezone": {        "label": "(GMT-05:00) Eastern Time",        "tzCode": "America/New_York",        "name": "Eastern Standard Time",        "utc": "-05:00"      },      "categories": ["Furniture Store"],      "siteUrl": "https://jennyhome.example"    }  }'

Simpan ID merek yang dikembalikan. ID ini merupakan token path brandId pada setiap endpoint merek lainnya, dan field body socialProfileId saat Anda memublikasikan postingan.

Mencantumkan dan membaca merek

GET /social/brands mengembalikan satu halaman daftar merek. GET /social/brands/{brandId} mengembalikan satu merek beserta detail lengkapnya.

curl -H "Authorization: API $LISTINGSAPI_KEY" \  "https://listingsapi.com/api/v4/social/brands?page=1&size=25"

ID yang menghasilkan SY95043 berarti merek tersebut tidak ada pada akun ini atau sudah diarsipkan.

Memperbarui merek

POST /social/brands/update

ID merek ditempatkan dalam body sebagai input.profileId, bukan di path. Kirim hanya field yang Anda ubah; field yang Anda tidak sertakan tetap mempertahankan nilai saat ini.

curl -X POST https://listingsapi.com/api/v4/social/brands/update \  -H "Authorization: API $LISTINGSAPI_KEY" \  -H "Content-Type: application/json" \  -d '{"input": {"profileId": "6f2c9a41-7b0e-4d55-9a2f-3c8e1d47b902", "bio": "Handmade furniture for real homes."}}'

Mengarsipkan merek

POST /social/brands/archive

Merek harus sudah ada selama 90 hari sebelum dapat diarsipkan. Jika belum mencapai usia tersebut, panggilan ditolak dengan SY95051 dan tidak ada perubahan apa pun. Setelah merek cukup lama dibuat, pengarsipan langsung berlaku dan sekaligus mengarsipkan semua koneksi pada merek tersebut.

Koneksi tersebut langsung berhenti menerbitkan, tetapi slotnya tetap dihitung hingga akhir periode penagihan, sama persis seperti pemutusan koneksi secara manual. Pengarsipan bukan cara untuk mengosongkan kapasitas hari ini.

curl -X POST https://listingsapi.com/api/v4/social/brands/archive \  -H "Authorization: API $LISTINGSAPI_KEY" \  -H "Content-Type: application/json" \  -d '{"input": {"socialProfileId": "6f2c9a41-7b0e-4d55-9a2f-3c8e1d47b902"}}'

Mendapatkan tautan koneksi

POST /social/brands/{brandId}/connections/link

Ini adalah satu-satunya cara untuk menambahkan koneksi. Respons berisi url yang dihosting dan berlaku selama expiresIn detik. Arahkan pengguna akhir ke tautan tersebut, lalu mereka memberikan otorisasi di platform dan diarahkan kembali ke redirectUrl Anda dengan hasilnya di query string. Sertakan errorUrl untuk membedakan pembatalan dari keberhasilan, dan state untuk membawa nilai korelasi Anda sendiri sepanjang alur pengalihan pergi dan kembali.

Ingat bahwa body ini memiliki struktur datar, tanpa pembungkus input.

curl -X POST https://listingsapi.com/api/v4/social/brands/6f2c9a41-7b0e-4d55-9a2f-3c8e1d47b902/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/failed"  }'

{  "data": {    "connectSocialAccount": {      "status": "success",      "url": "https://social.listingsapi.com/connect/start?token=bfac8e06-8d72-4810-9c50-ae7ee12a7b52",      "expiresIn": 900    }  }}

Periksa status sebelum mengarahkan pengguna. Respons failed tidak mengembalikan url dan menempatkan alasannya di title, paling sering karena batas jumlah koneksi (SY95042) atau platform yang tidak dimiliki akun (SY95044).

Menampilkan daftar koneksi merek

GET /social/brands/{brandId}/connections

Mengembalikan akun yang terhubung ke merek, masing-masing dengan id yang Anda perlukan untuk menerbitkan melalui koneksi tertentu atau memutuskan koneksi tersebut.

curl -H "Authorization: API $LISTINGSAPI_KEY" \  https://listingsapi.com/api/v4/social/brands/6f2c9a41-7b0e-4d55-9a2f-3c8e1d47b902/connections

Memutuskan koneksi

POST /social/connections/disconnect

Menggunakan id koneksi dari daftar di atas. Akun langsung berhenti menerbitkan, tetapi slot yang digunakannya tidak dikembalikan ke kumpulan slot yang tersedia hingga periode penagihan berakhir. Menghubungkan kembali akun yang sama ke merek yang sama dalam periode tersebut menggunakan kembali slot itu tanpa biaya; menghubungkannya ke merek yang berbeda menggunakan slot kedua.

curl -X POST https://listingsapi.com/api/v4/social/connections/disconnect \  -H "Authorization: API $LISTINGSAPI_KEY" \  -H "Content-Type: application/json" \  -d '{"input": {"socialProfileConnectedChannelId": "b81d5b3c-4a90-4f6a-9c11-71e0dd2fa4a7"}}'

Menerbitkan postingan

POST /social/posts

Satu panggilan menerbitkan konten yang sama ke setiap platform dalam platforms. Setiap platform tersebut harus sudah memiliki koneksi pada merek, atau panggilan akan mengembalikan SY95045. Instagram dan Pinterest memerlukan setidaknya satu entri dalam mediaUrls.

Jadwalkan postingan dengan salah satu dari dua cara, jangan pernah menggunakan keduanya sekaligus. scheduledAt adalah timestamp ISO-8601 dengan offset. scheduleDate dan scheduleTime dikirim bersama dan ditafsirkan menurut zona waktu merek. Mengirim keduanya, atau jadwal di masa lalu, akan mengembalikan SY95046.

curl -X POST https://listingsapi.com/api/v4/social/posts \  -H "Authorization: API $LISTINGSAPI_KEY" \  -H "Content-Type: application/json" \  -d '{    "input": {      "socialProfileId": "6f2c9a41-7b0e-4d55-9a2f-3c8e1d47b902",      "name": "Autumn collection launch",      "platforms": ["INSTAGRAM", "FACEBOOK"],      "content": "Our autumn collection lands today.",      "mediaUrls": ["https://cdn.example.com/social/autumn-collection.jpg"],      "action": "SCHEDULE",      "scheduleDate": "2026-10-02",      "scheduleTime": "09:30",      "clientReference": "campaign-4471-slot-01"    }  }'

Tetapkan clientReference ke pengenal Anda sendiri. Pengenal ini disimpan dan dikembalikan, sehingga Anda dapat mencocokkan postingan dengan catatan Anda tanpa menyimpan UUID.

Membaca satu postingan

GET /social/posts/{postId}

Inilah cara Anda mengetahui apakah penerbitan berhasil. status pada postingan itu sendiri merupakan ringkasan; hasil sebenarnya tersedia per kanal dalam connectedChannels, dengan setiap entri memuat status masing-masing, liveLink setelah platform menerimanya, serta reason atau error jika platform tidak menerimanya.

{  "connectedChannels": [    {      "platform": "INSTAGRAM",      "status": "SUCCESS",      "liveLink": "https://www.instagram.com/p/CxYz1234abc/",      "error": null    }  ]}

Lakukan polling pada endpoint ini setelah menerima PUBLISH. Satu kanal dapat gagal sementara kanal lainnya berhasil, jadi periksa setiap entri, bukan hanya status di tingkat teratas.

Cantumkan postingan merek

GET /social/brands/{brandId}/posts

Satu halaman postingan merek, dengan filter untuk mempersempit hasil berdasarkan status. Gunakan ini untuk melakukan rekonsiliasi secara massal alih-alih melakukan polling id satu per satu.

curl -H "Authorization: API $LISTINGSAPI_KEY" \  "https://listingsapi.com/api/v4/social/brands/6f2c9a41-7b0e-4d55-9a2f-3c8e1d47b902/posts?page=1&size=25"

Batalkan postingan terjadwal

POST /social/posts/cancel

Membatalkan postingan yang belum dipublikasikan. Postingan yang sudah tayang di suatu platform tidak dapat ditarik kembali melalui endpoint ini.

curl -X POST https://listingsapi.com/api/v4/social/posts/cancel \  -H "Authorization: API $LISTINGSAPI_KEY" \  -H "Content-Type: application/json" \  -d '{"input": {"socialPostId": "a3f81c62-9d4e-4a17-b5c0-2e7f6d8a9b10"}}'

Baca wawasan dan komentar

GET /social/posts/{postId}/insights

Jumlah interaksi dan komentar untuk satu postingan di satu kanal. Kanal wajib ditentukan, karena postingan yang dipublikasikan ke tiga platform memiliki tiga kumpulan angka yang terpisah.

curl -H "Authorization: API $LISTINGSAPI_KEY" \  "https://listingsapi.com/api/v4/social/posts/a3f81c62-9d4e-4a17-b5c0-2e7f6d8a9b10/insights?socialConnectedChannelId=b81d5b3c-4a90-4f6a-9c11-71e0dd2fa4a7"

Buat postingan secara massal

POST /social/bulk-posts

Menerima 1 hingga 500 baris dalam input.posts. Setiap baris adalah objek yang sama dengan yang diterima POST /social/posts sebagai input, dan baris-baris tersebut dapat menargetkan merek yang berbeda dalam permintaan yang sama.

Seluruh batch divalidasi sebelum apa pun dibuat. Jika ada baris yang gagal, Anda mendapatkan SY95050 dengan kesalahan per baris dan tidak ada yang dimasukkan ke antrean, jadi perbaiki dan kirim ulang. Lebih dari 500 baris akan mengembalikan SY95048, dan dalam hal ini pun tidak ada yang dibuat. Batch yang valid mengembalikan tugas yang dapat dipantau melalui polling.

curl -X POST https://listingsapi.com/api/v4/social/bulk-posts \  -H "Authorization: API $LISTINGSAPI_KEY" \  -H "Content-Type: application/json" \  -d '{    "input": {      "name": "October launch batch",      "posts": [        {          "socialProfileId": "6f2c9a41-7b0e-4d55-9a2f-3c8e1d47b902",          "name": "Launch day",          "platforms": ["FACEBOOK"],          "content": "Doors open at nine.",          "action": "SCHEDULE",          "scheduleDate": "2026-10-02",          "scheduleTime": "09:00"        }      ]    }  }'

Operasi massal dihitung sebagai satu permintaan terhadap batas laju Anda, sehingga menjadi cara yang efisien untuk batch besar.

Lakukan polling tugas massal

GET /social/bulk-posts/{bulkJobId}

Mengembalikan status tugas beserta hasil per baris, termasuk id postingan yang dibuat untuk setiap baris dan baris apa pun yang gagal setelah dimasukkan ke antrean. Tugas tidak disimpan selamanya; id yang masa penyimpanannya telah habis akan mengembalikan SY95047.

curl -H "Authorization: API $LISTINGSAPI_KEY" \  https://listingsapi.com/api/v4/social/bulk-posts/f47ac10b-58cc-4372-a567-0e02b2c3d479

Periksa batas dan penggunaan

GET /social/limits

Baca ini sebelum membuat koneksi, bukan setelah menerima SY95042. Bandingkan usage.connections dengan maxConnections: itulah jumlah yang dikenai biaya, yaitu yang saat ini terhubung ditambah yang telah dilepas sebelumnya dalam periode ini. usage.connectionsActive adalah jumlah yang aktif saat ini, dan usage.connectionsReleased adalah jumlah kapasitas yang kembali tersedia saat perpanjangan.

brands mengembalikan nilai null, yang berarti tanpa batas. Jumlah merek tidak dihitung sebagai penggunaan pada paket API.

curl -H "Authorization: API $LISTINGSAPI_KEY" \  https://listingsapi.com/api/v4/social/limits

Kesalahan yang akan Anda temui

Daftar lengkap tersedia di referensi kode kesalahan.

Langkah berikutnya

Baca Paket dan add-on untuk mengetahui keterkaitan antara batas koneksi, paket berisi 5 koneksi, dan aturan pengarsipan 90 hari, serta Tanggapi peristiwa dengan webhook untuk menerima peristiwa social_post.* dan social_connection.* alih-alih melakukan polling.

Python SDK menyediakan endpoint ini sebagai client.social.brands, client.social.connections, client.social.posts, dan client.social.bulk; lihat Resource Social. Node SDK belum mendukung Social, jadi panggil endpoint REST langsung dari Node.