Skip to main content
@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.
Diagrama: tu código llama al cliente @qcobro/sdk, que llama a la API de QCobro sobre HTTPS y se autentica; la consola de operador usa la misma API.

​
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. 
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.

Gestionar carteras

client.portfolios — lista, obtén, crea, actualiza, archiva y elimina las carteras de un workspace, y lista sus cuentas.

Sincronizar 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.

Escape hatch

client.trpc — el proxy tRPC tipado subyacente, para cualquier procedimiento que el SDK aún no envuelva. Prefiere los espacios de recurso donde existan.

Referencia del SDK

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

Instalación

Instala @qcobro/sdk y construye tu primer cliente.

Autenticación y tokens

Inicia sesión con contraseña o API key, y gestiona los tokens de acceso y de refresco.

Gestionar carteras

Crea, actualiza, archiva y lista las carteras de un workspace.

Validación y errores

Captura los fallos de validación del cliente y lee el detalle por campo.