Hubby eSIM API Quickstart Guide
Last updated

Hubby eSIM API Quickstart Guide

Welcome to Hubby! This quickstart guide will help you get started with Hubby's eSIM API, allowing you to make your first API call and begin integrating eSIM booking capabilities into your application.

API Endpoints

Hubby provides two API endpoints:

  • Production: https://api.hubbyesim.com/api - Use this for live applications
  • Staging: https://api-staging.hubby.dev/api - Use this for testing and development

Make sure to use the appropriate endpoint based on your needs. The staging environment is perfect for testing your integration before going live.

Step 1: Get Your API Keys

  1. Contact Hubby support at support@hubbyesim.com to get your API credentials
  2. You will receive:
    • Public API Key (x-api-key)
    • Secret Key (for generating signatures)

Step 2: Authentication

All API requests must include the following headers:

  • x-api-key: Your public API key
  • x-timestamp: Current Unix timestamp in milliseconds
  • x-signature: HMAC-SHA256 signature

Here's how to generate the HMAC signature:

const cryptoJs = require('crypto-js');

// Configuration values that would normally come from environment
const secretKey = "YOUR_API_SECRET";
const publicKey = "YOUR_API_KEY";
const baseUrl = "YOUR_BASE_URL";

// Function to generate headers for API request
function generateApiHeaders(method, path) {
    // Get current timestamp in milliseconds
    const timestamp = Date.now().toString();

    // Ensure path is a string
    let processedPath = String(path);

    // Remove baseUrl from the path if present
    processedPath = processedPath.replace(baseUrl, '');

    // Create query string if needed
    const queryString = new URL(path).search;
    if (queryString) {
        processedPath += queryString;
    }

    // Validate public key
    if (!publicKey) {
        throw new Error("Public key is required");
    }

    // Create the payload - include query parameters if present
    // Sample payload: 1715558400000GET/api/bookings?bookingId=1234567890
    const payload = timestamp + method + processedPath;

    // Generate the HMAC signature
    const signature = cryptoJs.HmacSHA256(payload, secretKey).toString(cryptoJs.enc.Hex);

    // Return headers object
    return {
        'x-timestamp': timestamp,
        'x-signature': signature,
        'x-api-key': publicKey,
        'Accept': 'application/json'
    };
}

Step 3: Create Your First Booking

Let's create a booking for an eSIM package. Use the staging URL for testing:

# For testing (staging):
curl -X POST https://api-staging.hubby.dev/api/bookings \

# For production:
# curl -X POST https://api.hubbyesim.com/api/bookings \
-H "Content-Type: application/json" \
-H "x-api-key: YOUR_API_KEY" \
-H "x-timestamp: 1715558400000" \
-H "x-signature: YOUR_GENERATED_SIGNATURE" \
-d '{
  "departure_date": "2024-12-01",
  "email": "customer@example.com",
  "first_name": "John",
  "last_name": "Doe",
  "package_specifications": [
    {
      "destination": "US",
      "size": "500MB"
    }
  ]
}'

Response Example

{
  "success": true,
  "message": "Booking created successfully",
  "data": {
    "id": "booking_id",
    "email": "customer@example.com",
    "first_name": "John",
    "last_name": "Doe",
    "departure_date": "2024-12-01",
    "promo_codes": [
      {
        "promo_code": "XXXX-YYYY-ZZZZ",
        "package_id": "package_id",
        "package_size": "500MB",
        "destination": "US"
      }
    ]
  }
}

Step 4: View Available Packages

Before creating a booking, you might want to check available packages for specific countries:

# For testing (staging):
curl -X GET "https://api-staging.hubby.dev/api/countries/US/packages" \

# For production:
# curl -X GET "https://api.hubbyesim.com/api/countries/US/packages" \
-H "x-api-key: YOUR_API_KEY" \
-H "x-timestamp: 1715558400000" \
-H "x-signature: YOUR_GENERATED_SIGNATURE"

Response Example

