Skip to main content

Overview

Welcome to the Billoget API! This guide will help you get started with integrating Billoget's budget management capabilities into your applications.

🎯 What You Can Do​

The Billoget API allows you to:

  • Create and manage budgets programmatically
  • Sync customer data between systems
  • Handle product catalogs and pricing
  • Receive real-time notifications via webhooks
  • Generate reports and analytics

🏗️ API Architecture​

RESTful Design​

Our API follows REST principles with predictable resource-oriented URLs, accepts JSON-encoded request bodies, and returns JSON-encoded responses.

Base URL​

https://api.billoget.com/v1

API Versioning​

The current API version is v1.4.0. All endpoints are prefixed with /api/public/ for public access.

🔐 Authentication​

The Billoget API uses API Keys for authentication. Each API key has specific scopes that determine what actions it can perform.

API Key Format​

bk_live_1234567890abcdef...

Authentication Header​

Authorization: Bearer bk_live_1234567890abcdef...

📊 Rate Limiting​

To ensure fair usage and system stability, the API implements rate limiting:

  • Default Limit: 1000 requests per hour per API key
  • Configurable: Can be adjusted per API key
  • Headers: Rate limit information is included in response headers

🔄 Request/Response Format​

Request Format​

All requests should include:

  • Content-Type: application/json header
  • Authorization: Bearer {api_key} header
  • JSON body for POST/PUT requests

Response Format​

All responses include:

  • HTTP status code
  • JSON body with data or error information
  • Pagination metadata when applicable

Example Request​

curl -X GET "https://api.billoget.com/v1/api/public/budgets" \
  -H "Authorization: Bearer bk_live_1234567890abcdef" \
  -H "Content-Type: application/json"

Example Response​

{
  "data": [
    {
      "id": "budget_123",
      "customerId": "customer_456",
      "total": 1500.0,
      "status": "PENDING",
      "createdAt": "2024-01-15T10:30:00Z"
    }
  ],
  "pagination": {
    "page": 1,
    "limit": 10,
    "total": 1,
    "hasMore": false
  }
}

🛡️ Security Features​

HTTPS Only​

All API requests must use HTTPS. HTTP requests will be rejected.

API Key Security​

  • API keys are hashed using bcrypt before storage
  • Keys have configurable expiration dates
  • IP whitelisting is available for additional security

Webhook Security​

  • Webhooks are signed with HMAC-SHA256
  • Signatures are included in the X-Billoget-Signature header
  • Payload validation prevents tampering

📈 Monitoring & Analytics​

Request Tracking​

Every API request is logged with:

  • Timestamp and response time
  • HTTP method and endpoint
  • Status code and payload size
  • Client IP and user agent

Usage Analytics​

Monitor your API usage through:

  • Request count per day/hour
  • Most used endpoints
  • Error rates and types
  • Performance metrics

🚀 Next Steps​

Now that you understand the basics, let's dive deeper:

  1. Authentication - Learn how to authenticate with the API
  2. API Keys - Create and manage your API keys
  3. Rate Limiting - Understand rate limits and best practices
  4. Error Handling - Handle errors gracefully

📚 Additional Resources​

Ready to authenticate? Let's move on to Authentication! 🔐