Saltar al contenido principal

Postman Collection Guide

Overview​

The Billoget Public API v1.1.0 Postman Collection provides a comprehensive set of pre-configured requests for testing and integrating with the Billoget API. This guide will help you get started quickly with our API.

📥 Download Collection​

Access the latest collection through our interactive documentation:

🚀 Quick Start​

Step 1: Access the Collection​

  1. Visit our Postman Documentation
  2. Click the "Run in Postman" button to import directly, or
  3. Click "Download Collection" to get the JSON file for manual import

⚙️ Configuration​

Required Variables​

Before using the collection, configure these variables:

VariableDescriptionExample Value
base_urlAPI base URLhttps://api.billoget.com
api_keyYour API keybk_live_1234567890abcdef...

Setting Variables​

  1. Collection Level: Right-click collection → Edit → Variables tab
  2. Environment: Create a new environment with these variables
  3. Global: Set as global variables for all collections
{
  "base_url": "https://api.billoget.com/v1",
  "api_key": "bk_live_your_actual_api_key_here"
}

🔐 Authentication​

The collection is pre-configured with Bearer Token authentication:

  • Type: Bearer Token
  • Token: {{api_key}}
  • Applied to: All requests automatically

Getting Your API Key​

  1. Log into your Billoget dashboard
  2. Navigate to Settings → API Keys
  3. Click Create New API Key
  4. Configure scopes and settings
  5. Copy the generated key

📊 Collection Structure​

📋 Budgets API (5 requests)​

Complete CRUD operations for budget management:

List Budgets​

GET {{base_url}}/api/public/budgets?page=1&limit=10

Query Parameters:

  • page - Page number (default: 1)
  • limit - Items per page (max: 100)
  • status - Filter by status (PENDING, APPROVED, REJECTED, EXPIRED)
  • customerId - Filter by customer ID
  • search - Search in notes and descriptions
  • minTotal / maxTotal - Amount range filters
  • createdAfter / createdBefore - Date range filters
  • sort / order - Sorting options

Example Response:

{
  "data": [
    {
      "id": "budget_123",
      "customerId": "customer_456",
      "status": "PENDING",
      "total": 1500.0,
      "subtotal": 1300.0,
      "tax": 200.0,
      "currency": "USD",
      "validUntil": "2024-02-15T23:59:59Z",
      "notes": "Q1 Marketing Budget",
      "createdAt": "2024-01-15T10:30:00Z",
      "customer": {
        "id": "customer_456",
        "name": "Acme Corp",
        "email": "contact@acme.com"
      }
    }
  ],
  "pagination": {
    "page": 1,
    "limit": 10,
    "total": 1,
    "hasMore": false
  }
}

Get Budget by ID​

GET {{base_url}}/api/public/budgets/:budgetId

Create Budget​

POST {{base_url}}/api/public/budgets

Request Body:

{
  "customerId": "customer_456",
  "items": [
    {
      "productId": "product_789",
      "description": "Premium Marketing Package",
      "quantity": 2,
      "unitPrice": 500.0
    },
    {
      "productId": "product_790",
      "description": "Additional Services",
      "quantity": 1,
      "unitPrice": 200.0
    }
  ],
  "notes": "Q1 Marketing Campaign Budget",
  "validUntil": "2024-03-31T23:59:59Z",
  "metadata": {
    "source": "api",
    "campaign": "Q1_2024",
    "department": "marketing"
  }
}

Update Budget​

PUT {{base_url}}/api/public/budgets/:budgetId

Request Body:

{
  "status": "APPROVED",
  "notes": "Approved by manager - ready to proceed",
  "validUntil": "2024-04-30T23:59:59Z"
}

Delete Budget​

DELETE {{base_url}}/api/public/budgets/:budgetId

👥 Customers API (5 requests)​

Customer information management:

List Customers​

GET {{base_url}}/api/public/customers?page=1&limit=10

Query Parameters:

  • page - Page number
  • limit - Items per page
  • search - Search by name or email
  • sort / order - Sorting options

Get Customer by ID​

GET {{base_url}}/api/public/customers/:customerId

Create Customer​

POST {{base_url}}/api/public/customers

Request Body:

{
  "name": "John Doe",
  "email": "john.doe@example.com",
  "phone": "+1-555-123-4567",
  "address": "123 Main Street",
  "city": "New York",
  "state": "NY",
  "country": "USA",
  "postalCode": "10001",
  "taxId": "12-3456789",
  "metadata": {
    "source": "api",
    "leadSource": "website",
    "priority": "high"
  }
}

Update Customer​

PUT {{base_url}}/api/public/customers/:customerId

Delete Customer​

DELETE {{base_url}}/api/public/customers/:customerId

📦 Products API (5 requests)​

Product catalog management:

List Products​

GET {{base_url}}/api/public/products?page=1&limit=10

