Metadata-Version: 2.4
Name: tebra_soap_api
Version: 0.1.1
Summary: Async Python wrapper for the Tebra (Kareo) SOAP 2.1 API
Author: Suleman Elahi
Project-URL: Homepage, https://github.com/Suleman-Elahi/tebra_soap_api
Project-URL: Repository, https://github.com/Suleman-Elahi/tebra_soap_api
Project-URL: Documentation, https://github.com/Suleman-Elahi/tebra_soap_api/tree/master/docs
Keywords: tebra,kareo,soap,api,healthcare,async,ehr
Classifier: Development Status :: 4 - Beta
Classifier: Framework :: AsyncIO
Classifier: Intended Audience :: Developers
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Python: >=3.10
Description-Content-Type: text/markdown
Requires-Dist: zeep>=4.2
Requires-Dist: httpx>=0.24
Requires-Dist: platformdirs>=3.0
Requires-Dist: requests>=2.28
Provides-Extra: dev
Requires-Dist: pytest>=8; extra == "dev"
Requires-Dist: pytest-asyncio>=0.23; extra == "dev"
Requires-Dist: build>=1.2; extra == "dev"
Requires-Dist: twine>=5; extra == "dev"

# `tebra_soap_api` — Async Tebra (Kareo) SOAP 2.1 Python Wrapper

A fast, lightweight, modular async wrapper around the **Tebra (Kareo) SOAP 2.1 Web Services API**, built on `zeep.AsyncClient` and `httpx.AsyncClient`.

> **Disclaimer:** This is an unofficial, community-built Python module. It is not affiliated with, endorsed by, or sponsored by Tebra. **Tebra** and **Kareo** are trademarks or registered trademarks of their respective owners. This project simply provides a Python wrapper around the publicly available Tebra SOAP 2.1 API; all product names and trademarks belong to their respective owners, and no copyright infringement is intended.

## Installation

```bash
pip install tebra_soap_api
```

## Documentation

Full API guide: open [`docs/index.html`](https://github.com/Suleman-Elahi/tebra_soap_api/tree/master/docs) in a browser (or use the `docs/` folder in the repository). It is a static, mobile-responsive site with a page per module, complete method reference, and runnable examples — no server or build step required.

## Key Features

- **Async & Concurrent**: Uses pooled HTTP/1.1 keep-alive connections (`httpx.AsyncClient`), off-loop WSDL compilation (`asyncio.to_thread`), persistent file + in-memory WSDL caching, and per-endpoint rate limiters so distinct endpoints (`GetPractices`, `GetAppointments`, `GetCharges`, `GetPatients`, etc.) execute concurrently via `asyncio.gather`.
- **Two Clean Ways to Call**:
  - **Top-level convenience methods** directly on `TebraClient`: `get_practices()`, `get_patient()`, `get_patients()`, `get_appointments()`, `get_charges()`, `get_providers()`, `get_service_locations()`, `get_payments()`, `get_transactions()`, `get_procedure_codes()`, `get_encounter_details()`.
  - **Modular resource namespaces**: `client.practices`, `client.patients`, `client.appointments`, `client.charges`, `client.encounters`, `client.providers`, `client.locations`, `client.procedure_codes`, `client.payments`, `client.documents`, `client.system`.
- **Built-in Tebra SOAP 2.1 Fixes**:
  - Automatically sends empty `Fields: {}` when `fields=None` to avoid Tebra's server-side `NullReferenceException` on `GetPractices` and other `Get*` endpoints.
  - Automatically strips placeholder/ghost records (`ID=None`) returned by Tebra on empty result sets.
  - Automatically resolves `practice_id` -> `PracticeName` (with in-memory caching) on endpoints like `GetAppointments`, `GetCharges`, and `GetTransactions` where Tebra's WSDL only accepts `PracticeName`.
  - Respects Tebra's per-endpoint throttle windows (`GetAllPatients=2500ms`, `GetPatients=1000ms`, `GetTransactions=1000ms`, others `250ms`) and retries transient throttle XML errors.
  - Supports `read_only=True` (`TEBRA_READ_ONLY=true`) to strictly block all 15+ mutating SOAP operations before any network request is made.

---

## Configuration

Provide credentials explicitly, via environment variables, or via a `.env` file:

```bash
export TEBRA_USER="user@example.com"
export TEBRA_PASSWORD="your-password"
export TEBRA_CUSTOMER_KEY="your-customer-key"
export TEBRA_READ_ONLY="true"   # optional safety guard
```

---

## Quick Start

```python
import asyncio
from tebra_soap_api import TebraClient


async def main() -> None:
    async with TebraClient(read_only=True) as client:
        # 1. List practices
        practices = await client.get_practices()

        # 2. Fetch appointments, charges, providers, and locations concurrently
        appointments, charges, providers, locations = await asyncio.gather(
            client.get_appointments(
                practice_id=7,
                start_date="2026-04-01",
                end_date="2026-04-15",
            ),
            client.get_charges(
                practice_id=7,
                from_service_date="2026-04-01",
                to_service_date="2026-04-15",
            ),
            client.get_providers(practice_id=7, active_only=True),
            client.get_service_locations(practice_id=7),
        )

        # 3. Search patients or fetch a single patient by ID
        matches = await client.get_patients(
            practice_id=7,
            first_name="Test",
            last_name="Patient",
        )
        patient = await client.get_patient(patient_id=119246)

        # 4. Stream all patients in a practice via cursor pagination
        async for p in client.iter_all_patients(practice_id=7, batch_size=250):
            print(p["ID"], p["PatientFullName"])


asyncio.run(main())
```

---

## Package Layout

```text
tebra_soap_api/
├── __init__.py          # Public exports
├── client.py            # TebraClient (core dispatcher + top-level convenience methods)
├── config.py            # TebraConfig, env/.env loader, WRITE_OPERATIONS, throttle defaults
├── exceptions.py        # Typed exception hierarchy (TebraError, TebraReadOnlyError, etc.)
├── transport.py         # FileWsdlCache, async WSDL loader, TebraAsyncTransport, EndpointThrottler
├── utils.py             # Zeep serialization, ghost-record filtering, date/field normalizers
└── resources/           # Modular domain resources
    ├── base.py          # BaseResource
    ├── practices.py     # PracticesResource (GetPractices, practice ID/name resolution)
    ├── patients.py      # PatientsResource (GetPatient, GetPatients, GetAllPatients, Create/Update)
    ├── appointments.py  # AppointmentsResource (GetAppointments, GetAppointment, Reasons, CRUD)
    ├── charges.py       # ChargesResource (GetCharges)
    ├── encounters.py    # EncountersResource (GetEncounterDetails, resolve_context, Create/UpdateStatus)
    ├── providers.py     # ProvidersResource (GetProviders, Provider/Resource Schedules & TimeOffs)
    ├── locations.py     # ServiceLocationsResource (GetServiceLocations)
    ├── procedure_codes.py # ProcedureCodesResource (GetProcedureCodes)
    ├── payments.py      # PaymentsResource (GetPayments, GetTransactions, CreatePayment)
    ├── documents.py     # DocumentsResource (CreateDocument, DeleteDocument)
    └── system.py        # SystemResource (GetThrottles, GetCustomerIdFromKey, ExternalVendors)
```
