PHP SDK Guide

Installation

composer require touristesim/touristesim-php-sdk

Requirements: PHP 8.3 or higher

Quick Start

<?php
require 'vendor/autoload.php';
use TouristeSIM\Sdk\TouristEsim;

// Initialize
$sdk = new TouristEsim('YOUR_CLIENT_ID', 'YOUR_CLIENT_SECRET');

// Get plans
$plans = $sdk->plans->get(page: 1);
echo "Total plans: " . $plans->pagination->total;

Authentication

The SDK handles OAuth 2.0 authentication automatically. Tokens are cached locally to minimize API calls:

// First call: OAuth token is fetched
$plans1 = $sdk->plans->get();

// Token is cached, no new OAuth call
$plans2 = $sdk->plans->get();

// Clear cache if needed
$sdk->clearTokenCache();

Work with Plans

// List all plans
$plans = $sdk->plans->get(page: 1, limit: 50);

// Filter by country
$plans = $sdk->plans->getByCountry('US');

// Filter by provider
$plans = $sdk->plans->getByProvider('provider-slug');

// Get plan details
foreach ($plans->data as $plan) {
    echo $plan->name;           // "USA 5GB - 7 Days"
    echo $plan->price;          // 9.99
    echo $plan->country;        // "US"
}

Create Orders

// Create order
$order = $sdk->orders->create([
    'plans' => [
        ['plan_slug' => 'vietnam_100mb_7days_7e87c5', 'quantity' => 1],
        ['plan_slug' => 'united_states_2gb_1day_dbab39', 'quantity' => 2]
    ],
    'email' => 'customer@example.com'
]);

echo "Order: " . $order->order_number;
echo "Status: " . $order->status;
echo "Total: " . $order->amount;

Error Handling

try {
    $plans = $sdk->plans->get();
} catch (TouristEsim\Sdk\Exceptions\AuthenticationException $e) {
    echo "Auth failed: " . $e->getMessage();
} catch (TouristEsim\Sdk\Exceptions\ValidationException $e) {
    echo "Invalid input: " . $e->getMessage();
}

Node.js SDK Guide

Installation

npm install @tourist-esim/touristesim-nodejs-sdk

Requirements: Node.js 20 LTS or higher

Quick Start

import { TouristEsim } from '@tourist-esim/touristesim-nodejs-sdk';

// Initialize
const sdk = new TouristEsim('YOUR_CLIENT_ID', 'YOUR_CLIENT_SECRET');

// Get plans
const plans = await sdk.plans.get(1);
console.log(`Total plans: ${plans.pagination.total}`);

Authentication

Tokens are cached automatically using NodeCache:

// First call: OAuth token is fetched and cached
const plans1 = await sdk.plans.get();

// Token is cached, no new OAuth call
const plans2 = await sdk.plans.get();

// Clear cache if needed
sdk.clearCache();

Work with Plans

// List all plans
const plans = await sdk.plans.get(1, 50);

// Filter by country
const usPlans = await sdk.plans.getByCountry('US');

// Filter by provider
const providerPlans = await sdk.plans.getByProvider('provider-slug');

// Get plan details
plans.data.forEach(plan => {
    console.log(plan.name);      // "USA 5GB - 7 Days"
    console.log(plan.price);     // 9.99
});

Create Orders

// Create order
const order = await sdk.orders.create({
    plans: [
        { plan_slug: 'vietnam_100mb_7days_7e87c5', quantity: 1 },
        { plan_slug: 'united_states_2gb_1day_dbab39', quantity: 2 }
    ],
    email: 'customer@example.com'
});

console.log(`Order ID: ${order.id}`);
console.log(`Status: ${order.status}`);

Python SDK Guide

Installation

pip install touristesim-python-sdk

Requirements: Python 3.8 or higher

Quick Start

from touristesim import TouristEsim

# Initialize
sdk = TouristEsim('YOUR_CLIENT_ID', 'YOUR_CLIENT_SECRET')

# Get plans
plans = sdk.plans.get(page=1)
print(f"Total plans: {plans['pagination']['total']}")

Authentication

The SDK automatically manages token caching:

# First call: OAuth token is fetched
plans1 = sdk.plans.get()

# Token is cached, no new OAuth call
plans2 = sdk.plans.get()

# Clear cache if needed
sdk.clear_cache()

Work with Plans

# List all plans
plans = sdk.plans.get(page=1, limit=50)

# Filter by country
us_plans = sdk.plans.get_by_country('US')

# Filter by provider
provider_plans = sdk.plans.get_by_provider('provider-slug')

# Get plan details
for plan in plans['data']:
    print(f"{plan['name']}: ${plan['price']}")

Create Orders

# Create order
order = sdk.orders.create({
    'plans': [
        {'plan_slug': 'vietnam_100mb_7days_7e87c5', 'quantity': 1},
        {'plan_slug': 'united_states_2gb_1day_dbab39', 'quantity': 2}
    ],
    'email': 'customer@example.com'
})

print(f"Order: {order['order_number']}")
print(f"Status: {order['status']}")

Best Practices

1. Error Handling

Always wrap SDK calls in try-catch blocks to handle errors gracefully:

• AuthenticationException: Invalid credentials or expired token
• ValidationException: Invalid parameters or data
• ServerException: Server error (retry with backoff)

2. Token Caching

All SDKs implement automatic token caching:

• Tokens are cached for their default TTL (3600 seconds)
• Expired tokens are automatically refreshed
• Manual cache clearing is rarely needed

3. Security

• Never expose Client ID or Secret in frontend code
• Store credentials in environment variables
• Use HTTPS only in production
• Rotate credentials regularly