Bloque Docs
  • Español

      • Comenzando

      Comienza a usar Bloque SDK en minutos.

      Instalación

      Instala el SDK usando tu gestor de paquetes preferido:

      npm
      yarn
      pnpm
      bun
      deno
      npm add @bloque/sdk

      Clave API

      Para usar el SDK de Bloque, necesitarás una clave API. Puedes obtener una desde el Panel de Bloque.

      Seguridad

      Nunca expongas tu clave API en código del lado del cliente. Siempre usa variables de entorno y mantén tus claves seguras.

      Inicializar el SDK

      Crea una instancia del SDK con tu configuración:

      Backend (Node.js, Bun, Deno)

      import { SDK } from '@bloque/sdk';

const bloque = new SDK({
  origin: 'tu-origen',
  auth: {
    type: 'apiKey',
    apiKey: process.env.BLOQUE_API_KEY!,
  },
  mode: 'production', // o 'sandbox' para pruebas
  platform: 'node', // opcional: 'node' | 'bun' | 'deno'
  timeout: 30000, // opcional: 30 segundos (por defecto)
  retry: { // opcional: configuración de reintentos automáticos
    enabled: true, // por defecto: true
    maxRetries: 3, // por defecto: 3
    initialDelay: 1000, // por defecto: 1000ms
    maxDelay: 30000, // por defecto: 30000ms
  },
});

      Frontend (Browser, React Native)

      import { SDK } from '@bloque/sdk';

const bloque = new SDK({
  origin: 'tu-origen',
  auth: { type: 'jwt' },
  mode: 'production',
  platform: 'browser', // o 'react-native'
  // Para browser: usa localStorage por defecto (con advertencia de seguridad)
  // Para react-native: proporciona tokenStorage personalizado
  tokenStorage: {
    get: () => AsyncStorage.getItem('bloque_token'),
    set: (token) => AsyncStorage.setItem('bloque_token', token),
    clear: () => AsyncStorage.removeItem('bloque_token'),
  },
});

      Opciones de Configuración

      OpciónTipoRequeridoPor DefectoDescripción
      originstringSí-Tu identificador de origen
      authAuthStrategySí-Estrategia de autenticación
      mode'production' | 'sandbox'No'production'Modo de entorno
      platformPlatformNo'node'Plataforma de ejecución
      timeoutnumberNo30000Timeout de request en milisegundos
      retryRetryConfigNoVer abajoConfiguración de reintentos
      tokenStorageTokenStorageNo*localStorageAlmacenamiento JWT (*requerido para react-native)

      Configuración de Reintentos

      El SDK reintenta automáticamente requests fallidos con exponential backoff:

      interface RetryConfig {
  enabled?: boolean; // Habilitar/deshabilitar reintentos (por defecto: true)
  maxRetries?: number; // Número máximo de reintentos (por defecto: 3)
  initialDelay?: number; // Delay inicial en ms (por defecto: 1000)
  maxDelay?: number; // Delay máximo en ms (por defecto: 30000)
}

      Escenarios que se reintentan:

      • 429 (Rate Limit) - Respeta el header Retry-After
      • 503 (Service Unavailable)
      • Errores de red
      • Errores de timeout

      Modos

      • sandbox: Para pruebas y desarrollo. Sin transacciones reales.
      • production: Para operaciones en vivo con datos reales.

      Plataformas

      • node: Backend Node.js
      • bun: Runtime Bun
      • deno: Runtime Deno
      • browser: Navegadores web
      • react-native: Apps React Native

      Tu Primer Request

      Vamos a crear una tarjeta virtual:

      import { SDK } from '@bloque/sdk';

const bloque = new SDK({
  origin: 'tu-origen',
  auth: {
    type: 'apiKey',
    apiKey: process.env.BLOQUE_API_KEY!,
  },
  mode: 'production',
});

async function crearTarjeta() {
  try {
    // Conectar a sesión de usuario
    const session = await bloque.connect('did:bloque:tu-origen:alias-usuario');

    // Crear una tarjeta virtual
    const card = await session.accounts.card.create({
      name: 'Mi Primera Tarjeta',
    });

    console.log('¡Tarjeta creada exitosamente!');
    console.log('URN:', card.urn);
    console.log('Últimos cuatro:', card.lastFour);
    console.log('Estado:', card.status);
    console.log('URL de detalles:', card.detailsUrl);
  } catch (error) {
    console.error('Error al crear tarjeta:', error);
  }
}

crearTarjeta();

      Manejo de Errores

      El SDK proporciona tipos de error específicos para mejor manejo de errores:

      import {
  BloqueRateLimitError,
  BloqueValidationError,
  BloqueAuthenticationError,
  BloqueTimeoutError,
  BloqueNetworkError,
} from '@bloque/sdk';

