Social
Tüm Social uç noktaları: markalar, barındırılan bağlantı kurma linkleri, tekli ve toplu yayın, zamanlama, istatistikler ve genel bağlantı sınırı.
Social API; Facebook, Instagram, X, LinkedIn ve Pinterest'te yayın yapar. Modelin tamamı iki nesneye dayanır. Marka, adına yayın yaptığınız kimliktir: bir ad, bir saat dilimi ve bu kimliğe bağlı sosyal medya hesapları. Bağlantı, bir platformda bir markaya bağlı, yetkilendirilmiş tek bir sosyal medya hesabıdır. API planında marka sayısı sınırsızdır ve markalar ücretsizdir. Planın kullanım ölçütü bağlantılardır; bu nedenle tasarımınızı bağlantı sınırını gözeterek yapmalısınız.
Bir hesabı bağlama işlemi sunucunuzdan yapılamaz. Son kullanıcının platformda yetki vermesi gerekir; bu nedenle barındırılan bir bağlantı talep eder ve kullanıcıyı bu bağlantıya yönlendirirsiniz. Yayınlama asenkrondur: her oluşturma çağrısı, gönderi kabul edilir edilmez döner ve kanal bazındaki sonucu almak için düzenli aralıklarla sorgulama yaparsınız.
Bir bakışta endpoint'ler
Her yerde kullanacağınız değerler
Platform değerleri, büyük harfle yazılmış enum adlarıdır. "instagram" gönderilirse istek reddedilir. TWITTER, X'i ifade eder; ürünün adı değiştiğinde enum adı değişmemiştir.
Marka oluşturma
POST /social/brands
profileName ve timezone zorunludur. Saat dilimi bir nesnedir ve önemli olan alan tzCode'dir: bu, markanın gönderilerindeki her scheduleDate ve scheduleTime değerini yorumlamak için kullanılan IANA tanımlayıcısıdır. Diğer üç anahtar, görüntüleme etiketleridir.
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" } }'Döndürülen marka kimliğini saklayın. Bu kimlik, diğer tüm marka endpoint'lerinde yoldaki brandId yer tutucusunun, yayınlama sırasında ise gövdedeki socialProfileId alanının değeridir.
Markaları listeleme ve okuma
GET /social/brands, markaları içeren bir sayfa döndürür. GET /social/brands/{brandId}, tek bir markayı tüm ayrıntılarıyla döndürür.
curl -H "Authorization: API $LISTINGSAPI_KEY" \ "https://listingsapi.com/api/v4/social/brands?page=1&size=25"Bir kimlikle yapılan istek SY95043 döndürüyorsa bu kimlik ya bu hesaba ait değildir ya da ilgili marka zaten arşivlenmiştir.
Bir markayı güncelleyin
POST /social/brands/update
Markanın id değeri yolda değil, gövdede input.profileId olarak yer alır. Yalnızca değiştirdiğiniz alanları gönderin; göndermediğiniz alanlar mevcut değerlerini korur.
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."}}'Bir markayı arşivleyin
POST /social/brands/archive
Bir markanın arşivlenebilmesi için oluşturulmasının üzerinden 90 gün geçmiş olması gerekir. Bu süre dolmadan yapılan çağrı SY95051 ile reddedilir ve hiçbir şey değişmez. Marka gerekli süreyi doldurduğunda arşivleme hemen geçerli olur ve markanın tüm bağlantıları da aynı anda arşivlenir.
Bu bağlantılar hemen yayın yapmayı durdurur, ancak tıpkı bağlantının elle kesilmesinde olduğu gibi, kullandıkları kontenjan fatura döneminin sonuna kadar dolu sayılmaya devam eder. Arşivleme, bugün kapasite açmanın bir yolu değildir.
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"}}'Bir bağlantı kurma bağlantısı alın
POST /social/brands/{brandId}/connections/link
Bağlantı eklemenin tek yolu budur. Yanıt, expiresIn saniye boyunca geçerli olan, barındırılan bir url içerir. Son kullanıcıyı bu adrese yönlendirin; kullanıcı platformda yetki verir ve sonuç sorgu dizesinde yer alacak şekilde sizin redirectUrl adresinize geri yönlendirilir. İptalleri başarılı işlemlerden ayırt etmek için errorUrl, kendi ilişkilendirme değerinizi gidiş-dönüş boyunca taşımak için de state parametresini iletin.
Bu gövdenin düz bir yapıda olduğunu ve input sarmalayıcısı içermediğini unutmayın.
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 } }}Yönlendirmeden önce status değerini kontrol edin. failed yanıtı url döndürmez ve nedeni title içinde belirtir; bu neden çoğunlukla bağlantı sınırı (SY95042) veya hesabın sahip olmadığı bir platformdur (SY95044).
Bir markanın bağlantılarını listeleyin
GET /social/brands/{brandId}/connections
Markaya bağlı hesapları, belirli bir bağlantıda yayın yapmak veya bu bağlantıyı kesmek için gereken id değeriyle birlikte döndürür.
curl -H "Authorization: API $LISTINGSAPI_KEY" \ https://listingsapi.com/api/v4/social/brands/6f2c9a41-7b0e-4d55-9a2f-3c8e1d47b902/connectionsBir bağlantıyı kesin
POST /social/connections/disconnect
Yukarıdaki listeden bağlantının id değerini alır. Hesap hemen yayın yapmayı durdurur, ancak kullandığı kontenjan fatura dönemi bitene kadar havuza geri verilmez. Aynı hesabı dönem içinde aynı markaya yeniden bağlamak aynı kontenjanı kullanır ve hiçbir ek maliyet oluşturmaz; hesabı farklı bir markaya bağlamak ise ikinci bir kontenjan kullanır.
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"}}'Bir gönderi yayınlayın
POST /social/posts
Tek bir çağrı, aynı içeriği platforms içindeki tüm platformlarda yayınlar. Bu platformların her biri için markada önceden kurulmuş bir bağlantı bulunmalıdır; aksi takdirde çağrı SY95045 döndürür. Instagram ve Pinterest, mediaUrls içinde en az bir öğe gerektirir.
Bir gönderiyi iki yöntemden biriyle zamanlayın; asla ikisini birden kullanmayın. scheduledAt, saat farkı içeren bir ISO-8601 zaman damgasıdır. scheduleDate ve scheduleTime birlikte gönderilir ve markanın saat dilimine göre yorumlanır. Her iki yöntemin birlikte gönderilmesi veya geçmişte kalan bir zamana zamanlama yapılması durumunda SY95046 döndürülür.
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" } }'clientReference alanını kendi tanımlayıcınıza ayarlayın. Bu değer saklanır ve döndürülür; böylece UUID değerini saklamadan bir gönderiyi kendi kayıtlarınızla eşleştirebilirsiniz.
Tek bir gönderiyi okuyun
GET /social/posts/{postId}
Yayınlamanın başarılı olup olmadığını bu şekilde öğrenirsiniz. Gönderinin kendi status değeri bir özettir; asıl sonuç connectedChannels içinde kanal bazında yer alır ve buradaki her kayıt kendi status değerini, platform kabul ettiğinde bir liveLink değerini, kabul etmediğinde ise reason veya error değerini içerir.
{ "connectedChannels": [ { "platform": "INSTAGRAM", "status": "SUCCESS", "liveLink": "https://www.instagram.com/p/CxYz1234abc/", "error": null } ]}PUBLISH sonrasında bu uç noktayı düzenli aralıklarla sorgulayın. Diğer kanallar başarılı olurken bir kanal başarısız olabilir; bu nedenle yalnızca en üst düzeydeki status değerini kontrol etmek yerine her kaydı kontrol edin.
Bir markanın gönderilerini listeleyin
GET /social/brands/{brandId}/posts
Markanın gönderilerini içeren, duruma göre daraltmaya yönelik filtreler sunan bir sonuç sayfası. Gönderi durumlarını topluca eşitlemek için id değerlerini tek tek sorgulamak yerine bunu kullanın.
curl -H "Authorization: API $LISTINGSAPI_KEY" \ "https://listingsapi.com/api/v4/social/brands/6f2c9a41-7b0e-4d55-9a2f-3c8e1d47b902/posts?page=1&size=25"Zamanlanmış bir gönderiyi iptal edin
POST /social/posts/cancel
Henüz yayımlanmamış bir gönderiyi iptal eder. Bir platformda zaten yayında olan bir gönderi bu endpoint üzerinden geri alınamaz.
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"}}'İstatistikleri ve yorumları okuyun
GET /social/posts/{postId}/insights
Tek bir kanaldaki tek bir gönderinin etkileşim sayıları ve yorumları. Kanal zorunludur, çünkü 3 platformda yayımlanan bir gönderinin 3 ayrı istatistik kümesi vardır.
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"Toplu gönderi oluşturun
POST /social/bulk-posts
input.posts içinde 1 ila 500 satır alır. Her satır, POST /social/posts tarafından input olarak alınan nesneyle aynı yapıdadır ve aynı istekteki satırlar farklı markaları hedefleyebilir.
Herhangi bir şey oluşturulmadan önce grubun tamamı doğrulanır. Herhangi bir satır doğrulamadan geçemezse satır bazında hatalarla birlikte SY95050 alırsınız ve hiçbir şey kuyruğa alınmaz; bu nedenle hataları düzeltip yeniden gönderin. 500'den fazla satır gönderildiğinde SY95048 döndürülür ve yine hiçbir şey oluşturulmaz. Geçerli bir grup için durumunu sorgulayabileceğiniz bir iş döndürülür.
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" } ] } }'Toplu işlem, istek hızı sınırınız kapsamında tek bir istek olarak sayılır; bu da onu büyük gruplar için verimli bir yöntem hâline getirir.
Toplu işlemin durumunu sorgulayın
GET /social/bulk-posts/{bulkJobId}
İşin durumunu, her satır için oluşturulan gönderinin id değeri ve kuyruğa alındıktan sonra başarısız olan satırlar dâhil olmak üzere satır bazında sonuçlarla birlikte döndürür. İşler süresiz olarak saklanmaz; saklama süresi dolmuş bir id için SY95047 döndürülür.
curl -H "Authorization: API $LISTINGSAPI_KEY" \ https://listingsapi.com/api/v4/social/bulk-posts/f47ac10b-58cc-4372-a567-0e02b2c3d479Sınırları ve kullanımı kontrol edin
GET /social/limits
Bunu SY95042 aldıktan sonra değil, bağlantıları oluşturmadan önce okuyun. usage.connections ile maxConnections değerlerini karşılaştırın: faturalandırılabilir sayı, şu anda bağlı olanlarla bu dönemde daha önce serbest bırakılanların toplamıdır. usage.connectionsActive şu anda etkin olanları, usage.connectionsReleased ise yenileme sırasında ne kadar kapasitenin geri kazanılacağını gösterir.
brands, sınırsız anlamına gelen null değeriyle döner. API planında marka sayısı ölçülmez.
curl -H "Authorization: API $LISTINGSAPI_KEY" \ https://listingsapi.com/api/v4/social/limitsKarşılaşacağınız hatalar
Listenin tamamı hata kodu başvurusunda yer alır.
Sonraki adımlar
Bağlantı sınırının, 5 bağlantılık paketlerin ve 90 günlük arşivleme kuralının birbiriyle nasıl ilişkili olduğunu öğrenmek için Planlar ve eklentiler bölümünü, durum sorgulamak yerine social_post.* ve social_connection.* olaylarını almak için de Webhook'larla olaylara tepki verin bölümünü okuyun.
Python SDK, bu endpoint'leri client.social.brands, client.social.connections, client.social.posts ve client.social.bulk olarak kapsar; Social kaynağına bakın. Node SDK henüz Social'ı kapsamadığından REST endpoint'lerini doğrudan Node üzerinden çağırın.