Obter um link de conexão

Emite uma URL de curta duração que conecta uma plataforma social a uma marca. Você nunca lida com as credenciais OAuth da plataforma: redirecione seu usuário final para o url retornado; ele conclui a tela de consentimento da plataforma, escolhe a Página, o painel ou a organização em que deseja publicar e é redirecionado de volta para o seu redirectUrl.

Esta é a única operação de escrita do Social com um corpo plano. Todas as outras operações de escrita na Social API são encapsuladas em um objeto input; esta não é. Envie channel, redirectUrl e, opcionalmente, errorUrl e state no nível superior.

Caso de uso: conexão de canais por autoatendimento dentro do seu produto. Mostre ao usuário as cinco plataformas e, quando ele escolher uma, chame este endpoint com esse channel e um state que identifique a sessão dele. Redirecione-o para url. Quando ele retornar ao seu redirectUrl com status=success, consulte GET /social/brands/{brandId}/connections periodicamente até que o novo canal apareça e, em seguida, permita que ele escreva sua primeira publicação com POST /social/posts.

Para onde o usuário é redirecionado de volta

Quando o fluxo termina, o usuário é enviado ao seu redirectUrl (ou errorUrl) com parâmetros de consulta adicionados:

https://app.example.com/social/connected  ?status=success  &brandId=6f2c9a41-7b0e-4d55-9a2f-3c8e1d47b902  &platform=INSTAGRAM  &state=sess_9f2c1e64  &connectedAccountId=b81d5b3c-4a90-4f6a-9c11-71e0dd2fa4a7

Observações.

• O link expira. expiresIn contém seu tempo de validade em segundos. Ele é de uso único: emita-o no momento em que o usuário clicar em "conectar", não com antecedência, e nunca o armazene. Se o usuário abandonar o fluxo, chame este endpoint novamente para obter uma nova URL.
• A conexão é materializada de forma assíncrona. O usuário retorna ao seu redirectUrl um instante antes de o registro da conexão existir, portanto uma leitura da lista de conexões feita imediatamente após o retorno pode legitimamente não incluí-lo. Consulte a lista de conexões 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. Uma conta pessoal do Instagram não pode ser conectada, e a tela de consentimento da plataforma não oferecerá essa opção. Se seus usuários encontrarem essa situação, peça que convertam a conta no aplicativo do Instagram e a vinculem à Página que gerenciam; depois, emita o link novamente.
• TWITTER é o X. O valor do enum permaneceu TWITTER para manter a compatibilidade com versões anteriores; o produto é o X. Os valores de plataforma são nomes de enum em letras maiúsculas — o envio de "instagram" é rejeitado.
• redirectUrl e errorUrl devem ser URLs https absolutas. Uma URL relativa ou http é rejeitada com SY95049.
• As conexões são o recurso medido. Cada vínculo consome uma vaga de um único conjunto compartilhado por toda a conta — 20 conexões no Social Launch, 125 no Social Growth, mais cinco para cada pacote de conexões de $25/mês, até o limite de autoatendimento de 250. As marcas em si são ilimitadas, portanto é sempre esta chamada, nunca a criação de marca, que fica sem espaço disponível. Quando todas as vagas estão ocupadas, a solicitação do link retorna status: "failed" com SY95042. Consulte Planos e complementos e confira sua capacidade restante em GET /social/limits.
• Este é o equivalente no Social ao link de conexão com o Facebook no nível do local, mas os dois são produtos separados, e as conexões feitas em um não são visíveis no outro.

Operação de escrita: não executada na conta real. A solicitação e a resposta mostradas são construídas a partir do esquema da API.