deliveryapi 1.0.0

Official Python SDK for the DeliveryAPI courier tracking platform

deliveryapi — Python SDK

Official Python SDK for the DeliveryAPI courier tracking and webhook platform.

Installation

pip install deliveryapi

Quick Start

from deliveryapi import DeliverySaasClient

client = DeliverySaasClient(
    api_key="pk_live_...",
    secret_key="sk_live_...",
)

# Query a single tracking number
result = client.tracking.get_one("LOTTE", "1234567890")
item = result["results"][0]
if item["success"]:
    print(item["data"]["deliveryStatus"])  # e.g. "IN_TRANSIT"

# Batch query
result = client.tracking.get([
    {"courierCode": "LOTTE", "trackingNumber": "1234567890"},
    {"courierCode": "cj",    "trackingNumber": "9876543210"},
])
print(result["summary"])

Async Support

import asyncio
from deliveryapi import AsyncDeliverySaasClient

async def main():
    async with AsyncDeliverySaasClient(
        api_key="pk_live_...",
        secret_key="sk_live_...",
    ) as client:
        result = await client.tracking.get_one("LOTTE", "1234567890")
        print(result)

asyncio.run(main())

Webhook Signature Verification

from deliveryapi import verify_webhook_signature, WebhookSignatureError

# Flask example
@app.route("/webhook", methods=["POST"])
def handle_webhook():
    try:
        verify_webhook_signature(
            payload=request.get_data(as_text=True),
            signature=request.headers["X-Webhook-Signature"],
            timestamp=request.headers["X-Webhook-Timestamp"],
            secret="whsec_...",
        )
    except WebhookSignatureError:
        return "Invalid signature", 400

    event = request.json
    print(event["data"]["currentStatus"])
    return "", 200

Error Handling

from deliveryapi import (
    DeliverySaasClient,
    DeliverySaasError,
    AuthenticationError,
    RateLimitError,
    NotFoundError,
)

client = DeliverySaasClient(api_key="pk_...", secret_key="sk_...")

try:
    result = client.tracking.get_one("LOTTE", "1234567890")
except AuthenticationError:
    print("Invalid API credentials")
except RateLimitError:
    print("Rate limit exceeded — slow down requests")
except NotFoundError:
    print("Resource not found")
except DeliverySaasError as e:
    print(f"API error {e.status_code}: {e}")

Webhook Management

# Register an endpoint
endpoint = client.webhooks.create({
    "url": "https://my-server.com/webhook",
    "name": "Production server",
})
print(endpoint["id"])  # e.g. "ep_..."

# Create a subscription
sub = client.subscriptions.create({
    "courierCode": "LOTTE",
    "trackingNumber": "1234567890",
    "endpointId": endpoint["id"],
})
print(sub["id"])  # e.g. "sub_..."

# List and cancel
subs = client.subscriptions.list(status="active")
client.subscriptions.cancel(sub["id"])

Supported Couriers

couriers = client.couriers.list()
for c in couriers["couriers"]:
    print(c["id"], c["displayName"])

License

MIT