oytel-esim-sdk 1.0.0

Official Oytel eSIM API SDK for Python

oytel-esim

Official Oytel eSIM API SDK for Python.

🚀 Quick Start

Installation

pip install oytel-esim

Basic Usage

from oytel import OytelClient

# Initialize client with your API key
client = OytelClient(api_key="sk_sandbox_your_api_key_here")

# Get available plans
plans = client.get_plans()
print(f"Found {len(plans['plans'])} plans")

# Provision an eSIM
esim = client.provision_esim(
    plan_id="eu-roam-50",
    customer_email="[e-mail]",
    customer_name="John Doe"
)

print(f"eSIM ID: {esim['esim']['esim_id']}")
print(f"QR Code: {esim['esim']['qr_code_url']}")
print(f"Activation Code: {esim['esim']['activation_code']}")
print(f"Cost: ${esim['billing']['cost_usd']}")

# Check eSIM status
status = client.get_esim_status(esim['esim']['esim_id'])
print(f"Status: {status['esim']['status']}")

if status['esim']['usage']:
    usage = status['esim']['usage']
    print(f"Data used: {usage['used_mb']}MB / {usage['total_mb']}MB")
    print(f"Usage: {usage['usage_percentage']}%")

📖 API Reference

Client Initialization

from oytel import OytelClient

client = OytelClient(
    api_key="sk_sandbox_your_key_here",  # Required: Your API key
    base_url="https://api.oytel.co.uk",  # Optional: API base URL
    environment="sandbox",               # Optional: Auto-detected from API key
    timeout=30                          # Optional: Request timeout in seconds
)

Methods

get_plans() -> PlansResponse

Get all available eSIM plans.

plans = client.get_plans()

# Access plan data
for plan in plans['plans']:
    print(f"{plan['name']}: ${plan['pricing']['base_price']}")
    print(f"Coverage: {plan['coverage']}")
    print(f"Data: {plan['data_allowance']}")
    print(f"Validity: {plan['validity_days']} days")

provision_esim(...) -> ProvisionResponse

Provision a new eSIM for a customer.

esim = client.provision_esim(
    plan_id="eu-roam-50",
    customer_email="[e-mail]",
    customer_name="John Doe",
    reference_id="order-123",  # Optional
    webhook_url="https://your-app.com/webhook"  # Optional
)

# Access eSIM details
esim_info = esim['esim']
billing_info = esim['billing']

print(f"eSIM ID: {esim_info['esim_id']}")
print(f"ICCID: {esim_info['iccid']}")
print(f"QR Code URL: {esim_info['qr_code_url']}")
print(f"Manual Code: {esim_info['activation_code']}")
print(f"Cost: ${billing_info['cost_usd']}")
print(f"Remaining Balance: ${billing_info['remaining_balance']}")

get_esim_status(esim_id: str) -> StatusResponse

Get detailed status and usage information for an eSIM.

status = client.get_esim_status("esim_123456")

esim_status = status['esim']
print(f"Status: {esim_status['status']}")
print(f"Activated: {esim_status['activation']['activated']}")

# Check data usage (if available)
if esim_status['usage']:
    usage = esim_status['usage']
    print(f"Data used: {usage['used_mb']}MB")
    print(f"Data remaining: {usage['remaining_mb']}MB")
    print(f"Usage percentage: {usage['usage_percentage']}%")

# Check connection info (if available)
if esim_status['connection']:
    conn = esim_status['connection']
    print(f"Connection status: {conn['status']}")
    if conn['current_network']:
        network = conn['current_network']
        print(f"Current network: {network['operator']} ({network['country_name']})")
        print(f"Signal strength: {network['signal_strength']}/5")

🔑 Authentication

API Keys

Get your API keys from the Oytel Developer Dashboard:

• Sandbox: sk_sandbox_... - Free testing with mock data
• Production: sk_live_... - Real billing with test eSIMs

Environment Detection

# Sandbox client
sandbox_client = OytelClient(api_key="sk_sandbox_...")
print(sandbox_client.get_environment())  # "sandbox"

# Production client  
prod_client = OytelClient(api_key="sk_live_...")
print(prod_client.get_environment())  # "production"

🛡️ Error Handling

The SDK provides specific exception types for different error scenarios:

from oytel import OytelClient, OytelError, OytelAPIError, OytelAuthError

client = OytelClient(api_key="sk_sandbox_...")

try:
    esim = client.provision_esim(
        plan_id="invalid-plan",
        customer_email="[e-mail]", 
        customer_name="Test User"
    )
except OytelAuthError as e:
    print(f"Authentication error: {e}")
except OytelAPIError as e:
    print(f"API error: {e}")
    print(f"Status code: {e.status_code}")
    print(f"Error code: {e.error_code}")
except OytelError as e:
    print(f"General error: {e}")

Exception Types