{
  "success": true,
  "message": "Packages fetched successfully",
  "data": {
    "US": [
      {
        "id": "package_id",
        "label": "500 MB",
        "bytes": 500170752,
        "country": "US",
        "price": 10.99,
        "customerPrice": 8.99
      }
    ]
  }
}

Step 5: Retrieve Booking Details

You can retrieve booking details using the booking ID:

# For testing (staging):
curl -X GET "https://api-staging.hubby.dev/api/bookings/YOUR_BOOKING_ID?includeUsage=true" \

# For production:
# curl -X GET "https://api.hubbyesim.com/api/bookings/YOUR_BOOKING_ID?includeUsage=true" \
-H "x-api-key: YOUR_API_KEY" \
-H "x-timestamp: 1715558400000" \
-H "x-signature: YOUR_GENERATED_SIGNATURE"

Response Example

{
  "success": true,
  "message": "Booking details retrieved successfully",
  "data": {
    "id": "booking_id",
    "email": "customer@example.com",
    "departure_date": "2024-12-01",
    "promo_codes": [
      {
        "promo_code": "XXXX-YYYY-ZZZZ",
        "package_id": "package_id",
        "package_size": "500MB",
        "destination": "US"
      }
    ]
  }
}

Step 6: Understanding Package Types

The Hubby API supports three different types of eSIM packages. Here are examples of each:

Data-Limited Package (Default)

Traditional packages with a specific data allowance:

# For testing (staging):
curl -X POST https://api-staging.hubby.dev/api/bookings \

# For production:
# curl -X POST https://api.hubbyesim.com/api/bookings \
-H "Content-Type: application/json" \
-H "x-api-key: YOUR_API_KEY" \
-H "x-timestamp: 1715558400000" \
-H "x-signature: YOUR_GENERATED_SIGNATURE" \
-d '{
  "departure_date": "2024-12-01",
  "email": "customer@example.com",
  "package_specifications": [
    {
      "destination": "US",
      "size": "1GB",
      "package_type": "data-limited",
      "package_duration": 365
    }
  ]
}'

Time-Limited Package

Unlimited data for a specific duration:

# For testing (staging):
curl -X POST https://api-staging.hubby.dev/api/bookings \

# For production:
# curl -X POST https://api.hubbyesim.com/api/bookings \
-H "Content-Type: application/json" \
-H "x-api-key: YOUR_API_KEY" \
-H "x-timestamp: 1715558400000" \
-H "x-signature: YOUR_GENERATED_SIGNATURE" \
-d '{
  "departure_date": "2024-12-01",
  "email": "customer@example.com",
  "package_specifications": [
    {
      "destination": "US",
      "package_type": "time-limited",
      "package_duration": 3
    }
  ]
}'

Starter Package

Limited data for a short duration (perfect for trials):

# For testing (staging):
curl -X POST https://api-staging.hubby.dev/api/bookings \

# For production:
# curl -X POST https://api.hubbyesim.com/api/bookings \
-H "Content-Type: application/json" \
-H "x-api-key: YOUR_API_KEY" \
-H "x-timestamp: 1715558400000" \
-H "x-signature: YOUR_GENERATED_SIGNATURE" \
-d '{
  "departure_date": "2024-12-01",
  "email": "customer@example.com",
  "package_specifications": [
    {
      "destination": "US",
      "size": "500MB",
      "package_type": "starter",
      "package_duration": 1
    }
  ]
}'

Note: If you don't specify package_type, it defaults to data-limited. For more details, see our Package Types guide.

Error Handling

The API uses standard HTTP status codes and returns detailed error messages:

{
  "success": false,
  "error": {
    "code": 400,
    "message": "Validation error",
    "details": {
      "departure_date": "Must be a future date"
    }
  }
}

Common error codes:

  • 400: Validation error
  • 401: Authentication error (check timestamp format and signature calculation)
  • 404: Resource not found
  • 500: Server error

Next Steps

Need help? Email us at support@hubbyesim.com

 
Next page
Copyright © 2024 Hubby. All rights reserved.