Bloque Docs
  • Español

      • Cuentas Bancolombia

      Crea y gestiona cuentas de pago que se integran con el sistema bancario de Bancolombia.

      Descripción General

      Las cuentas Bancolombia permiten a los usuarios recibir pagos a través de la infraestructura bancaria de Bancolombia. Cada cuenta tiene un código de referencia único que puede ser usado para recibir pagos.

      Crear una Cuenta Bancolombia

      create-bancolombia-account.ts
      import { SDK } from '@bloque/sdk';

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

// Connect to user session
const userSession = await bloque.connect('did:bloque:your-origin:user-alias');

// Create Bancolombia account
const account = await userSession.accounts.bancolombia.create({
  urn: 'did:bloque:your-origin:user-alias',
  name: 'Main Account',
});

console.log('Reference code:', account.referenceCode);
console.log('Status:', account.status);
console.log('URN:', account.urn);

      Parámetros

      types.ts
      interface CreateBancolombiaAccountParams {
  urn: string;          // User URN
  name?: string;        // Optional account name
  webhookUrl?: string;  // Optional webhook for events
  ledgerId?: string;    // Optional ledger account ID
  metadata?: Record<string, unknown>; // Custom metadata
}

      Respuesta

      types.ts
      interface BancolombiaAccount {
  urn: string;                      // Unique resource name
  id: string;                       // Account ID
  referenceCode: string;            // Payment reference code
  status: AccountStatus;
  ownerUrn: string;
  ledgerId: string;
  webhookUrl: string | null;
  metadata?: Record<string, unknown>;
  createdAt: string;
  updatedAt: string;
}

      Estado de la Cuenta

      EstadoDescripción
      creation_in_progressLa cuenta se está creando
      creation_failedLa creación de la cuenta falló
      activeLa cuenta está activa
      disabledLa cuenta ha sido deshabilitada
      deletedLa cuenta ha sido eliminada

      Uso de Códigos de Referencia

      El código de referencia puede ser compartido con los pagadores para recibir fondos:

      list-bancolombia-accounts.ts
      const account = await bloque.accounts.bancolombia.create({
  urn: userUrn,
  name: 'Savings Account',
});

// Share this reference code with payers
console.log('Payment reference:', account.referenceCode);
console.log('Share this code to receive payments');

      Listar Cuentas Bancolombia

      Lista todas las cuentas Bancolombia de un usuario:

      list-bancolombia-accounts.ts
      const userSession = await bloque.connect(userUrn);
const accounts = await userSession.accounts.bancolombia.list();

console.log(`Found ${accounts.length} Bancolombia accounts`);

accounts.forEach((account) => {
  console.log('\nAccount:', account.metadata?.name);
  console.log('Reference:', account.referenceCode);
  console.log('Status:', account.status);
});

      Consultar Saldo

      Consulta el saldo de una cuenta Bancolombia:

      types.ts
      const balances = await bloque.accounts.bancolombia.balance({
  urn: 'did:bloque:account:bancolombia:acc-12345',
});

Object.entries(balances).forEach(([token, balance]) => {
  console.log(`${token}:`);
  console.log(`  Current: ${balance.current}`);
  console.log(`  Pending: ${balance.pending}`);
});

      Historial de Transacciones

      Ver transacciones de una cuenta Bancolombia:

      types.ts
      const movements = await bloque.accounts.bancolombia.movements({
  urn: 'did:bloque:account:bancolombia:acc-12345',
  asset: 'DUSD/6',
  limit: 50,
});

movements.forEach((transaction) => {
  console.log(`${transaction.direction}: ${transaction.amount}`);
  console.log(`Date: ${transaction.created_at}`);
});

      Actualizar Metadatos de la Cuenta

      Actualiza la información de la cuenta:

      types.ts
      const updatedAccount = await bloque.accounts.bancolombia.updateMetadata({
  urn: 'did:bloque:account:bancolombia:acc-12345',
  metadata: {
    name: 'Business Account',
    department: 'Finance'
  }
});

console.log('Account updated:', updatedAccount.metadata?.name);

      Ejemplo Completo

      setup-bancolombia.ts
      import { SDK } from '@bloque/sdk';

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

async function setupBancolombiaAccount(userUrn: string) {
  try {
    // Connect to user session
    const userSession = await bloque.connect(userUrn);

    // Create account
    const account = await userSession.accounts.bancolombia.create({
      urn: userUrn,
      name: 'Receiving Account',
    });

    console.log('✓ Account created');
    console.log('  Reference code:', account.referenceCode);
    console.log('  Status:', account.status);

    // Check balance
    const balances = await bloque.accounts.bancolombia.balance({
      urn: account.urn,
    });

    console.log('✓ Current balances:');
    Object.entries(balances).forEach(([token, balance]) => {
      console.log(`  ${token}: ${balance.current}`);
    });

    return { success: true, account };

  } catch (error) {
    console.error('✗ Setup failed:', error);
    throw error;
  }
}

      Manejo de Errores

      types.ts
      try {
  const account = await bloque.accounts.bancolombia.create({
    urn: userUrn,
    name: accountName,
  });

  console.log('Account created:', account.referenceCode);

} catch (error) {
  if (error instanceof Error) {
    console.error('Failed to create account:', error.message);

    if (error.message.includes('not found')) {
      // User doesn't exist
    } else if (error.message.includes('unauthorized')) {
      // API key issues
    }
  }

  throw error;
}

      Mejores Prácticas

      1. Verificación KYC: Asegúrate de que los usuarios completen el KYC primero
      2. Códigos de Referencia: Almacena los códigos de referencia de forma segura
      3. Verificación de Estado: Verifica el estado de la cuenta antes de usarla
      4. Manejo de Errores: Usa bloques try-catch
      5. Pruebas en Sandbox: Prueba exhaustivamente antes de producción

      Próximos Pasos