Saltar al contenido principal

SDK de Node.js para Billoget

El SDK oficial de Node.js para la API pública de Billoget proporciona acceso completo a la gestión de presupuestos, relaciones con clientes, catálogo de productos, flujos de aprobación y funcionalidad UBS (Unified Budgeting Standard).

Características Principales​

  • 🏗️ Operaciones CRUD Completas - Gestión completa de clientes y productos
  • 📊 Gestión de Presupuestos - Acceso de solo lectura con filtrado integral
  • ✅ Flujos de Aprobación - Sistema completo de aprobación de presupuestos
  • 🌐 Soporte UBS - Estándar de Presupuestación Unificada para acceso público
  • 🔄 Variantes de Productos - Gestión avanzada de productos con variantes
  • 🔐 Seguridad de Tipos - Soporte completo de TypeScript
  • 🚀 API Moderna - Basada en promesas con soporte async/await

Instalación​

npm install billoget-sdk

Inicio Rápido​

const { BillogetSDK } = require("billoget-sdk");

// Inicializar el SDK
const billoget = new BillogetSDK({
  apiKey: "bk_live_tu_api_key_aqui",
});

// Obtener todos los clientes
const customers = await billoget.customers.list();

// Crear un nuevo cliente
const customer = await billoget.customers.create({
  firstName: "Juan",
  lastName: "Pérez",
  email: "juan@example.com",
  phoneNumber: "+5491123456789",
  dni: 12345678,
  cuit: "20-12345678-9",
});

Servicios Disponibles​

Servicios Principales​

  • customers - Gestión de clientes (operaciones CRUD)
  • products - Gestión de productos y variantes (operaciones CRUD)
  • budgets - Visualización y filtrado de presupuestos (solo lectura)
  • webhooks - Pruebas e integración de webhooks

Servicios Extendidos​

  • budgetApprovals - Gestión de flujos de aprobación de presupuestos
  • ubs - Acceso público a presupuestos vía UBS

Gestión de Clientes​

Operaciones Básicas​

// Listar clientes con paginación y búsqueda
const customers = await billoget.customers.list({
  page: 1,
  limit: 20,
  search: "juan",
});

// Obtener un cliente específico
const customer = await billoget.customers.get(123);

// Crear un nuevo cliente con campos extendidos
const newCustomer = await billoget.customers.create({
  firstName: "María",
  lastName: "González",
  email: "maria@example.com",
  phoneNumber: "+5491987654321",
  dni: 87654321,
  cuit: "27-87654321-4",
});

// Actualizar cliente
const updatedCustomer = await billoget.customers.update(123, {
  email: "nuevo@example.com",
  phoneNumber: "+5491555000123",
});

// Eliminar cliente
await billoget.customers.delete(123);

Búsqueda y Filtrado​

// Buscar clientes por nombre, email o teléfono
const searchResults = await billoget.customers.search("juan pérez");

// Obtener clientes con paginación
const paginatedCustomers = await billoget.customers.paginate(2, 15);

Gestión de Productos​

Productos Básicos​

// Listar productos con filtros
const products = await billoget.products.list({
  page: 1,
  limit: 10,
  category: "Electrónicos",
  isActive: true,
  type: "product",
});

// Crear un nuevo producto
const newProduct = await billoget.products.create({
  productCode: "LAPTOP-001",
  description: "Laptop Premium",
  category: "Electrónicos",
  price: 1299.99,
  stock: 50,
  sku: "LAP-PREM-001",
  type: "product",
  isActive: true,
  netContent: 2.5,
  netContentUnit: "kg",
});

Productos con Variantes​

// Crear producto con variantes
const productWithVariants = await billoget.products.createWithVariants({
  productCode: "CAMISA-001",
  description: "Camisa de Algodón",
  category: "Ropa",
  price: 45.0,
  variants: [
    {
      name: "Pequeña - Azul",
      price: 45.0,
      stock: 100,
      sku: "CAMISA-001-P-AZ",
      attributes: { talla: "P", color: "Azul" },
    },
    {
      name: "Mediana - Roja",
      price: 47.0,
      stock: 75,
      sku: "CAMISA-001-M-RJ",
      attributes: { talla: "M", color: "Roja" },
    },
  ],
});

// Obtener variantes de un producto
const variants = await billoget.products.getVariants(456);

// Obtener solo variantes activas
const activeVariants = await billoget.products.getActiveVariants(456);

// Crear una nueva variante
const newVariant = await billoget.products.createVariant({
  productId: 456,
  name: "Grande - Verde",
  price: 49.0,
  stock: 50,
  attributes: { talla: "G", color: "Verde" },
});

Gestión de Presupuestos​

Creación Pública de Presupuestos​

El SDK ahora incluye un método para crear presupuestos públicamente que retorna un enlace público para compartir:

