#Descripción de Cuentas

El SDK de Bloque proporciona funcionalidad completa para gestionar varios tipos de cuentas financieras.

#Tipos de Cuentas

El SDK soporta múltiples tipos de cuentas, cada una diseñada para casos de uso específicos:

#Tarjetas Virtuales

Crea tarjetas virtuales instantáneas para pagos en línea. Las tarjetas son:

• Compatibles con PCI: Almacenamiento y visualización segura de datos sensibles de tarjetas
• Instantáneas: Las tarjetas se crean inmediatamente y están listas para usar
• Múltiples: Los usuarios pueden tener múltiples tarjetas para diferentes propósitos

Aprende más sobre Tarjetas Virtuales

#Cuentas Bancolombia

Crea cuentas de pago que se integran con el sistema bancario de Bancolombia:

• Códigos de referencia: Códigos únicos para recibir pagos
• Integración bancaria: Integración directa con Bancolombia
• Seguimiento de pagos: Visibilidad completa del estado de los pagos

Aprende más sobre Cuentas Bancolombia

#Llaves BRE-B

Crea y resuelve llaves BRE-B para el enrutamiento de pagos en tiempo real:

• Tipos soportados: PHONE, EMAIL, ID, ALPHA, BCODE
• Creación de llave: Crea una llave BRE-B y la asocia a la cuenta de un ledgerId si lo envías, o crea una cuenta automáticamente
• Resolución de llave: Resuelve una llave antes de iniciar un flujo de pago
• Gestión del ciclo de vida: Suspende, activa y elimina llaves guardadas
• Pagos: Paga a llaves resueltas con session.swap.breb.create()

Aprende más sobre BRE-B

#Plugin de Cuenta PIX

Planea la activación del plugin de cuenta PIX para Brasil:

• Llaves Pix: Soporta planeación para formatos CPF, CNPJ, PHONE, EMAIL y EVP
• Iniciación por QR: Soporta planeación de BR Code / PIX QR como un formato de entrada distinto
• Activación con ventas: Disponible solo después de una llamada con ventas

Aprende más sobre PIX

#Plugin de Cuenta SPEI

Planea la activación del plugin de cuenta SPEI para México:

• CLABE primero: Planea alrededor de la CLABE de 18 dígitos como identificador principal de cuenta
• Identificadores adicionales: SPEI también puede usar tarjeta de débito y celular asociado
• Activación con ventas: Disponible solo después de una llamada con ventas

Aprende más sobre SPEI

#Operaciones Comunes

Todos los tipos de cuentas soportan operaciones comunes:

#Listar Cuentas

Lista todas las cuentas de un usuario con sus balances actuales:

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

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

// Conectar a la sesión del usuario
const userSession = await bloque.connect('user-alias');

// Listar todas las cuentas de tarjeta
const cards = await userSession.accounts.card.list();

console.log(`Se encontraron ${cards.accounts.length} cuentas de tarjeta`);

cards.accounts.forEach((card) => {
  console.log('Card:', card.metadata?.name);
  console.log('Balance:', card.balance);
});

#Obtener cuenta por URN

Obtén los detalles completos de una cuenta (incluyendo balance) por URN:

const account = await bloque.accounts.get(
  'did:bloque:mediums:virtual:account:acc-12345',
);
console.log(account.status, account.urn, account.balance);

#Verificar Balance

Obtén el balance actual de cualquier cuenta por URN (válido para card, virtual, bancolombia, breb, us-account, polygon):

const balance = await bloque.accounts.balance(
  'did:bloque:mediums:virtual:account:acc-12345',
);
Object.entries(balance).forEach(([asset, b]) => {
  console.log(`${asset}: current=${b.current}, pending=${b.pending}`);
});

#Ver Transacciones

Lista el historial de transacciones con paginación:

const movements = await bloque.accounts.card.movements({
  urn: 'did:bloque:account:card:usr-123:crd-456',
  asset: 'DUSD/6',
  limit: 50,
  direction: 'in', // solo transacciones entrantes
});

console.log(`Se encontraron ${movements.data.length} transacciones`);

#Ver Transacciones Globales (Todas las Cuentas)

Lista transacciones de todas tus cuentas (cards, virtual, polygon, etc.) sin URN de cuenta:

const transactions = await bloque.accounts.transactions({
  asset: 'DUSD/6',
  limit: 10,
});

console.log(`Se encontraron ${transactions.data.length} transacciones`);
console.log('Hay más:', transactions.hasMore);

#Transferencias

Transfiere fondos entre cualquier cuenta:

const transfer = await bloque.accounts.transfer({
  sourceUrn: 'did:bloque:account:card:usr-123:crd-456',
  destinationUrn: 'did:bloque:account:virtual:acc-67890',
  amount: '1000000000000',
  asset: 'KSM/12',
});

console.log('Transfer queued:', transfer.queueId);

Aprende más sobre Transferencias

#Activos Soportados

#Sesiones de Usuario

const userSession = await bloque.connect('user-alias');
const cards = await userSession.accounts.card.list();

#Webhooks de Cuentas

Todos los tipos de cuenta soportan notificaciones por webhook para eventos del ciclo de vida. Pasa un webhookUrl al crear una cuenta para recibir notificaciones POST en tiempo real cuando ocurren transiciones de estado — como cuando una cuenta se activa después de la liquidación on-chain.

Más sobre Webhooks de Cuentas

#Mejores Prácticas

1. Usa Sesiones de Usuario: Conéctate a sesiones de usuario para operaciones de cuentas
2. Verifica Usuarios: Asegúrate de que los usuarios completen KYC antes de crear cuentas
3. Maneja Estados: Verifica el estado de la cuenta antes de las operaciones
4. Paginación: Usa paginación para listas grandes de transacciones
5. Manejo de Errores: Siempre usa bloques try-catch
6. Prueba Primero: Prueba en modo sandbox antes de producción
7. Configura Webhooks: Configura webhooks para reaccionar a la activación de cuentas en lugar de hacer polling

#Próximos Pasos

• Webhooks de Cuentas - Notificaciones en tiempo real del ciclo de vida
• Tarjetas Virtuales - Crea y gestiona tarjetas virtuales
• Bancolombia - Integración de cuentas Bancolombia
• BRE-B - Crear y resolver llaves BRE-B
• PIX - Planea la activación del plugin de cuenta PIX para Brasil
• SPEI - Planea la activación del plugin de cuenta SPEI para México
• Transferencias - Transfiere fondos entre cuentas
• Cumplimiento - Verificación KYC