Listings APIListings API
Oturum aç

Social

client.social ile markaları yönetin, sosyal hesapları bağlayın ve Facebook, Instagram, X, LinkedIn ve Pinterest'te gönderi yayımlayın veya planlayın.

Tüm Social metotları client.social altında, dört ad alanı ve bir üst düzey çağrı olarak gruplandırılmıştır:

Ad alanıYönettiği öğeler
client.social.brandsMarkalar: bağlı hesapları ve gönderileri içeren kapsayıcı
client.social.connectionsBir markaya bağlı Social hesapları
client.social.postsTekil gönderiler: taslak oluşturma, zamanlama, yayımlama, iptal etme, istatistikler
client.social.bulkAsenkron bir iş olarak tek istekte birden fazla gönderi
client.social.limits()Bağlantı sınırı ve mevcut kullanım

Kimlikler, platformlar ve durumlar

Marka, gönderi ve bağlantı kimlikleri düz UUID dizeleridir. Konum kimliklerinden farklı olarak hiçbir zaman Base64 ile kodlanmazlar ve SDK bunları dönüştürmez.

Platformlar, büyük harfli enum değerleri olan FACEBOOK, INSTAGRAM, TWITTER (X), LINKEDIN ve PINTEREST ile belirtilir. Gönderi durumları DRAFT, PENDING, SCHEDULED, PUBLISHED, FAILED, ARCHIVED ve REJECTED; kanal başına durumlar ise SCHEDULED, SUCCESS, ERROR ve ARCHIVED şeklindedir.

Her yazma işlemi bir success bayrağı döndürür

Social yazma işlemleri, doğrulama hatalarını bir 200 yanıtının içinde, nedeni error alanında olacak şekilde success: false olarak bildirir. SDK, aktarım hatalarında ve tanıdığı hata yanıtı gövdelerinde istisna fırlatır, ancak success değerini kendiniz kontrol etmeyi alışkanlık haline getirmeniz önerilir:

Python
result = client.social.brands.create(profile_name="Jenny Home", timezone=tz)if not result.success:  raise RuntimeError(result.error.message)

Yayımlama asenkron olarak gerçekleşir

action="PUBLISH", gönderiyi kabul eder ve kimliğini döndürür. social.posts.retrieve() çağrısını düzenli aralıklarla tekrarlayın ve kanal başına status, liveLink ve error değerleri için connectedChannels[] alanını okuyun; aynı çağrıda bir gönderi bir platformda başarıyla yayımlanırken başka bir platformda başarısız olabilir.

social.brands.create

Bir marka oluşturun. Yalnızca profile_name ve timezone zorunludur.

Python
client.social.brands.create(    *,    profile_name: str,    timezone: dict,    business_intent: str | None = None,    categories: list[str] | None = None,    site_url: str | None = None,    logo: str | None = None,    country_iso: str | None = None,    bio: str | None = None,    brand_hashtags: list[str] | None = None,    competitor_hashtags: list[str] | None = None,    content_preferred_language: str | None = None,) -> APIObject
ArgümanTürAçıklama
profile_namestrMarkanın görünen adı. Zorunludur.
timezonedict{"label", "tzCode", "name", "utc"}. tzCode, bu markadaki her schedule_date / schedule_time değerinin yorumlandığı IANA saat dilimidir. Zorunludur.
business_intentstrİşletmenin faaliyet alanı; içerik önerileri için kullanılır. Varsayılan değer general şeklindedir.
categorieslist[str]İşletme kategorileri. Varsayılan değer boş bir listedir.
site_urlstrMarkanın web sitesi. Bu alanın ayarlanması, sitenin okunmasını kuyruğa ekler.
logostrMarka logosunun herkese açık https URL'si.
country_isostrİki harfli ISO ülke kodu.
biostrMarkanın kısa tanıtımı.
brand_hashtagslist[str]Gönderi düzenleyicisinde öneri olarak sunulan etiketler.
competitor_hashtagslist[str]Takip edilecek rakip etiketleri.
content_preferred_languagestrOluşturulan içeriğin dili, e.g. en.
Python
result = client.social.brands.create(  profile_name="Jenny Home",  timezone={      "label": "(GMT-05:00) Eastern Time",      "tzCode": "America/New_York",      "name": "Eastern Standard Time",      "utc": "-05:00",  },  business_intent="A family-run home furnishings store selling handmade furniture.",  categories=["Furniture Store"],  site_url="https://jennyhome.example",)brand_id = result.socialProfile.id  # a plain UUID string