// Crear un presupuesto público
const result = await billoget.budgets.createPublic({
  currency: "USD",
  issueDate: new Date(),
  expirationDate: new Date(Date.now() + 30 * 24 * 60 * 60 * 1000), // 30 días
  customerId: 123,
  sellerId: 456,
  minimumPaymentToConfirm: 100.0,
  subtotal: 1000.0,
  total: 1210.0,
  iva: 210.0,
  comments: "Presupuesto para nuevo proyecto",
  items: [
    {
      productId: 101,
      quantity: 2,
      unitPrice: 500.0,
    },
    {
      packageId: 201,
      quantity: 1,
      unitPrice: 210.0,
    },
  ],
});

console.log(`Presupuesto creado: ${result.publicUrl}`);
console.log(`ID del presupuesto: ${result.budgetId}`);
console.log(`Token público: ${result.publicToken}`);

// Resultado:
// {
//   success: true,
//   message: "Budget created successfully",
//   publicUrl: "https://app.billoget.com/budget/123_abc789_xyz456",
//   budgetId: 124,
//   publicToken: "123_abc789_xyz456"
// }

Consulta de Presupuestos (Solo Lectura)​

Importante

Los presupuestos son de solo lectura a través de la API para mantener la integridad de los datos. La creación y edición debe realizarse a través de la aplicación principal de Billoget.

// Listar presupuestos con filtros
const budgets = await billoget.budgets.list({
  page: 1,
  limit: 10,
  status: 0, // Generado
  customerId: 123,
  startDate: "2024-01-01",
  endDate: "2024-12-31",
});

// Obtener un presupuesto específico
const budget = await billoget.budgets.get(789);

// Obtener presupuestos por cliente
const customerBudgets = await billoget.budgets.getByCustomer(123);

// Obtener presupuestos por estado
const approvedBudgets = await billoget.budgets.getByStatus(1); // Aprobados

// Buscar presupuestos
const searchResults = await billoget.budgets.search("laptop");

Campos Adicionales en Respuestas​

Los presupuestos ahora incluyen campos adicionales para mejor integración:

const budget = await billoget.budgets.get(789);

console.log("Información del presupuesto:");
console.log(`IVA: ${budget.iva}`);
console.log(`URL de pago: ${budget.paymentUrl}`);
console.log(`Token público: ${budget.publicToken}`);
console.log(`Comentarios: ${budget.comments}`);
console.log(`UBS ID: ${budget.ubs_id}`);
console.log(`Versión UBS: ${budget.ubs_version}`);
console.log(`ID de seguimiento: ${budget.sign_track_id}`);
console.log(`Archivado: ${budget.isArchived}`);

// Información completa de productos
budget.items?.forEach((item) => {
  const product = item.product;
  console.log(`Producto: ${product?.productCode} - ${product?.description}`);
  console.log(`Categoría: ${product?.category}`);
  console.log(`Tipo: ${product?.type}`);
  console.log(
    `Contenido neto: ${product?.netContent} ${product?.netContentUnit}`
  );
  console.log(`Activo: ${product?.isActive}`);
});

// Información de la empresa
console.log("Empresa del vendedor:");
console.log(`Nombre: ${budget.seller?.business?.name}`);
console.log(`Email: ${budget.seller?.business?.email}`);
console.log(`Teléfono: ${budget.seller?.business?.phone}`);
console.log(`Dirección: ${budget.seller?.business?.address}`);

Sistema de Aprobaciones​

Configuración de Aprobaciones​

// Obtener configuración de aprobaciones
const config = await billoget.budgetApprovals.getConfig();

// Actualizar configuración
await billoget.budgetApprovals.createOrUpdateConfig({
  requiresBudgetApproval: true,
  ownerCanApprove: true,
  adminCanApprove: true,
  approvalThreshold: 1000.0,
});

Gestión de Aprobadores​

// Obtener aprobadores
const approvers = await billoget.budgetApprovals.getApprovers();

// Asignar un nuevo aprobador
await billoget.budgetApprovals.assignApprover({
  userId: 456,
  notes: "Gerente senior para presupuestos de alto valor",
});

// Remover aprobador
await billoget.budgetApprovals.removeApprover(approverId);

Flujo de Aprobación​

// Enviar presupuesto para aprobación
const approval = await billoget.budgetApprovals.submitForApproval({
  budgetId: 789,
  requestNotes: "Cliente de alto valor",
});

// Procesar aprobación
await billoget.budgetApprovals.processApproval(approval.id, {
  action: "approve",
  comments: "Aprobado por gerencia",
});

// Obtener aprobaciones pendientes
const pendingApprovals = await billoget.budgetApprovals.getPendingApprovals();

// Obtener estadísticas de aprobaciones
const stats = await billoget.budgetApprovals.getApprovalStats();

UBS - Estándar de Presupuestación Unificada​

El servicio UBS permite acceso público a presupuestos mediante tokens, sin requerir autenticación con API key.

Acceso Público a Presupuestos​

// Obtener presupuesto por token público
const publicBudget = await billoget.ubs.getBudgetByToken(
  "token_presupuesto_aqui"
);

// Depurar token para solución de problemas
const debugInfo = await billoget.ubs.debugToken("token_presupuesto_aqui");

// Confirmar presupuesto públicamente
const confirmation = await billoget.ubs.confirmBudget("token_presupuesto_aqui");

