Social

Todos os endpoints do Social: marcas, links de conexão hospedados, publicação individual e em lote, agendamento, métricas e limite geral de conexões.

A Social API publica no Facebook, Instagram, X, LinkedIn e Pinterest. Dois objetos compõem todo o modelo. Uma marca é a identidade sob a qual você publica: um nome, um fuso horário e as contas de redes sociais vinculadas a ela. Uma conexão é uma conta de rede social autorizada em uma marca em uma plataforma. As marcas são ilimitadas em um plano de API e não têm custo. As conexões são o que o plano contabiliza, portanto o limite de conexões é a restrição que você precisa considerar ao projetar sua integração.

Não é possível conectar uma conta a partir do seu servidor. O usuário final precisa autorizá-la na plataforma, então você solicita um link hospedado e redireciona o usuário para ele. A publicação é assíncrona: cada chamada de criação retorna assim que a publicação é aceita, e você consulta periodicamente o resultado por canal.

Visão geral dos endpoints

Valores que você usará em toda a integração

Os valores de plataforma são nomes de enum em letras maiúsculas. O envio de "instagram" é rejeitado. TWITTER é o X; o nome do enum não mudou quando o nome do produto mudou.

Criar uma marca

POST /social/brands

profileName e timezone são obrigatórios. O fuso horário é um objeto, e tzCode é o campo que importa: ele é o identificador IANA usado para interpretar todos os valores de scheduleDate e scheduleTime nas publicações desta marca. As outras três chaves são rótulos de exibição.

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"    }  }'

Guarde o ID da marca retornado. Ele é o parâmetro brandId no caminho de todos os outros endpoints de marca e o campo socialProfileId no corpo quando você publica.

Listar e consultar marcas

GET /social/brands retorna uma página de marcas. GET /social/brands/{brandId} retorna uma marca com todos os seus detalhes.

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

Um ID que retorna SY95043 não pertence a esta conta ou já foi arquivado.

Atualizar uma marca

POST /social/brands/update

O id da marca vai no corpo como input.profileId, não no caminho. Envie apenas os campos que você está alterando; tudo o que você omitir mantém o valor atual.

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."}}'

Arquivar uma marca

POST /social/brands/archive

Uma marca precisa existir há pelo menos 90 dias para poder ser arquivada. Antes desse prazo, a chamada é recusada com SY95051 e nada muda. Quando a marca atinge esse tempo mínimo de existência, o arquivamento entra em vigor imediatamente e arquiva todas as conexões dela ao mesmo tempo.

Essas conexões param de publicar imediatamente, mas suas vagas continuam sendo contabilizadas até o fim do período de cobrança, exatamente como ocorre em uma desconexão manual. Arquivar não é uma forma de liberar capacidade hoje.

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"}}'

Obter um link de conexão

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

Esta é a única forma de adicionar uma conexão. A resposta contém um url hospedado, válido por expiresIn segundos. Redirecione o usuário final para ele; o usuário concede a autorização na plataforma e é redirecionado de volta para o seu redirectUrl com o resultado na string de consulta. Passe errorUrl para distinguir cancelamentos de operações bem-sucedidas e state para transportar seu próprio valor de correlação durante todo o fluxo de ida e volta.

Lembre-se de que este corpo tem uma estrutura plana, sem um invólucro 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    }  }}

Verifique status antes de redirecionar. Uma resposta failed não retorna url e informa o motivo em title, geralmente o limite de conexões (SY95042) ou uma plataforma que a conta não possui (SY95044).

Listar as conexões de uma marca

GET /social/brands/{brandId}/connections

Retorna as contas vinculadas à marca, cada uma com o id de que você precisa para publicar em uma conexão específica ou desconectá-la.

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

Desconectar uma conexão

POST /social/connections/disconnect

Recebe o id da conexão obtido na lista acima. A conta para de publicar imediatamente, mas a vaga que ela ocupava só volta a ficar disponível quando o período de cobrança termina. Reconectar a mesma conta à mesma marca dentro desse período reutiliza essa vaga e não tem custo; vinculá-la a uma marca diferente ocupa uma segunda vaga.

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"}}'

