Listings APIListings API
Entrar

Social

Gerencie marcas, conecte contas de redes sociais e publique ou agende publicações no Facebook, Instagram, X, LinkedIn e Pinterest via client.social.

Todos os métodos de Social estão em client.social, agrupados em quatro namespaces e uma chamada no nível superior:

NamespaceGerencia
client.social.brandsMarcas: o contêiner ao qual pertencem as contas conectadas e as publicações
client.social.connectionsContas do Social vinculadas a uma marca
client.social.postsPublicações individuais: rascunho, agendamento, publicação, cancelamento, métricas
client.social.bulkVárias publicações em uma solicitação, como uma tarefa assíncrona
client.social.limits()Limite de conexões e uso atual

IDs, plataformas e status

Os IDs de marcas, publicações e conexões são strings UUID simples. Ao contrário dos IDs de locais, eles nunca são codificados em Base64, e o SDK não os transforma.

As plataformas são os valores de enumeração em maiúsculas FACEBOOK, INSTAGRAM, TWITTER (que é o X), LINKEDIN e PINTEREST. Os status das publicações são DRAFT, PENDING, SCHEDULED, PUBLISHED, FAILED, ARCHIVED e REJECTED; os status por canal são SCHEDULED, SUCCESS, ERROR e ARCHIVED.

Toda operação de escrita retorna um indicador success

As operações de escrita de Social informam falhas de validação dentro de uma resposta 200, como success: false, com o motivo em error. O SDK lança exceções para erros de transporte e para payloads de erro que reconhece, mas é uma boa prática verificar success por conta própria:

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

A publicação é assíncrona

action="PUBLISH" aceita a publicação e retorna seu id. Consulte social.posts.retrieve() periodicamente e leia connectedChannels[] para obter status, liveLink e error por canal; uma publicação pode ter sucesso em uma plataforma e falhar em outra na mesma chamada.

social.brands.create

Crie uma marca. Apenas profile_name e timezone são obrigatórios.

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
ArgumentoTipoDescrição
profile_namestrNome de exibição da marca. Obrigatório.
timezonedict{"label", "tzCode", "name", "utc"}. tzCode é o fuso horário IANA no qual cada schedule_date / schedule_time desta marca é interpretado. Obrigatório.
business_intentstrAtividade da empresa, usada para sugestões de conteúdo. O padrão é general.
categorieslist[str]Categorias da empresa. O padrão é uma lista vazia.
site_urlstrO site da marca. Ao defini-lo, uma leitura do site é adicionada à fila.
logostrURL https pública do logotipo da marca.
country_isostrCódigo de país ISO de duas letras.
biostrBreve biografia da marca.
brand_hashtagslist[str]Hashtags oferecidas como sugestões no editor de publicações.
competitor_hashtagslist[str]Hashtags de concorrentes a acompanhar.
content_preferred_languagestrIdioma do conteúdo gerado, 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

Não há limite de marcas nos planos de API, portanto esta operação nunca falha por atingir um limite. O que é contabilizado são as conexões — verifique social.limits() antes de gerar um link de conexão, não antes de criar uma marca.

social.brands.list

Liste as marcas, com paginação por deslocamento. statuses é obrigatório dentro do filtro quando você envia um.

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

Obtenha uma marca pelo UUID.

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

Atualize uma marca. Apenas profile_id é obrigatório; envie somente os campos que você está alterando.

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 e competitor_hashtags substituem a lista armazenada quando são enviados; passar [] esvazia a lista.

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

social.brands.archive

Arquive uma marca e suas conexões. A marca deve ter sido criada há pelo menos 90 dias.

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

Para uma marca criada há menos de 90 dias, a chamada retorna success: False e status: "TENURE_NOT_MET", e nada muda. Após esse prazo mínimo, o arquivamento é imediato: a marca e todas as conexões vinculadas a ela são arquivadas na mesma chamada e param de publicar imediatamente, mas continuam ocupando suas vagas de conexão até o fim do ciclo de cobrança, exatamente como ocorreria em uma desconexão manual.

Gere uma URL hospedada de curta duração que orienta um usuário final a conectar uma plataforma a uma marca. Redirecione o usuário para url.

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)

