Metadata-Version: 2.5
Name: ticketmatic-api
Version: 1.0.2
Summary: Python API client for the Ticketmatic API
Project-URL: Homepage, https://github.com/denatelier/ticketmatic-api
Project-URL: Documentation, https://denatelier-ticketmatic-api.readthedocs-hosted.com
Project-URL: Repository, https://github.com/denatelier/ticketmatic-api
Project-URL: Issues, https://github.com/denatelier/ticketmatic-api/issues
Project-URL: Changelog, https://github.com/denatelier/ticketmatic-api/releases
Author: Yves Thommes
License-Expression: MIT
License-File: LICENSE
Keywords: api,client,sdk,ticketing,ticketmatic
Classifier: Development Status :: 5 - Production/Stable
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.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Internet :: WWW/HTTP
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Typing :: Typed
Requires-Python: >=3.11
Requires-Dist: httpx>=0.27
Provides-Extra: dev
Requires-Dist: black>=26.0; extra == 'dev'
Requires-Dist: pytest-httpx>=0.30; extra == 'dev'
Requires-Dist: pytest>=8.0; extra == 'dev'
Requires-Dist: ruff>=0.15; extra == 'dev'
Provides-Extra: docs
Requires-Dist: furo>=2024.5.6; extra == 'docs'
Requires-Dist: sphinx>=7.3; extra == 'docs'
Description-Content-Type: text/markdown

# ticketmatic-api

