Python SDK

pip install threeqpr

from threeqpr import ThreeQPRClient

client = ThreeQPRClient(api_key="YOUR_API_KEY")
# Or set the THREEQPR_API_KEY environment variable and omit api_key

code = client.qpr_codes.create(
    name="Retail Product Assistant",
    prompt="You are a helpful product assistant for Acme Store. Help customers with product info, sizing, and recommendations.",
    template="retail",
)

print(code.scan_url)       # https://3qpr.com/s/ab3x9k
print(code.qr_image_url)   # https://api.3qpr.com/qr/ab3x9k.png
print(code.id)             # qpr_01HXYZ789ABC

codes = client.qpr_codes.list(limit=50)
for code in codes.codes:
    print(f"{code.name}: {code.scans_total} scans")

analytics = client.analytics.get(
    qpr_code_id="qpr_01HXYZ789ABC",
    period="30d",
)
print(f"Total scans: {analytics.total_scans}")
print(f"Unique scanners: {analytics.unique_users}")
print(f"Conversion rate: {analytics.conversion_rate:.1%}")

webhook = client.webhooks.create(
    url="https://yourapp.com/webhooks/3qpr",
    events=["scan.created", "conversation.completed"],
)
print(f"Webhook secret: {webhook.secret}")  # Store this securely!

from fastapi import FastAPI, Request, HTTPException
from threeqpr import WebhookVerifier

app = FastAPI()
verifier = WebhookVerifier(secret="whsec_...")

@app.post("/webhooks/3qpr")
async def handle_webhook(request: Request):
    payload = await request.body()
    signature = request.headers.get("X-3QPR-Signature", "")

    try:
        event = verifier.verify(payload, signature)
    except ValueError:
        raise HTTPException(status_code=400, detail="Invalid signature")

    if event["event"] == "scan.created":
        scan_data = event["data"]
        print(f"New scan: {scan_data['short_id']}")

    return {"received": True}

from threeqpr.exceptions import (
    AuthenticationError,
    RateLimitError,
    APIError,
)

try:
    code = client.qpr_codes.create(name="Test", prompt="...")
except AuthenticationError:
    print("Invalid API key")
except RateLimitError as e:
    print(f"Rate limited. Retry after {e.retry_after}s")
except APIError as e:
    print(f"API error {e.status_code}: {e.message}")