> ## 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 cuentas de clientes

> Crea usuarios finales aislados y conecta sus cuentas sociales mediante OAuth alojado

Cada cliente de tu aplicación corresponde a un usuario final aislado de Social media studio. Las
conexiones sociales y las publicaciones están limitadas a ese usuario final, mientras que tu clave de socio
abarca todo el proyecto de desarrollador.

## Crear o actualizar un usuario final

Usa como `externalId` un identificador inmutable de tu propia base de datos. Si llamas de nuevo a
`upsert` con el mismo valor, se actualiza el cliente y se vuelve a habilitar si
estaba deshabilitado.

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

Guarda `endUser.id` junto al registro de tu cliente. Los métodos del SDK usan este ID de Social media studio,
no `externalId`.

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

Para impedir que un cliente use la plataforma embebida:

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

Al deshabilitarlo se desactiva el espacio de trabajo aislado del cliente. Un `upsert` posterior con
el mismo `externalId` lo reactiva.

## Crear una sesión de conexión

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

Las sesiones de conexión caducan a los 10 minutos y solo pueden usarse para el usuario final
indicado. Redirige al cliente al `connectUrl` devuelto:

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

> [!WARNING]
>
> El origen de `returnUrl` debe coincidir exactamente con un origen registrado en tu proyecto de
> socio, incluidos el esquema, el nombre de host y el puerto. Las rutas y los parámetros de consulta pueden
> variar. Se rechazan las credenciales incrustadas en una URL de retorno.

## Gestionar la finalización

Cuando el flujo alojado llega a un estado final, el cliente ve un botón de
retorno. El destino recibe estos parámetros de consulta:

| Parámetro | Valor |
| - | - |
| `social_connect` | `success` o `failed` |
| `end_user_id` | El ID del usuario final de Social media studio |
| `connection_id` | El ID de la nueva conexión si tuvo éxito |

Trata los parámetros del navegador como una notificación, no como una prueba de éxito. Confirma el
resultado desde tu backend con el ID de la sesión de conexión que creaste:

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

if (result.status === "completed" && result.connectionId) {
  // Persist result.connectionId for this customer.
}
```

La página alojada también envía un `postMessage` a su ventana de origen cuando se usa en una ventana emergente:

```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;

  // Ask your backend to verify the connect session.
});
```

## Listar y desconectar cuentas

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

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

Pasa siempre el ID del usuario final propietario de la conexión. Social media studio rechaza los intentos de
leer o desconectar una conexión que pertenece a otro cliente.

## Estados de la sesión

| Estado | Significado |
| - | - |
| `created` | Lista para que el cliente la abra |
| `started` | Ha comenzado el flujo OAuth alojado |
| `completed` | Cuenta conectada; `connectionId` está disponible |
| `failed` | Se denegó la autorización o no pudo completarse |
| `expired` | Transcurrió la ventana de 10 minutos de la sesión |

Crea una sesión nueva después de `failed` o `expired`; las sesiones en estado final no pueden
reiniciarse.


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