[![PyPI](https://img.shields.io/pypi/v/ticketmatic-api)](https://pypi.org/project/ticketmatic-api/)
[![Python versions](https://img.shields.io/pypi/pyversions/ticketmatic-api)](https://pypi.org/project/ticketmatic-api/)
[![Documentation](https://img.shields.io/badge/docs-read%20the%20docs-blue)](https://denatelier-ticketmatic-api.readthedocs-hosted.com)
[![License: MIT](https://img.shields.io/badge/license-MIT-green)](https://github.com/denatelier/ticketmatic-api/blob/master/LICENSE)

A Python client library for the [Ticketmatic API](https://apps.ticketmatic.com/docs/api).

📖 **Full documentation: [denatelier-ticketmatic-api.readthedocs-hosted.com](https://denatelier-ticketmatic-api.readthedocs-hosted.com)**

The distribution is published as `ticketmatic-api`, but it installs the `ticketmatic`
package, so imports use the short name (e.g. `from ticketmatic import Client`).

This library is a port of the official [Ticketmatic PHP SDK](https://github.com/ticketmatic/tm-php) (`ticketmatic/phpsdk`) to idiomatic Python. It covers the full Ticketmatic REST API surface: contacts, events, orders, settings, and more.

> [!IMPORTANT]
> **This project is not affiliated with, endorsed by, or connected to Ticketmatic in any way.** It is an independent, community-maintained library. Ticketmatic is not involved in its development or support. Please direct all questions, bug reports, and issues regarding this library to this project's GitHub page (issue tracker) — do **not** contact Ticketmatic about this project at any time.

## Documentation

The complete documentation lives at **[denatelier-ticketmatic-api.readthedocs-hosted.com](https://denatelier-ticketmatic-api.readthedocs-hosted.com)**:

- [Installation](https://denatelier-ticketmatic-api.readthedocs-hosted.com/en/latest/guide/installation.html) and [Configuration](https://denatelier-ticketmatic-api.readthedocs-hosted.com/en/latest/guide/configuration.html)
- [Core concepts](https://denatelier-ticketmatic-api.readthedocs-hosted.com/en/latest/guide/concepts.html), [Error handling](https://denatelier-ticketmatic-api.readthedocs-hosted.com/en/latest/guide/error-handling.html), [Streaming](https://denatelier-ticketmatic-api.readthedocs-hosted.com/en/latest/guide/streaming.html) and [Widgets](https://denatelier-ticketmatic-api.readthedocs-hosted.com/en/latest/guide/widgets.html)
- [Examples](https://denatelier-ticketmatic-api.readthedocs-hosted.com/en/latest/examples.html) — a full order-to-ticket walkthrough
- [API reference](https://denatelier-ticketmatic-api.readthedocs-hosted.com/en/latest/api/index.html) — every endpoint and model

## Requirements

- Python 3.11+
- An active [Ticketmatic](https://www.ticketmatic.com/) account with API credentials (access key + secret key)

## Installation

```bash
pip install ticketmatic-api
```

Or install from source:

```bash
git clone https://github.com/denatelier/ticketmatic-api.git
cd ticketmatic-api
pip install -e .
```

## Quick Start

```python
from ticketmatic import Client
from ticketmatic.endpoints import contacts, events, orders

# Create a client
client = Client("myaccount", "your-access-key", "your-secret-key")

# List events
result = events.get_list(client)
for event in result.data:
    print(f"{event.id}: {event.name}")

# Get a single contact
contact = contacts.get(client, 12345)
print(f"{contact.firstname} {contact.lastname}")

# Create an order
order = orders.create(client, {"saleschannelid": 1})
print(f"Order created: {order.orderid}")
```

## Usage

### Authentication

The client uses [TM-HMAC-SHA256](https://apps.ticketmatic.com/docs/api) authentication. Each request is signed automatically — just provide your account code, access key, and secret key.

```python
from ticketmatic import Client

client = Client("myaccount", "access-key", "secret-key")
```

Contact [support@ticketmatic.com](mailto:support@ticketmatic.com) to obtain API credentials.

### Working with Endpoints

Endpoints are organized as module-level functions that take a `Client` as the first argument. You can pass either model objects or plain dicts:

```python
from ticketmatic.endpoints import contacts

# Using a dict (convenient for simple calls)
contact = contacts.create(client, {
    "firstname": "John",
    "lastname": "Doe",
    "email": "john@example.com",
})

# Using a model object (useful for IDE autocompletion)
from ticketmatic.models.contact import ContactQuery

result = contacts.get_list(client, ContactQuery(
    searchterm="John",
    limit=10,
))
```

### Available Endpoints

| Module | Description |
|--------|-------------|
| `endpoints.contacts` | Contact CRUD, batch operations, import, remarks |
| `endpoints.events` | Event CRUD, batch, tickets, lock/unlock, images |
| `endpoints.orders` | Order CRUD, tickets, products, payments, PDF export |
| `endpoints.diagnostics` | Server time check |
| `endpoints.tools` | Account info, custom queries, data export |
| `endpoints.jobs` | Async job status |
| `endpoints.subscribers` | Mailing subscriber sync |
| `endpoints.streams` | Event stream polling |
| `endpoints.sales.waiting_list_requests` | Waiting list management |

**Settings endpoints** (under `endpoints.settings`):

| Module | Description |
|--------|-------------|
| `settings.account_parameters` | Account-level parameters |
| `settings.products` | Products and product categories |
| `settings.vouchers` | Voucher management and codes |
| `settings.communication.*` | Documents, order mails, ticket layouts, web skins |
| `settings.events.event_locations` | Event locations |
| `settings.pricing.*` | Price lists, price types, ticket fees, order fee definitions |
| `settings.seating_plans.*` | Seating plans (with SVG, logical plans), seat ranks |
| `settings.system.*` | Contact fields, custom fields, reports, views, opt-ins, and more |
| `settings.ticket_sales.*` | Delivery scenarios, payment methods/scenarios, sales channels, etc. |

### Streaming

Some endpoints return streaming responses (newline-delimited JSON). Use them as iterators:

```python
from ticketmatic.endpoints import events

with events.get_tickets(client, event_id) as stream:
    for ticket in stream:
        print(ticket["id"], ticket["barcode"])
```

### Widget Signing

To generate signed widget URLs (using separate widget API keys):

```python
from ticketmatic import Widgets

widgets = Widgets("myaccount", "widget-access-key", "widget-secret-key")
url = widgets.generate_url("addtickets", {"event": "123", "skinid": "5"})
```

### Multi-language Support

Set a language to receive translated content:

```python
client.set_language("nl")
result = events.get_list(client)  # Returns Dutch translations
```

### Error Handling

```python
from ticketmatic import ClientException, RateLimitException

try:
    contact = contacts.get(client, 99999)
except RateLimitException as e:
    print(f"Rate limited, retry after {e.backoff} seconds")
except ClientException as e:
    print(f"API error {e.code}: {e}")
```

### Client Configuration

Each client maintains a pooled HTTP connection, so consecutive API calls
reuse the same connection. Close the client when you're done, or use it as
a context manager:

```python
from ticketmatic import Client

with Client("myaccount", "key", "secret") as client:
    result = events.get_list(client)
```

The server URL (e.g. for a staging environment) and request timeout can be
set per client:

```python
client = Client(
    "testaccount",
    "key",
    "secret",
    server="https://qa.ticketmatic.com",
    timeout=10.0,  # seconds, default 30
)
```

Setting `Client.server = "..."` before creating clients still works and
changes the default for all clients that don't pass `server=` explicitly.

## Development

```bash
# Install with dev dependencies
pip install -e ".[dev]"

# Run unit tests
pytest tests/test_models.py tests/test_widgets.py

# Run integration tests (requires API credentials)
TM_TEST_ACCOUNTCODE=xxx TM_TEST_ACCESSKEY=xxx TM_TEST_SECRETKEY=xxx pytest tests/ -m integration
```

### Releasing

Releases are published to [PyPI](https://pypi.org/project/ticketmatic-api/) by
the `Publish` GitHub Actions workflow whenever a `v*` tag is pushed. The tag
must match the `version` in `pyproject.toml`:

```bash
# 1. bump `version` in pyproject.toml and commit
# 2. tag and push
git tag v1.0.1
git push origin v1.0.1
```

The workflow runs the unit tests and linters, builds the sdist and wheel,
uploads them to PyPI via trusted publishing, and creates a GitHub Release.

## Credits

This library is a Python port of the [Ticketmatic PHP SDK](https://github.com/ticketmatic/tm-php) (`ticketmatic/phpsdk`, build 1.0.122) by [Ticketmatic BVBA](https://www.ticketmatic.com/). The PHP SDK served as the reference implementation for all API endpoints, data models, and authentication logic. Full credit to the Ticketmatic team for the original design and documentation.

This project was created with the help of [Claude Code](https://claude.ai/code) by Anthropic.

## License

MIT License — see [LICENSE](https://github.com/denatelier/ticketmatic-api/blob/master/LICENSE) for details.