Query Parameters:

  • page - Page number
  • limit - Items per page
  • category - Filter by category
  • search - Search in name/description
  • isActive - Filter by active status
  • minPrice / maxPrice - Price range filters

Get Product by ID​

GET {{base_url}}/api/public/products/:productId

Create Product​

POST {{base_url}}/api/public/products

Request Body:

{
  "name": "Premium Marketing Package",
  "description": "Comprehensive marketing solution including strategy, content creation, and campaign management",
  "price": 2500.0,
  "sku": "MKT-PREM-001",
  "category": "services",
  "unit": "package",
  "isActive": true,
  "metadata": {
    "duration": "3 months",
    "deliverables": "strategy, content, reports",
    "team": "marketing"
  }
}

Update Product​

PUT {{base_url}}/api/public/products/:productId

Delete Product​

DELETE {{base_url}}/api/public/products/:productId

🔗 Webhooks API (1 request)​

Webhook testing and management:

Test Webhook​

POST {{base_url}}/api/public/webhooks/test

Request Body:

{
  "event": "budget.created",
  "data": {
    "id": "budget_123",
    "customerId": "customer_456",
    "total": 1500.0,
    "status": "PENDING",
    "createdAt": "2024-01-15T10:30:00Z"
  }
}

🧪 Built-in Testing​

The collection includes automated tests for every request:

Global Tests​

All requests automatically test:

  • Response time < 2000ms
  • Valid JSON response
  • Rate limit headers presence
  • Rate limit monitoring with warnings

Test Scripts​

// Response time validation
pm.test("Response time is less than 2000ms", function () {
  pm.expect(pm.response.responseTime).to.be.below(2000);
});

// JSON validation
pm.test("Response has valid JSON", function () {
  pm.response.to.have.jsonBody();
});

// Rate limit monitoring
const rateLimitRemaining = pm.response.headers.get("X-RateLimit-Remaining");
const rateLimitLimit = pm.response.headers.get("X-RateLimit-Limit");
if (rateLimitRemaining && rateLimitLimit) {
  console.log(`Rate Limit: ${rateLimitRemaining}/${rateLimitLimit} remaining`);

  if (parseInt(rateLimitRemaining) < 10) {
    console.warn("⚠️ Rate limit running low!");
  }
}

Pre-request Scripts​

Automatic timestamp generation:

// Set timestamp for requests
pm.globals.set("timestamp", new Date().toISOString());

🚀 Usage Examples​

Running Individual Requests​

  1. Select a request from the collection
  2. Ensure variables are set correctly
  3. Click Send
  4. Check the Test Results tab for validation

Running the Entire Collection​

  1. Right-click the collection name
  2. Select Run collection
  3. Configure iterations and delay
  4. Click Run Billoget Public API v1.1.0
  5. Monitor results in the Collection Runner

Environment Switching​

Create different environments for different stages:

Development Environment:

{
  "base_url": "https://api.billoget.com/v1",
  "api_key": "bk_test_development_key"
}

Production Environment:

{
  "base_url": "https://api.billoget.com/v1",
  "api_key": "bk_live_production_key"
}

📈 Monitoring and Analytics​

Rate Limit Monitoring​

The collection automatically monitors your rate limits:

  • Displays current usage in console
  • Warns when approaching limits
  • Tracks remaining requests

Response Time Tracking​

All requests are tested for performance:

  • Fails if response time > 2000ms
  • Helps identify API performance issues
  • Useful for monitoring during load testing

🛠️ Customization​

Adding Custom Tests​

Add request-specific tests in the Tests tab:

// Custom validation for budget creation
if (pm.response.code === 201) {
  pm.test("Budget created successfully", function () {
    const response = pm.response.json();
    pm.expect(response.data.id).to.exist;
    pm.expect(response.data.status).to.eql("PENDING");
  });
}

Environment Variables​

Add custom variables for your integration:

{
  "base_url": "https://api.billoget.com/v1",
  "api_key": "bk_live_...",
  "customer_id": "customer_123",
  "product_id": "product_456",
  "test_email": "test@yourcompany.com"
}

Custom Headers​

Add integration-specific headers:

// Pre-request script
pm.request.headers.add({
  key: "X-Integration-Name",
  value: "My Company Integration",
});

🔍 Troubleshooting​

Common Issues​

401 Unauthorized​

  • Check API key is correct
  • Verify key hasn't expired
  • Ensure key has required scopes

429 Rate Limited​

  • Wait for rate limit reset
  • Reduce request frequency
  • Check rate limit headers

404 Not Found​

  • Verify endpoint URL
  • Check resource ID exists
  • Confirm base_url is correct

Debug Mode​

Enable detailed logging:

// Add to pre-request script
console.log("Request URL:", pm.request.url.toString());
console.log("Request Headers:", pm.request.headers.toJSON());

📚 Next Steps​

🔗 Additional Resources​

Ready to start testing? Access the collection and start exploring the Billoget API! 🚀