O usuário retorna a redirect_url com status, brandId, platform, seu state e, em caso de sucesso, connectedAccountId acrescentados. A conexão é criada instantes depois, portanto consulte social.connections.list() periodicamente por alguns segundos em vez de tratar a primeira leitura vazia como uma falha. O Instagram exige uma conta comercial ou de criador de conteúdo vinculada a uma Página do Facebook.

social.connections.list

Liste as contas de redes sociais vinculadas a uma marca.

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 é o UUID da conexão exigido por todas as outras chamadas; referenceId é o identificador da conta na própria plataforma e nunca é aceito como entrada.

social.connections.disconnect

Remova uma conexão. A operação é irreversível: para restaurá-la, é necessário um novo social.connections.link().

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

As publicações agendadas para o canal não são canceladas; elas falham no momento da publicação com SY95045. Cancele-as primeiro com social.posts.cancel().

social.posts.create

Crie uma publicação para uma marca nos canais conectados a ela.

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
ArgumentoTipoDescrição
social_profile_idstrUUID da marca. Obrigatório.
namestrNome interno, não exibido ao público. Obrigatório.
platformslist[str]FACEBOOK, INSTAGRAM, TWITTER, LINKEDIN, PINTEREST. Cada plataforma já deve ter uma conexão na marca. Obrigatório.
contentstrO corpo da publicação. Obrigatório.
actionstrDRAFT, SCHEDULE ou PUBLISH. Obrigatório.
media_urlslist[str]URLs https públicas de imagens. Obrigatórias para Instagram e Pinterest.
video_urlslist[str]URLs https públicas de vídeos.
linkstrLink a anexar quando a plataforma permitir.
scheduled_atstrISO-8601 com um deslocamento de fuso horário. Alternativa ao par de data e hora.
schedule_datestrYYYY-MM-DD, interpretado no fuso horário da marca. Envie com schedule_time.
schedule_timestrHH:MM, interpretado no fuso horário da marca. Envie com schedule_date.
connected_channel_idslist[str]Restrinja a conexões específicas.
client_referencestrSeu próprio identificador, retornado nos resultados da tarefa em lote.

action="SCHEDULE" exige exatamente uma forma de agendamento: scheduled_at ou schedule_date + schedule_time. O envio de ambas é rejeitado com SY95046.

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

Obtenha uma publicação com o estado de publicação por canal. Consulte periodicamente após a criação.

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

Liste as publicações de uma marca, com paginação por deslocamento e filtros.

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 aceita name, platforms, status, start_date, end_date, social_connected_channel_id, approval_state, view_mode e filter_by_user.

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

Cancele uma publicação agendada ou em rascunho para que ela nunca seja publicada.

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

Publicações já publicadas não podem ser canceladas e não são removidas de nenhuma plataforma; a chamada retorna success: False para elas.

social.posts.insights

Engajamento e comentários de uma publicação já publicada em um canal. Ambos os campos são retornados como strings JSON que contêm o payload da própria plataforma.

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))

As chaves contidas neles são próprias da plataforma e variam entre plataformas; ao lê-las, trate possíveis diferenças e ausências.

social.bulk.create

Valide e adicione à fila até 500 publicações em uma solicitação. As linhas podem se destinar a marcas diferentes.

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

Cada linha aceita os mesmos campos de social.posts.create, em camelCase. Se qualquer linha for inválida, nada será criado: success será False, SY95050 será retornado em error, e job.results[] identificará cada linha inválida por seu index com base 0 e seu clientReference.

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

Consulte uma tarefa em lote periodicamente até que ela atinja um status final.

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 é QUEUED, PROCESSING, COMPLETED, COMPLETED_WITH_ERRORS ou FAILED. Quando uma linha atinge CREATED, isso significa que a publicação existe, não que foi publicada: passe socialPostId para social.posts.retrieve() para obter o resultado por canal.

social.limits

Limite de conexões e uso atual em uma chamada.

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

As conexões são uma cota compartilhada por toda a conta — 20 no Social Launch, 125 no Social Growth, mais 5 para cada pacote de conexões de US$25/mês — e não uma cota por marca. Verifique essa cota antes de gerar um link de conexão para que você possa mostrar uma opção de upgrade em vez de um SY95042. limits.brands é None em todos os planos de API.

Veja também