PySyriatel 2.0.0

A professional Python library for interacting with the Syriatel Cash API

Syriatel Cash API Python Library

A professional Python library for interacting with the Syriatel Cash API. Supports both async and sync operations with proper error handling.

Installation

pip install -e .

Or install from source:

git clone <repository-url>
cd syr_cash_api
pip install -e .

Quick Start

Async Usage

import asyncio
from syriatel import SyriatelCashClient

async def main():
    # Using async context manager (recommended)
    async with SyriatelCashClient(api_token="your_api_token") as client:
        # Get balance (returns integer directly)
        balance = await client.get_balance("0991234567")
        print(f"Balance: {balance} SYP")
        
        # Get incoming history (returns list of transactions directly)
        transactions = await client.get_incoming_history(number="0991234567", page=1)
        print(f"Total transactions: {len(transactions)}")
        for tx in transactions:
            print(f"{tx.date}: {tx.amount} SYP from {tx.from_gsm}")
        
        # Filter transactions by date
        filtered = client.filter_transactions_by_date(
            transactions,
            start_date="2024-01-01",
            end_date="2024-01-31"
        )
        
        # Find transaction by number
        tx = await client.find_incoming_transaction("TXN123456", number="0991234567")
        if tx:
            print(f"Found transaction: {tx.amount} SYP")
        
        # Get outgoing history
        outgoing = await client.get_outgoing_history(code="1234", page=1)
        
        # List all active numbers
        numbers = await client.get_incoming_history()
        for num in numbers:
            print(f"Number: {num.number}, Code: {num.code}")

asyncio.run(main())

Sync Usage

from syriatel import SyriatelCashClientSync

# Using context manager (recommended)
with SyriatelCashClientSync(api_token="your_api_token") as client:
    # Get balance (returns integer directly)
    balance = client.get_balance("0991234567")
    print(f"Balance: {balance} SYP")
    
    # Get incoming history (returns list of transactions directly)
    transactions = client.get_incoming_history(number="0991234567", page=1)
    print(f"Total transactions: {len(transactions)}")
    
    # Get outgoing history
    outgoing = client.get_outgoing_history(code="1234", page=1)
    
    # List all active numbers
    numbers = client.get_incoming_history()
    for num in numbers:
        print(f"Number: {num.number}, Code: {num.code}")

API Reference

SyriatelCashClient (Async)

get_balance(number: str) -> BalanceResponse

Get Syriatel Cash balance for a phone number.

Parameters:

• number (str): Phone number in format 0XXXXXXXXX (will be normalized)

Returns:

• BalanceResponse: Object with balance (int) attribute

Raises:

• InvalidTokenError: API token is invalid
• SubscriptionExpiredError: Subscription is expired
• FetchFailedError: Failed to fetch from Syriatel
• NotAuthorizedError: Account not authorized
• ServerMaintenanceError: Servers under maintenance
• NetworkError: Network request failed

Example:

balance = await client.get_balance("0991234567")
print(balance.balance)  # 50000

get_incoming_history(number=None, code=None, page=1) -> HistoryResponse | List[NumberWithCode]

Get incoming transaction history.

Parameters:

• number (str, optional): Phone number
• code (str, optional): Secret code (alternative to number)
• page (int, optional): Page number (default: 1)

Returns:

• HistoryResponse if number/code provided: Object with total (int) and transactions (List[Transaction])
• List[NumberWithCode] if neither provided: List of active subscriptions

Example:

# Get history for a number
history = await client.get_incoming_history(number="0991234567", page=1)
print(history.total)  # 25
for tx in history.transactions:
    print(tx.amount, tx.from_gsm, tx.to_gsm)

# List all active numbers
numbers = await client.get_incoming_history()
for num in numbers:
    print(num.number, num.code)

get_outgoing_history(number=None, code=None, page=1) -> HistoryResponse | List[NumberWithCode]

Get outgoing transaction history. Same parameters and return types as get_incoming_history.

SyriatelCashClientSync (Sync)

All methods are the same as async client but without await:

client = SyriatelCashClientSync(api_token="your_token")
balance = client.get_balance("0991234567")
history = client.get_incoming_history(number="0991234567")

Data Models

BalanceResponse

@dataclass
class BalanceResponse:
    balance: int  # Balance in SYP

HistoryResponse

@dataclass
class HistoryResponse:
    total: int
    transactions: List[Transaction]

Transaction

@dataclass
class Transaction:
    transaction_no: str
    date: str
    from_gsm: str
    to_gsm: str
    amount: int
    fee: int
    net: int
    channel: str
    status: str

NumberWithCode

@dataclass
class NumberWithCode:
    number: str
    code: str

Error Handling

The library provides specific exception classes for different error types:

from syr_cash_api import (
    SyriatelCashError,           # Base exception
    InvalidTokenError,           # Invalid API token
    SubscriptionExpiredError,    # Subscription expired
    FetchFailedError,            # Fetch from Syriatel failed
    NotAuthorizedError,          # Account not authorized
    ServerMaintenanceError,      # Servers under maintenance
    NetworkError,                # Network issues
)

try:
    balance = await client.get_balance("0991234567")
except SubscriptionExpiredError:
    print("Subscription expired, please renew")
except InvalidTokenError:
    print("Invalid API token")
except NetworkError as e:
    print(f"Network error: {e}")
except SyriatelCashError as e:
    print(f"API error: {e.code} - {e.message}")

Advanced Usage

Custom Base URL

client = SyriatelCashClient(
    api_token="your_token",
    base_url="https://custom-api-url.com/v1"
)

Custom Timeout

client = SyriatelCashClient(
    api_token="your_token",
    timeout=60  # 60 seconds
)

Reusing Session (Async)

import aiohttp

async with aiohttp.ClientSession() as session:
    client = SyriatelCashClient(
        api_token="your_token",
        session=session
    )
    # Use client...
    # Session will not be closed when client closes

Phone Number Normalization

Phone numbers are automatically normalized:

• [phone] → 0991234567
• 963991234567 → 0991234567
• 0991 234 567 → 0991234567

Requirements

• Python 3.7+
• aiohttp >= 3.8.0
• requests >= 2.28.0

License

MIT License

Support

For API support, visit: https://api.melchersman.com/syr-cash/