• OytelError: Base exception for all SDK errors
• OytelAPIError: API-specific errors (4xx, 5xx responses)
• OytelAuthError: Authentication and authorization errors

💰 Billing & Costs

Sandbox Environment

• Free unlimited testing
• $100 fake credits (never depleted)
• Mock eSIMs (realistic responses but non-functional)

Production Environment

• Real money billing from your account balance
• Test eSIMs (safe - no real inventory used)
• Minimum $200 balance required for production access
• $25 minimum balance to continue API usage

📱 eSIM Integration Examples

Display QR Code

import qrcode
from PIL import Image
import requests

# Provision eSIM
esim = client.provision_esim(
    plan_id="eu-roam-50",
    customer_email="[e-mail]",
    customer_name="John Doe"
)

# Generate QR code from activation code
qr = qrcode.QRCode(version=1, box_size=10, border=5)
qr.add_data(esim['esim']['activation_code'])
qr.make(fit=True)

# Create QR code image
qr_image = qr.make_image(fill_color="black", back_color="white")
qr_image.save("esim_qr_code.png")

# Or download the provided QR code URL
qr_response = requests.get(esim['esim']['qr_code_url'])
with open("esim_qr_from_api.png", "wb") as f:
    f.write(qr_response.content)

Monitor Usage

import time

def monitor_esim_usage(client, esim_id, threshold=80):
    """Monitor eSIM usage and alert when threshold is reached."""
    
    while True:
        try:
            status = client.get_esim_status(esim_id)
            
            if status['esim']['usage']:
                usage = status['esim']['usage']
                usage_percent = usage['usage_percentage']
                
                print(f"Current usage: {usage_percent}%")
                
                if usage_percent >= threshold:
                    print(f"⚠️  WARNING: Usage exceeded {threshold}%!")
                    print(f"Data used: {usage['used_mb']}MB / {usage['total_mb']}MB")
                    break
                    
        except Exception as e:
            print(f"Error checking usage: {e}")
        
        # Check every hour
        time.sleep(3600)

# Start monitoring
monitor_esim_usage(client, "esim_123456", threshold=80)

Batch Provisioning

def provision_bulk_esims(client, customers, plan_id):
    """Provision eSIMs for multiple customers."""
    
    results = []
    
    for customer in customers:
        try:
            esim = client.provision_esim(
                plan_id=plan_id,
                customer_email=customer['email'],
                customer_name=customer['name'],
                reference_id=customer.get('order_id')
            )
            
            results.append({
                'customer': customer,
                'esim_id': esim['esim']['esim_id'],
                'qr_code': esim['esim']['qr_code_url'],
                'activation_code': esim['esim']['activation_code'],
                'success': True
            })
            
        except Exception as e:
            results.append({
                'customer': customer,
                'error': str(e),
                'success': False
            })
    
    return results

# Example usage
customers = [
    {'name': 'John Doe', 'email': '[e-mail]', 'order_id': 'ORD001'},
    {'name': 'Jane Smith', 'email': '[e-mail]', 'order_id': 'ORD002'},
]

results = provision_bulk_esims(client, customers, "eu-roam-50")

for result in results:
    if result['success']:
        print(f"✅ {result['customer']['name']}: {result['esim_id']}")
    else:
        print(f"❌ {result['customer']['name']}: {result['error']}")

🔄 Context Manager Usage

# Use with context manager for automatic cleanup
with OytelClient(api_key="sk_sandbox_...") as client:
    plans = client.get_plans()
    print(f"Found {len(plans['plans'])} plans")
    
    esim = client.provision_esim(
        plan_id="eu-roam-50",
        customer_email="[e-mail]",
        customer_name="Test User"
    )
    print(f"Provisioned: {esim['esim']['esim_id']}")

# Session automatically closed when exiting the context

🌍 Supported Regions

Available eSIM plans cover:

• Europe: 27+ countries with high-speed data
• Global: 190+ countries worldwide coverage
• Regional: Asia, Americas, Middle East specific plans
• Country-specific: UK, USA, and other individual countries

🌐 About Oytel

Oytel Mobile is the UK's leading eSIM provider, offering:

• 🌍 Global eSIM Coverage - 190+ countries worldwide
• 💰 Wholesale eSIM Solutions - Enterprise and reseller programs
• 📱 Consumer eSIMs - Individual plans for travelers
• 🔧 Developer APIs - Easy integration for businesses

Learn More: https://oytel.co.uk/

• Wholesale eSIM: https://oytel.co.uk/wholesale
• Business Solutions: https://oytel.co.uk/corporate

📞 Support

• Documentation: https://oytel.co.uk/developers
• Developer Dashboard: https://oytel.co.uk/developers/dashboard
• Email Support: [e-mail]
• GitHub Issues: https://github.com/oytel/esim-sdk-python/issues

📄 License

MIT License - see LICENSE file for details.

---

Powered by NexusCore Cloud ⚡