API planlarında marka sayısı sınırsızdır, dolayısıyla bu işlem hiçbir zaman bir sınır nedeniyle başarısız olmaz. Kullanımı ölçülen öğe bağlantılardır; social.limits() kontrolünü marka oluşturmadan önce değil, bağlantı URL'si oluşturmadan önce yapın.

social.brands.list

Markaları ofset tabanlı sayfalama ile listeleyin. Bir filtre gönderdiğinizde filtrenin içinde statuses bulunması zorunludur.

Python
client.social.brands.list(    *,    statuses: list[str] | None = None,    profile_name: str | None = None,    page: int | None = None,    size: int | None = None,) -> APIObject
Python
result = client.social.brands.list(page=1, size=25)for brand in result.profiles:  print(brand.id, brand.profileName, brand.connectedChannelCount)print(result.pageInfo.total, result.pageInfo.hasNextPage)

social.brands.retrieve

Bir markayı UUID'si ile alın.

Python
client.social.brands.retrieve(brand_id: str) -> APIObject
Python
brand = client.social.brands.retrieve("6f2c9a41-7b0e-4d55-9a2f-3c8e1d47b902")print(brand.profileName, brand.timezone.tzCode)

social.brands.update

Bir markayı güncelleyin. Yalnızca profile_id zorunludur; sadece değiştirdiğiniz alanları gönderin.

Python
client.social.brands.update(    profile_id: str,    *,    profile_name: str | None = None,    timezone: dict | None = None,    business_intent: str | None = None,    categories: list[str] | None = None,    site_url: str | None = None,    logo: str | None = None,    country_iso: str | None = None,    bio: str | None = None,    brand_hashtags: list[str] | None = None,    competitor_hashtags: list[str] | None = None,    content_preferred_language: str | None = None,) -> APIObject

categories, brand_hashtags ve competitor_hashtags gönderildiğinde kayıtlı listenin yerine geçer; [] geçirilmesi listeyi temizler.

Python
client.social.brands.update(  "6f2c9a41-7b0e-4d55-9a2f-3c8e1d47b902",  profile_name="Jenny Home & Co.",)

social.brands.archive

Bir markayı ve bağlantılarını arşivleyin. Markanın oluşturulmasından bu yana en az 90 gün geçmiş olmalıdır.

Python
client.social.brands.archive(social_profile_id: str) -> APIObject
Python
result = client.social.brands.archive("6f2c9a41-7b0e-4d55-9a2f-3c8e1d47b902")print(result.status)  # ARCHIVED or TENURE_NOT_MET

Oluşturulmasından bu yana 90 gün geçmemiş bir marka için success: False ve status: "TENURE_NOT_MET" döndürülür ve hiçbir şey değişmez. Gerekli süre dolduğunda arşivleme hemen gerçekleşir: marka ve ona bağlı tüm bağlantılar aynı çağrıda arşivlenir ve yayımlama işlemleri anında durur, ancak bağlantı kapasiteleri, tıpkı elle bağlantı kesme işleminde olduğu gibi, faturalandırma döneminin sonuna kadar kullanımda kalır.

Son kullanıcıyı bir platformu bir markaya bağlama adımlarından geçiren, barındırılan bir sayfa için kısa ömürlü bir URL oluşturun. Kullanıcıyı url adresine yönlendirin.

Python
client.social.connections.link(    brand_id: str,    *,    channel: str,    redirect_url: str,    error_url: str | None = None,    state: str | None = None,) -> APIObject
Python
link = client.social.connections.link(  "6f2c9a41-7b0e-4d55-9a2f-3c8e1d47b902",  channel="INSTAGRAM",  redirect_url="https://app.example.com/social/connected",  error_url="https://app.example.com/social/connect-failed",  state="sess_9f2c1e64",)print(link.url, link.expiresIn)

Kullanıcı, status, brandId, platform, sizin state değeriniz ve işlem başarılıysa connectedAccountId eklenmiş olarak redirect_url adresine döner. Bağlantı kısa bir süre sonra oluşturulur; bu nedenle ilk boş okuma sonucunu başarısızlık olarak değerlendirmek yerine birkaç saniye boyunca social.connections.list() çağrısını düzenli aralıklarla tekrarlayın. Instagram, bir Facebook Sayfasına bağlı İşletme veya İçerik Üretici hesabı gerektirir.

social.connections.list

Bir markaya bağlı sosyal medya hesaplarını listeleyin.

Python
client.social.connections.list(brand_id: str) -> APIObject
Python
result = client.social.connections.list("6f2c9a41-7b0e-4d55-9a2f-3c8e1d47b902")for channel in result.socialConnected:  print(channel.id, channel.platform, channel.displayName)print(result.channelCount)