// Rechazar presupuesto públicamente
const rejection = await billoget.ubs.rejectBudget("token_presupuesto_aqui");

Utilidades UBS​

// Validar formato de token
const isValid = billoget.ubs.validateTokenFormat("token_presupuesto_aqui");

// Extraer información UBS
const ubsInfo = billoget.ubs.extractUBSInfo(publicBudget);
console.log("UBS ID:", ubsInfo.ubs_id);
console.log("Versión:", ubsInfo.ubs_version);
console.log("Cumple UBS:", ubsInfo.isUBSCompliant);

// Generar URL compartible
const shareUrl = billoget.ubs.generateShareableUrl("token_presupuesto_aqui");

// Verificar si está vencido
const isExpired = billoget.ubs.isBudgetExpired(publicBudget);

Configuración Avanzada​

const billoget = new BillogetSDK({
  apiKey: "bk_live_tu_api_key_aqui",
  baseUrl: "https://api.billoget.com/v1", // Opcional
  timeout: 30000, // Opcional, timeout en ms (1000-60000)
  retries: 3, // Opcional, número de reintentos (0-5)
  debug: false, // Opcional, habilitar logging de debug
});

Manejo de Errores​

try {
  const customer = await billoget.customers.get(999);
} catch (error) {
  if (error.response?.status === 404) {
    console.log("Cliente no encontrado");
  } else if (error.response?.status === 401) {
    console.log("API key inválida");
  } else {
    console.log("Error:", error.message);
  }
}

Soporte de TypeScript​

El SDK está escrito en TypeScript y proporciona definiciones de tipos completas:

import {
  BillogetSDK,
  Customer,
  Product,
  Budget,
  BudgetApproval,
} from "billoget-sdk";

const billoget = new BillogetSDK({
  apiKey: "bk_live_tu_api_key_aqui",
});

// Todos los métodos están completamente tipados
const customers: PaginatedResponse<Customer> = await billoget.customers.list();
const product: Product = await billoget.products.get(123);
const budget: Budget = await billoget.budgets.get(456);

Métodos del SDK​

Información y Diagnóstico​

// Obtener versión del SDK
const version = BillogetSDK.getVersion(); // "1.1.0"

// Obtener información completa del SDK
const info = billoget.getInfo();
console.log("Versión:", info.version);
console.log("Servicios:", info.services);

// Probar conexión
const connectionTest = await billoget.testConnection();
console.log("Conexión:", connectionTest.success ? "OK" : "Fallo");

Notas Importantes​

Gestión de Presupuestos​

  • Los presupuestos son de solo lectura para mantener la integridad de los datos
  • La creación y edición debe realizarse a través de la aplicación principal
  • Utiliza el sistema de aprobaciones para gestionar aprobaciones

UBS (Estándar de Presupuestación Unificada)​

  • Los endpoints UBS proporcionan acceso público mediante tokens
  • No requiere autenticación con API key
  • Soporta flujos de confirmación y rechazo

Limitación de Velocidad​

  • Las peticiones están sujetas a limitación de velocidad
  • La información de límites se incluye en los headers de respuesta
  • El SDK maneja automáticamente errores de límite con reintentos

Migración desde v1.0.0​

Cambios Importantes​

Servicio de Presupuestos:

// ❌ Ya no disponible (v1.0.0)
await billoget.budgets.create(budgetData);
await billoget.budgets.update(id, updateData);
await billoget.budgets.delete(id);

// ✅ Usar métodos de solo lectura (v1.1.0)
const budgets = await billoget.budgets.list();
const budget = await billoget.budgets.get(id);

Nuevos Servicios:

// ✅ Nuevo en v1.1.0
const approvals = await billoget.budgetApprovals.getPendingApprovals();
const publicBudget = await billoget.ubs.getBudgetByToken("token");
const variants = await billoget.products.getVariants(productId);

Ejemplos Completos​

Flujo Completo de Cliente y Producto​

// Crear cliente
const customer = await billoget.customers.create({
  firstName: "Ana",
  lastName: "García",
  email: "ana@example.com",
  dni: 12345678,
  cuit: "27-12345678-9",
});

// Crear producto con variantes
const product = await billoget.products.createWithVariants({
  productCode: "PROD-001",
  description: "Producto de Prueba",
  category: "Pruebas",
  price: 100.0,
  variants: [
    {
      name: "Variante A",
      price: 100.0,
      stock: 50,
      attributes: { color: "Rojo" },
    },
  ],
});

// Obtener presupuestos del cliente
const customerBudgets = await billoget.budgets.getByCustomer(customer.id);

Soporte​

Changelog​

v1.1.0 (Actual)​

  • ✅ Sistema de aprobaciones de presupuestos
  • ✅ Soporte UBS (Estándar de Presupuestación Unificada)
  • ✅ Variantes de productos
  • ✅ Campos extendidos de clientes (DNI, CUIT)
  • ✅ Presupuestos de solo lectura para integridad de datos

v1.0.0​

  • ✅ Lanzamiento inicial con servicios básicos