wioclinic 0.1.0

Official Python SDK for the WioClinic Developer API

WioClinic Python SDK

Official Python SDK for the WioClinic Developer API.

Requirements

• Python 3.9+
• httpx ≥ 0.25

Installation

pip install wioclinic

Authentication

Generate an API key from the WioClinic Developer Portal (Settings → API Keys). You will receive:

• Key ID — starts with pk_live_ (public, safe to log)
• Secret — starts with wcs_live_ (treat like a password)

Quick Start

from wioclinic import WioClinic

client = WioClinic(
    key_id="pk_live_2q2mfy7inwhwq76nymmob7o24e",
    secret="wcs_live_your_secret_here",
)

# List patients
page = client.patients.list(limit=10)
print(f"Found {page.total} patients")
for patient in page:
    print(patient["full_name"])

# Get a single patient
patient = client.patients.get("049ab2ab-184c-4c3b-b59b-c4be475a1b65")

# Create a patient
new_patient = client.patients.create(
    first_name="Ali",
    last_name="Yilmaz",
    date_of_birth="1990-01-15",
    gender="male",
    phone_number="[phone]",
    email_address="[e-mail]",
)

Patients

# List with filters
page = client.patients.list(
    page=1,
    limit=20,
    search="ali",       # Searches name, phone, email, national ID
    is_active=True,
)

# CRUD
patient = client.patients.get(patient_id)
patient = client.patients.create(first_name=..., last_name=...)
patient = client.patients.update(patient_id, phone_number="[phone]")
client.patients.deactivate(patient_id)

Appointments

# List appointments (date range max 31 days)
page = client.appointments.list(
    date_from="2026-05-01",
    date_to="2026-05-31",
    patient_id="...",         # optional
    status="scheduled",       # optional
)

# Get / create / update
appt = client.appointments.get(appointment_id)
appt = client.appointments.create(
    patient_id="...",
    doctor_id="...",
    appointment_date="2026-06-01",
    start_time="10:00",
    end_time="10:30",
)
appt = client.appointments.update(appointment_id, start_time="11:00")

# Lifecycle transitions
client.appointments.confirm(appointment_id)
client.appointments.check_in(appointment_id)
client.appointments.complete(appointment_id)
client.appointments.cancel(appointment_id, reason="Patient request")
client.appointments.no_show(appointment_id)

Availability

result = client.availability.check(
    doctor_id="716b0069-...",
    date="2026-06-01",
    duration=30,   # minutes, optional
)

for slot in result["available_slots"]:
    print(slot["start"], "–", slot["end"])

Clinic

clinic    = client.clinic.get()
doctors   = client.clinic.doctors()
depts     = client.clinic.departments()
rooms     = client.clinic.rooms()
treatments = client.clinic.treatments()
price_lists = client.clinic.price_lists()

Finance

# Invoices
page = client.finance.list_invoices(status="paid", from_date="2026-01-01")
invoice = client.finance.get_invoice(invoice_id)
payments = client.finance.invoice_payments(invoice_id)

# Payments
page = client.finance.list_payments(from_date="2026-01-01", to_date="2026-12-31")

# Shortcuts: client.invoices / client.payments also work
page = client.invoices.list_invoices(limit=5)

Messages (SMS / Email)

# Send SMS
client.messages.send(
    patient_id="...",
    channel="sms",
    message="Your appointment is tomorrow at 10:00.",
)

# Send email
client.messages.send(
    patient_id="...",
    channel="email",
    subject="Appointment Reminder",
    message="<p>Your appointment is tomorrow at 10:00.</p>",
)

# List sent messages
page = client.messages.list(channel="sms")

Webhooks

# List webhooks
hooks = client.webhooks.list()

# Create
hook = client.webhooks.create(
    target_url="https://example.com/wio-events",
    subscribed_events=["appointment.created", "patient.created"],
    signing_secret="my-hmac-secret",
)

# Update
client.webhooks.update(hook["id"], subscribed_events=["appointment.cancelled"])

# Test connectivity
client.webhooks.test(hook["id"])

# View recent deliveries
deliveries = client.webhooks.deliveries(hook["id"])

# Replay a failed delivery
client.webhooks.replay_delivery(hook["id"], delivery_id)

# Delete
client.webhooks.delete(hook["id"])

Pagination

List methods return a Page object:

page = client.patients.list(page=1, limit=20)

page.data        # list of result dicts
page.total       # total record count
page.page        # current page number
page.limit       # records per page
page.has_more    # True if there are additional pages

# Iterate directly
for patient in page:
    print(patient["full_name"])

# Fetch all pages manually
all_patients = []
p = 1
while True:
    page = client.patients.list(page=p, limit=100)
    all_patients.extend(page.data)
    if not page.has_more:
        break
    p += 1

Error Handling

from wioclinic import (
    WioClinicError,        # base class
    AuthenticationError,   # 401 — bad key/secret
    PermissionDeniedError, # 403
    NotFoundError,         # 404
    UnprocessableEntityError, # 422 — validation errors
    RateLimitError,        # 429
    InternalServerError,   # 5xx
    APIConnectionError,    # network issues
)

try:
    patient = client.patients.get("some-id")
except NotFoundError as e:
    print(f"Patient not found (request_id={e.request_id})")
except AuthenticationError:
    print("Check your API key and secret")
except WioClinicError as e:
    print(f"API error {e.status_code}: {e.message}")

Advanced: Custom HTTP Client

Pass a custom httpx.Client for proxy support, custom TLS, etc.:

import httpx
from wioclinic import WioClinic

transport = httpx.HTTPTransport(proxy="http://my-proxy:8080")
http = httpx.Client(transport=transport, timeout=60)

client = WioClinic(key_id=..., secret=..., http_client=http)

Context Manager

with WioClinic(key_id=..., secret=...) as client:
    doctors = client.clinic.doctors()
# connection pool is automatically closed

Supported Events (Webhooks)

Event	Triggered when
appointment.created	New appointment is booked
appointment.updated	Appointment details change
appointment.cancelled	Appointment is cancelled
appointment.completed	Appointment is marked complete
patient.created	New patient is registered
patient.updated	Patient profile is updated
invoice.created	Invoice is generated
invoice.paid	Invoice is fully paid
payment.received	Payment transaction recorded

License

MIT