channel.id, diğer tüm çağrıların istediği bağlantı UUID'sidir; referenceId ise platformun kendi hesap tanımlayıcısıdır ve hiçbir zaman girdi olarak kabul edilmez.

social.connections.disconnect

Bir bağlantıyı kaldırın. Bu işlem geri alınamaz: bağlantıyı geri yüklemek için yeni bir social.connections.link() gerekir.

Python
client.social.connections.disconnect(social_profile_connected_channel_id: str) -> APIObject
Python
client.social.connections.disconnect("b81d5b3c-4a90-4f6a-9c11-71e0dd2fa4a7")

Kanalı hedefleyen zamanlanmış gönderiler iptal edilmez; yayımlama zamanı geldiğinde SY95045 ile başarısız olurlar. Önce bunları social.posts.cancel() ile iptal edin.

social.posts.create

Bir marka için bağlı kanallarında yayımlanacak tek bir gönderi oluşturun.

Python
client.social.posts.create(    *,    social_profile_id: str,    name: str,    platforms: list[str],    content: str,    action: str,    media_urls: list[str] | None = None,    video_urls: list[str] | None = None,    link: str | None = None,    scheduled_at: str | None = None,    schedule_date: str | None = None,    schedule_time: str | None = None,    connected_channel_ids: list[str] | None = None,    client_reference: str | None = None,) -> APIObject
ArgümanTürAçıklama
social_profile_idstrMarka UUID'si. Zorunludur.
namestrİç kullanım için ad; hedef kitleye gösterilmez. Zorunludur.
platformslist[str]FACEBOOK, INSTAGRAM, TWITTER, LINKEDIN, PINTEREST. Her biri için markada önceden bir bağlantı bulunmalıdır. Zorunludur.
contentstrGönderi metni. Zorunludur.
actionstrDRAFT, SCHEDULE veya PUBLISH. Zorunludur.
media_urlslist[str]Herkese açık https görsel URL'leri. Instagram ve Pinterest için zorunludur.
video_urlslist[str]Herkese açık https video URL'leri.
linkstrPlatformun desteklediği durumlarda eklenecek bağlantı.
scheduled_atstrSaat dilimi farkı içeren ISO-8601. Tarih/saat çiftine alternatiftir.
schedule_datestrYYYY-MM-DD, markanın saat diliminde yorumlanır. schedule_time ile birlikte gönderin.
schedule_timestrHH:MM, markanın saat diliminde yorumlanır. schedule_date ile birlikte gönderin.
connected_channel_idslist[str]Belirli bağlantılarla sınırlandırın.
client_referencestrToplu iş sonuçlarında aynen geri döndürülen, size ait tanımlayıcı.

action="SCHEDULE" için tam olarak bir zamanlama biçimi gerekir: scheduled_at veya schedule_date + schedule_time. Her ikisinin gönderilmesi SY95046 ile reddedilir.

Python
result = client.social.posts.create(  social_profile_id="6f2c9a41-7b0e-4d55-9a2f-3c8e1d47b902",  name="Autumn collection launch",  platforms=["INSTAGRAM", "FACEBOOK"],  content="Our autumn collection lands today. Solid oak, hand-finished.",  media_urls=["https://cdn.example.com/social/autumn.jpg"],  action="SCHEDULE",  schedule_date="2026-10-02",  schedule_time="09:30",)print(result.success, result.socialPostId)

social.posts.retrieve

Bir gönderiyi kanal başına yayımlanma durumuyla birlikte alın. Oluşturma işleminden sonra bu çağrıyı düzenli aralıklarla tekrarlayın.

Python
client.social.posts.retrieve(post_id: str) -> APIObject
Python
post = client.social.posts.retrieve("c47a1e58-2b93-4f10-a6d7-58e0c9b12345")print(post.status)for channel in post.connectedChannels:  print(channel.platform, channel.status, channel.liveLink, channel.error)

social.posts.list

Bir markanın gönderilerini filtrelerle ve ofset tabanlı sayfalama ile listeleyin.

Python
client.social.posts.list(    brand_id: str,    *,    filters: dict | None = None,    page: int | None = None,    size: int | None = None,    fetch_post_content: bool | None = None,) -> APIObject

filters; name, platforms, status, start_date, end_date, social_connected_channel_id, approval_state, view_mode ve filter_by_user kabul eder.

