Skip to main content

🚀 API v1.1.0 Released - Enhanced Budget Management & UBS Support

· 5 min read
Billoget Development Team
Billoget Development Team
API & Platform Engineering Team

We're excited to announce the release of Billoget API v1.1.0, our biggest update yet! This release introduces significant improvements to budget management, customer data handling, product catalog features, and introduces the revolutionary UBS (Unified Budgeting Standard) for public budget access.

🌟 What's New​

📋 Enhanced Budget Management​

Read-Only Budget API for Data Integrity

  • Budgets are now read-only via API to maintain data integrity
  • All budget creation/modification happens through the secure web interface
  • Enhanced filtering with new fields: state, ubs_id, ubs_version
  • New budget states: 0=Generated, 1=Approved, 2=Rejected

New Budget Fields:

{
  "id": "budget_123",
  "state": 0,
  "ubs_id": "ubs_456",
  "ubs_version": "1.0",
  "publicToken": "pub_token_abc123",
  "minimumPaymentToConfirm": 500.0,
  "paymentUrl": "https://payment.billoget.com/budget_123",
  "comments": "Updated budget notes",
  "isArchived": false
}

👥 Enhanced Customer Data​

DNI and CUIT Support

  • Added dni (number) field for national identification
  • Added cuit (string) field for tax identification
  • Separated firstName and lastName for better data structure
  • Enhanced search capabilities by DNI and CUIT

Updated Customer Structure:

{
  "id": "customer_456",
  "firstName": "John",
  "lastName": "Doe",
  "email": "john.doe@example.com",
  "phoneNumber": "+1-555-123-4567",
  "dni": 12345678,
  "cuit": "20-12345678-9",
  "businessId": "business_001"
}

📦 Product Variants Support​

Complete Variant Management

  • Create products with multiple variants
  • Each variant has independent pricing, stock, and attributes
  • Custom attributes support for flexible product configurations
  • New product types: PRODUCT, SERVICE, SUBSCRIPTION

Product with Variants Example:

{
  "productCode": "MKT-PREM-001",
  "description": "Premium Marketing Package",
  "type": "SERVICE",
  "variants": [
    {
      "name": "Basic",
      "price": 1500.0,
      "attributes": {
        "duration": "1 month",
        "channels": "2"
      }
    },
    {
      "name": "Premium",
      "price": 2500.0,
      "attributes": {
        "duration": "3 months",
        "channels": "5"
      }
    }
  ]
}

🔔 Budget Approval System​

Complete Approval Workflow

  • Submit budgets for approval with request notes
  • Track approval status: PENDING, APPROVED, REJECTED
  • Approval actions: APPROVE, REJECT, REQUEST_CHANGES
  • Full audit trail with timestamps and comments

Approval Example:

{
  "budgetId": "budget_123",
  "requestNotes": "Please review Q1 marketing budget",
  "action": "APPROVE",
  "status": "PENDING"
}

🌐 UBS (Unified Budgeting Standard)​

Public Budget Access Revolution

  • Access budgets via public tokens without authentication
  • Public confirmation and rejection workflows
  • Secure token-based system for customer interactions
  • Perfect for client-facing budget review processes

UBS Endpoints:

# Get budget by public token
GET /api/public/ubs/budget/{token}

# Confirm budget publicly
POST /api/public/ubs/budget/{token}/confirm

# Reject budget with reason
POST /api/public/ubs/budget/{token}/reject

🛠️ Technical Improvements​

📡 Enhanced API Structure​

New Endpoint Categories:

  • Budget Approvals API - Complete approval management
  • UBS API - Public budget access and interactions
  • Product Variants API - Variant management endpoints
  • Enhanced Filtering - Advanced search and filter options

🔒 Security Enhancements​

  • Token-based UBS access with secure validation
  • Read-only budget operations for data integrity
  • Enhanced API key scopes for granular permissions
  • Audit trails for all approval actions

📊 Better Data Validation​

  • TypeScript interfaces for all new endpoints
  • Enhanced error handling with descriptive messages
  • Input validation for DNI, CUIT, and other fields
  • Consistent response formats across all endpoints

📥 Updated Resources​

🔧 Postman Collection v1.1.0​

Download the updated collection with all new endpoints:

New Collection Features:

  • ✅ All new API endpoints with examples
  • ✅ Automated tests for response validation
  • ✅ Environment variables for easy switching
  • ✅ Pre-request scripts for authentication
  • ✅ Rate limiting awareness

📚 SDK Updates​

The billoget-sdk v1.1.0 has been updated to support all new features:

npm install billoget-sdk@1.1.0

New SDK Features:

  • Budget approval methods
  • UBS token operations
  • Product variant management
  • Enhanced customer operations
  • TypeScript support for all new types

🔄 Migration Guide​

From v1.0.0 to v1.1.0​

Budget Operations:

// ❌ No longer available (v1.0.0)
await billoget.budgets.create(budgetData);
await billoget.budgets.update(id, updateData);
await billoget.budgets.delete(id);

// ✅ Use read-only methods (v1.1.0)
const budgets = await billoget.budgets.list({ state: 0 });
const budget = await billoget.budgets.getById(id);

Customer Structure:

// ❌ Old structure (v1.0.0)
{
  "name": "John Doe",
  "taxId": "12-3456789"
}

// ✅ New structure (v1.1.0)
{
  "firstName": "John",
  "lastName": "Doe",
  "dni": 12345678,
  "cuit": "20-12345678-9"
}

Product Variants:

// ✅ New in v1.1.0
const product = await billoget.products.createWithVariants({
  productCode: "PROD-001",
  description: "Main Product",
  variants: [
    { name: "Small", price: 100 },
    { name: "Large", price: 200 },
  ],
});

🎯 Use Cases​

💼 Business Scenarios​

1. Client Budget Review

// Generate UBS token for client review
const budget = await billoget.budgets.getById("budget_123");
const ubsUrl = `https://budgets.billoget.com/${budget.publicToken}`;
// Send URL to client for review and approval

2. Product Catalog with Variants

// Create service with multiple tiers
const service = await billoget.products.createWithVariants({
  description: "Consulting Service",
  type: "SERVICE",
  variants: [
    { name: "Basic", price: 500, attributes: { hours: "5" } },
    { name: "Premium", price: 1000, attributes: { hours: "10" } },
  ],
});

3. Approval Workflow

// Submit budget for approval
const approval = await billoget.budgetApprovals.submit({
  budgetId: "budget_123",
  requestNotes: "Please review Q1 budget",
  action: "APPROVE",
});

🔮 What's Next​

Upcoming Features (v1.2.0)​

  • Real-time notifications via WebSockets
  • Bulk operations for products and customers
  • Advanced analytics endpoints
  • Custom approval workflows
  • Multi-currency support enhancements

Community Feedback​

We'd love to hear your feedback on the new features! Join our community:

🎉 Get Started​

Ready to upgrade? Here's how to get started:

  1. 📥 Download the new Postman collection v1.1.0
  2. 📚 Review the updated documentation
  3. 🔧 Update your integration to use new endpoints
  4. 🧪 Test with the enhanced SDK v1.1.0
  5. 🚀 Deploy with confidence

Happy coding! 🚀

The Billoget Development Team

For technical questions or support, reach out to our developer community or contact us at developers@billoget.com.