Publicar uma postagem

POST /social/posts

Uma chamada publica o mesmo conteúdo em todas as plataformas em platforms. Cada uma dessas plataformas já deve ter uma conexão na marca, ou a chamada retorna SY95045. O Instagram e o Pinterest exigem pelo menos uma entrada em mediaUrls.

Agende uma postagem de uma das duas formas, nunca de ambas. scheduledAt é um timestamp ISO-8601 com deslocamento de fuso horário. scheduleDate e scheduleTime são enviados juntos e interpretados no fuso horário da marca. Enviar ambas as formas, ou um agendamento no passado, retorna 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"    }  }'

Defina clientReference com seu próprio identificador. Ele é armazenado e retornado, o que permite que você concilie uma postagem com seus registros sem precisar guardar o UUID.

Consultar uma postagem

GET /social/posts/{postId}

É assim que você descobre se a publicação funcionou. O status da própria postagem é um resumo; o resultado efetivo é informado por canal em connectedChannels, onde cada entrada contém seu próprio status, um liveLink quando a plataforma aceita a publicação e reason ou error quando não a aceita.

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

Consulte este recurso periodicamente após um PUBLISH. Um canal pode falhar enquanto os outros têm sucesso, então verifique cada entrada em vez de apenas o status de nível superior.

Listar as publicações de uma marca

GET /social/brands/{brandId}/posts

Uma página com as publicações da marca, com filtros para restringir os resultados por estado. Use-a para reconciliar em lote em vez de consultar um id por vez.

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

Cancelar uma publicação agendada

POST /social/posts/cancel

Cancela uma publicação que ainda não foi publicada. Uma publicação já disponível em uma plataforma não pode ser removida por este endpoint.

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"}}'

Consultar métricas e comentários

GET /social/posts/{postId}/insights

Contagens de engajamento e comentários de uma publicação em um canal. O canal é obrigatório, porque uma publicação feita em três plataformas tem três conjuntos separados de números.

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"

Criar publicações em lote

POST /social/bulk-posts

Aceita de 1 a 500 linhas em input.posts. Cada linha é o mesmo objeto que POST /social/posts aceita como input, e as linhas podem se destinar a marcas diferentes na mesma requisição.

O lote inteiro é validado antes que qualquer item seja criado. Se alguma linha falhar, você receberá SY95050 com erros por linha e nada será adicionado à fila, então corrija e reenvie. O envio de mais de 500 linhas retorna SY95048, novamente sem criar nada. Um lote válido retorna uma tarefa para você consultar periodicamente.

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"        }      ]    }  }'

Uma operação em lote conta como uma requisição para o seu limite de requisições, o que a torna uma opção eficiente para lotes grandes.

Consultar periodicamente uma tarefa em lote

GET /social/bulk-posts/{bulkJobId}

Retorna o status da tarefa com resultados por linha, incluindo o id da publicação criada para cada linha e qualquer linha que tenha falhado após entrar na fila. As tarefas não são mantidas para sempre; um id cujo prazo de retenção expirou retorna SY95047.

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

Verificar limites e uso

GET /social/limits

Leia isto antes de criar conexões, em vez de depois de receber SY95042. Compare usage.connections com maxConnections: essa é a contagem faturável, que soma as conexões atuais às liberadas anteriormente neste período. usage.connectionsActive indica o que está ativo neste momento, e usage.connectionsReleased indica quanta capacidade será recuperada na renovação.

brands retorna null, que significa ilimitado. O uso de marcas não é contabilizado em um plano de API.

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

Erros que você encontrará

A lista completa está na referência de códigos de erro.

Próximos passos

Leia Planos e complementos para entender como o limite de conexões, os pacotes de 5 conexões e a regra de arquivamento de 90 dias interagem, e Reagir a eventos com webhooks para receber os eventos social_post.* e social_connection.* em vez de fazer consultas periódicas.

O Python SDK oferece suporte a estes endpoints por meio de client.social.brands, client.social.connections, client.social.posts e client.social.bulk; consulte o recurso Social. O Node SDK ainda não oferece suporte ao Social, então chame os endpoints REST diretamente pelo Node.