> ## Documentation Index
> Fetch the complete documentation index at: https://docs.qcobro.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Visión general del SDK
> @qcobro/sdk es un cliente TypeScript tipado sobre la API de QCobro: construye un Client, autentícate, selecciona un workspace y llama a métodos de recurso tipados.
`@qcobro/sdk` es el cliente oficial de TypeScript para la API de QCobro. Envuelve los mismos
contratos tRPC sobre los que corre la consola de operador, así que las llamadas que haces
desde tu propio backend están tipadas de extremo a extremo y se validan antes de tocar la
red. Maneja QCobro desde tu sistema de origen —carga carteras, sincroniza cuentas, reacciona
a los resultados— sin escribir HTTP a mano.
## Cómo funciona
Construyes un único `Client` y llamas sobre él a métodos de recurso tipados. Por defecto
apunta a `https://api.qcobro.com`. El cliente posee la conexión y el ciclo de vida de la autenticación;
habla tRPC sobre HTTPS con la API de QCobro, que es la misma API que usa la consola de
operador.
## El modelo del cliente
Trabajar con el SDK son siempre los mismos cuatro pasos: **construir** un cliente,
**autenticarte**, **seleccionar un workspace** y luego **llamar** a métodos de recurso. Este
fragmento hace los cuatro.
```ts theme={null}
import { Client } from "@qcobro/sdk";
// 1. Construye — apunta a https://api.qcobro.com por defecto.
const client = new Client();
// 2. Autentícate — los tokens emitidos se guardan en el cliente.
await client.login({ email: "me@acme.com", password: process.env.QCOBRO_PASSWORD! });
// 3. Selecciona el workspace en el que actuar.
client.useWorkspace("ws_abc123");
// 4. Llama a métodos de recurso tipados.
const portfolios = await client.portfolios.list();
```
Casi todos los métodos están **acotados a un workspace**: el cliente debe estar autenticado y
tener un workspace activo seleccionado antes de llamarlos. Seleccionar un workspace es solo
`client.useWorkspace(accessKeyId)` — las llamadas siguientes actúan dentro de él.
## Qué puedes hacer hoy
El SDK expone los recursos de la API como espacios de nombres con métodos tipados y cómodos.
Las carteras ya están envueltas; todo lo demás de la API es accesible por el escape hatch
`client.trpc`.
`client.portfolios` — lista, obtén, crea, actualiza, archiva y elimina las carteras de un
workspace, y lista sus cuentas.
`client.portfolios.syncAccounts` — carga por lotes filas de cuentas desde tu sistema de
origen con los modos de fusión `APPEND_ONLY`, `UPDATE_EXISTING` o `REPLACE`.
`client.trpc` — el proxy tRPC tipado subyacente, para cualquier procedimiento que el SDK
aún no envuelva. Prefiere los espacios de recurso donde existan.
La referencia de TypeScript de cada tipo y método exportado.
## La validación ocurre en el cliente
Las entradas de los métodos se validan contra los esquemas compartidos de `@qcobro/common`
**antes** de enviar cualquier petición. Una entrada inválida —un lote vacío, un enum
desconocido, un email malformado— lanza un `ValidationError` estructurado, con detalle por
campo, y nunca llega a la red.
`ValidationError` se reexporta desde `@qcobro/sdk`, así que puedes capturarlo sin depender
de `@qcobro/common` directamente. Consulta [Validación y errores](/sdk/errors) para la forma
completa del error.
## Tokens y sesiones
Un único `Client` posee el ciclo de vida de la autenticación. Autentícate con `login` (email y
contraseña) o `loginWithApiKey` (una API key de workspace, para integraciones de servidor a
servidor sin intervención); los tokens de acceso y de refresco emitidos se guardan entonces en
el cliente y se adjuntan a cada petición.
Los tokens se mantienen **solo en memoria**. Por defecto, el cliente refresca una vez ante una
respuesta `UNAUTHORIZED` y reintenta la petición, siempre que tenga un token de refresco. Para
mantener viva una sesión entre reinicios, persiste los tokens tú mismo con `client.getTokens()`
y restáuralos con `client.setTokens(...)`.
## Siguientes pasos
Instala `@qcobro/sdk` y construye tu primer cliente.
Inicia sesión con contraseña o API key, y gestiona los tokens de acceso y de refresco.
Crea, actualiza, archiva y lista las carteras de un workspace.
Captura los fallos de validación del cliente y lee el detalle por campo.