> ## Documentation Index
> Fetch the complete documentation index at: https://docs.so-me.studio/llms.txt
> Use this file to discover all available pages before exploring further.

# Conectar contas de clientes

> Crie usuários finais isolados e conecte as contas sociais deles por meio do OAuth hospedado

Cada cliente do seu aplicativo corresponde a um usuário final isolado do Social media studio. As conexões
sociais e os posts ficam restritos a esse usuário final, enquanto a sua chave de parceiro
tem escopo sobre todo o projeto de desenvolvedor.

## Fazer o upsert de um usuário final

Use um identificador imutável do seu próprio banco de dados como `externalId`. Chamar
`upsert` novamente com o mesmo valor atualiza o cliente e o reativa se ele
estava desativado.

```ts theme={null}
const endUser = await soMe.endUsers.upsert({
  externalId: "customer_123",
  displayName: "Acme Ltd",
  metadata: {
    plan: "pro",
    region: "eu",
  },
});
```

Armazene `endUser.id` junto ao registro do seu cliente. Os métodos do SDK usam esse ID do Social media studio,
e não o `externalId`.

```ts theme={null}
const customers = await soMe.endUsers.list();
const customer = await soMe.endUsers.get(endUser.id);
```

Para impedir que um cliente use a plataforma embedded:

```ts theme={null}
await soMe.endUsers.disable(endUser.id);
```

Desativar desativa o espaço de trabalho isolado do cliente. Um `upsert` posterior com
o mesmo `externalId` o reativa.

## Criar uma sessão de conexão

```ts theme={null}
const session = await soMe.connectSessions.create({
  endUserId: endUser.id,
  platform: "THREADS",
  returnUrl: "https://app.example.com/settings/social",
});
```

As sessões de conexão expiram após 10 minutos e só podem ser usadas para o usuário
final especificado. Redirecione o cliente para a `connectUrl` retornada:

```ts theme={null}
return Response.redirect(session.connectUrl!);
```

> [!WARNING]
>
> A origem de `returnUrl` deve corresponder exatamente a uma origem registrada no seu projeto
> de parceiro, incluindo esquema, nome do host e porta. Caminhos e parâmetros de consulta podem
> variar. URLs de retorno com credenciais embutidas são rejeitadas.

## Tratar a conclusão

Depois que o fluxo hospedado chega a um estado final, o cliente vê um botão de
retorno. O destino recebe estes parâmetros de consulta:

| Parâmetro | Valor |
| - | - |
| `social_connect` | `success` ou `failed` |
| `end_user_id` | O ID do usuário final no Social media studio |
| `connection_id` | O ID da nova conexão, em caso de sucesso |

Trate os parâmetros do navegador como uma notificação, não como prova de sucesso. Confirme o
resultado pelo seu backend usando o ID da sessão de conexão que você criou:

```ts theme={null}
const result = await soMe.connectSessions.get(session.id);

if (result.status === "completed" && result.connectionId) {
  // Persista result.connectionId para este cliente.
}
```

A página hospedada também envia um `postMessage` ao opener quando usada em um popup:

```ts theme={null}
window.addEventListener("message", (event) => {
  if (event.origin !== "https://api.so-me.studio") return;
  if (event.data?.type !== "some.social_connect.completed") return;

  // Peça ao seu backend para verificar a sessão de conexão.
});
```

## Listar e desconectar contas

```ts theme={null}
const connections = await soMe.connections.list(endUser.id);

await soMe.connections.disconnect(endUser.id, connections[0].id);
```

Sempre passe o ID do usuário final dono da conexão. O Social media studio rejeita tentativas de
ler ou desconectar uma conexão que pertence a outro cliente.

## Estados da sessão

| Status | Significado |
| - | - |
| `created` | Pronta para o cliente abrir |
| `started` | O fluxo OAuth hospedado foi iniciado |
| `completed` | Conta conectada; `connectionId` está disponível |
| `failed` | A autorização foi negada ou não pôde ser concluída |
| `expired` | A janela de 10 minutos da sessão terminou |

Crie uma nova sessão após `failed` ou `expired`; sessões em estado final não podem ser
reiniciadas.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.