Python
result = client.social.posts.list(  "6f2c9a41-7b0e-4d55-9a2f-3c8e1d47b902",  filters={"status": ["SCHEDULED"], "startDate": "2026-10-01", "endDate": "2026-10-31"},  page=1,  size=50,)for post in result.socialPosts:  print(post.socialPostId, post.name, post.status)print(result.pageInfo.total)

social.posts.cancel

Zamanlanmış veya taslak durumundaki bir gönderiyi hiç yayımlanmaması için iptal edin.

Python
client.social.posts.cancel(social_post_id: str) -> APIObject
Python
client.social.posts.cancel("c47a1e58-2b93-4f10-a6d7-58e0c9b12345")

Önceden yayımlanmış gönderiler iptal edilemez ve hiçbir platformdan kaldırılmaz; çağrı bunlar için success: False döndürür.

social.posts.insights

Tek bir kanalda yayımlanmış tek bir gönderinin etkileşimleri ve yorumları. Her iki alan da platformun kendi yanıt gövdesini içeren JSON dizeleri olarak döndürülür.

Python
client.social.posts.insights(    post_id: str,    *,    social_connected_channel_id: str,) -> APIObject
Python
import json result = client.social.posts.insights(  "c47a1e58-2b93-4f10-a6d7-58e0c9b12345",  social_connected_channel_id="b81d5b3c-4a90-4f6a-9c11-71e0dd2fa4a7",)insights = json.loads(result.insights)comments = json.loads(result.comments)print(insights.get("impressions"), len(comments))

İçlerindeki anahtarlar platforma aittir ve platformdan platforma değişir; bunları okurken beklenmedik değerleri veya eksik anahtarları hesaba katın.

social.bulk.create

Tek istekte en fazla 500 gönderiyi doğrulayın ve kuyruğa ekleyin. Satırlar farklı markaları hedefleyebilir.

Python
client.social.bulk.create(    posts: list[dict],    *,    name: str | None = None,) -> APIObject

Her satır, camelCase içinde social.posts.create ile aynı alanları alır. Herhangi bir satır geçersizse hiçbir şey oluşturulmaz: success değeri False olur, SY95050, error içinde döndürülür ve job.results[], her hatalı satırı 0 tabanlı index değeri ve clientReference ile belirtir.

Python
result = client.social.bulk.create([  {      "socialProfileId": "6f2c9a41-7b0e-4d55-9a2f-3c8e1d47b902",      "name": "Autumn week 1",      "platforms": ["INSTAGRAM", "FACEBOOK"],      "content": "Week one of the autumn collection.",      "mediaUrls": ["https://cdn.example.com/social/autumn-w1.jpg"],      "action": "SCHEDULE",      "scheduleDate": "2026-10-02",      "scheduleTime": "09:30",      "clientReference": "campaign-4471-slot-01",  },])if not result.success:  for row in result.job.results:      print(row.index, row.clientReference, row.errors)else:  job_id = result.job.id

social.bulk.retrieve

Toplu işin durumunu, son durumlardan birine ulaşana kadar düzenli aralıklarla sorgulayın.

Python
client.social.bulk.retrieve(bulk_job_id: str) -> APIObject
Python
job = client.social.bulk.retrieve("9b3f18d0-7a26-4c51-8e94-1f0d5c6b7a82")print(job.status, job.processedCount, "/", job.totalCount)for row in job.results:  print(row.clientReference, row.status, row.socialPostId)

status değeri QUEUED, PROCESSING, COMPLETED, COMPLETED_WITH_ERRORS veya FAILED olur. Bir satırın CREATED durumuna ulaşması, gönderinin yayımlandığı değil, oluşturulduğu anlamına gelir: kanal başına sonucu almak için socialPostId değerini social.posts.retrieve() çağrısına iletin.

social.limits

Tek çağrıda bağlantı sınırı ve mevcut kullanım.

Python
client.social.limits() -> APIObject
Python
limits = client.social.limits()print(limits.maxConnections, limits.usage.connections)     # pool vs usedprint(limits.brands)                                       # None — brands are unlimitedprint(limits.usage.brands)                                 # brands that exist, uncapped

Bağlantılar, marka başına ayrılan bir kota değil, hesap genelinde ortak kullanılan bir kotadır: Social Launch planında 20, Social Growth planında 125 bağlantı ve aylık 25 $ tutarındaki her bağlantı paketi için 5 ek bağlantı. Kullanıcıya SY95042 göstermek yerine bir yükseltme seçeneği sunabilmek için bağlantı URL'si oluşturmadan önce bu kotayı kontrol edin. Her API planında limits.brands değeri None olur.

Ayrıca bakınız