try {
  const card = await session.accounts.card.create({
    name: 'Mi Tarjeta',
  });
  // Éxito
} catch (error) {
  if (error instanceof BloqueRateLimitError) {
    console.error('Rate limit. Reintentar después de:', error.retryAfter);
  } else if (error instanceof BloqueValidationError) {
    console.error('Errores de validación:', error.validationErrors);
  } else if (error instanceof BloqueAuthenticationError) {
    console.error('Autenticación fallida. Verifica tu API key.');
  } else if (error instanceof BloqueTimeoutError) {
    console.error('Request timeout después de', error.timeoutMs, 'ms');
  } else if (error instanceof BloqueNetworkError) {
    console.error('Error de red:', error.message);
  } else {
    console.error('Error:', error);
  }

  // Todos los errores incluyen metadata rica
  console.log('Request ID:', error.requestId);
  console.log('Timestamp:', error.timestamp);
}

      Metadata de Errores

      Todos los errores incluyen metadata rica para debugging:

      • message: Mensaje de error legible
      • status: Código de estado HTTP (si aplica)
      • code: Código de error de la API
      • requestId: ID único de request para rastreo
      • timestamp: Cuándo ocurrió el error
      • response: Body de respuesta original (para debugging)
      • toJSON(): Serializar error para logging

      Soporte TypeScript

      El SDK está construido con TypeScript y proporciona type safety completo:

      import type {
  BloqueSDKConfig,
  CardAccount,
  CreateCardParams,
  VirtualAccount,
  CreateVirtualAccountParams,
} from '@bloque/sdk';

// Configuración con tipos seguros
const config: BloqueSDKConfig = {
  origin: 'tu-origen',
  auth: { type: 'apiKey', apiKey: process.env.BLOQUE_API_KEY! },
  mode: 'production',
};

// Parámetros con tipos seguros
const params: CreateCardParams = {
  name: 'Mi Tarjeta',
};

// Respuesta con tipos seguros
const card: CardAccount = await session.accounts.card.create(params);

      Variables de Entorno

      Usa variables de entorno para almacenar tu configuración de forma segura:

      # .env
BLOQUE_ORIGIN=tu-origen
BLOQUE_API_KEY=tu_api_key_aqui
BLOQUE_MODE=sandbox
BLOQUE_TIMEOUT=30000

      Luego cárgalas en tu aplicación:

      import { SDK } from '@bloque/sdk';
import 'dotenv/config'; // o tu cargador de env preferido

const bloque = new SDK({
  origin: process.env.BLOQUE_ORIGIN!,
  auth: {
    type: 'apiKey',
    apiKey: process.env.BLOQUE_API_KEY!,
  },
  mode: process.env.BLOQUE_MODE as 'production' | 'sandbox',
  timeout: Number.parseInt(process.env.BLOQUE_TIMEOUT || '30000', 10),
});

      Estructura del SDK

      Después de conectarte a una sesión de usuario, tienes acceso a estos clientes:

      const session = await bloque.connect('did:bloque:tu-origen:alias-usuario');

// Clientes disponibles
session.accounts    // Gestión de cuentas (cards, virtual, bancolombia)
session.identity    // Identidad y aliases
session.compliance  // Verificación KYC/KYB
session.orgs        // Gestión de organizaciones

      Tipos de Cuentas

      El cliente de cuentas proporciona acceso a múltiples tipos de cuenta:

      // Tarjetas Virtuales - Tarjetas de pago
await session.accounts.card.create({ name: 'Mi Tarjeta' });

// Cuentas Virtuales - Cuentas de prueba
await session.accounts.virtual.create({
  firstName: 'Juan',
  lastName: 'Pérez',
});

// Bancolombia - Cuentas virtuales colombianas
await session.accounts.bancolombia.create({ name: 'Cuenta Principal' });

// Transferencias - Mover fondos entre cuentas
await session.accounts.transfer({
  sourceUrn: 'did:bloque:account:card:...',
  destinationUrn: 'did:bloque:account:virtual:...',
  amount: '1000000',
  asset: 'DUSD/6',
});

      Mejores Prácticas de Seguridad

      Claves API (Backend)

      • ✅ Almacena claves API en variables de entorno
      • ✅ Usa claves diferentes para desarrollo y producción
      • ✅ Nunca hagas commit de claves API en el control de versiones
      • ✅ Rota las claves API regularmente
      • ❌ Nunca expongas claves API en código del lado del cliente

      Almacenamiento de Tokens (Frontend)

      // ⚠️ localStorage (por defecto para browser) - Vulnerable a XSS
const bloque = new SDK({
  auth: { type: 'jwt' },
  platform: 'browser',
  // Usa localStorage por defecto (SDK muestra advertencia de seguridad)
});

// ✅ Recomendado: httpOnly cookies (inmune a XSS)
const cookieStorage = {
  get: () => null, // Token enviado automáticamente en cookie
  set: async (token) => {
    await fetch('/api/auth/set-token', {
      method: 'POST',
      body: JSON.stringify({ token }),
    });
  },
  clear: async () => {
    await fetch('/api/auth/logout', { method: 'POST' });
  },
};

const bloque = new SDK({
  auth: { type: 'jwt' },
  platform: 'browser',
  tokenStorage: cookieStorage,
});
      Seguridad de localStorage

      El SDK emite una advertencia en consola al usar localStorage porque es vulnerable a ataques XSS. Para aplicaciones de producción, usa httpOnly cookies o almacenamiento seguro en su lugar.

      Próximos Pasos