sevdeskpy

A Python SDK for the sevdesk API.

Quick Start

Prerequisites

• Python 3.11+
• A sevdesk account with API token

Setup

git clone https://git.miskam.xyz/mxm/sevdeskpy.git
cd sevdeskpy
python -m venv .venv
source .venv/bin/activate   # Windows: .venv\Scripts\activate
pip install -e ".[dev]"
cp .env.example .env
# Add your sevdesk API token to .env

Run an iteration manually

# Generate types for a specific endpoint group
python scripts/generate.py --group contacts

# Validate generated types against live API
python scripts/validate.py

# Run both in sequence
python scripts/generate.py --group contacts && python scripts/validate.py

Run with Claude

Open this repo with a code agent at it, then say:

Read INSTRUCTIONS.md. Generate wrappers for all remaining endpoint groups. For each one, validate and update instructions. Keep going until all pass.

Project Structure

.
├── INSTRUCTIONS.md              ← The self-improving brain (START HERE)
├── CLAUDE.md                    ← Context file for Claude Code
├── src/
│   └── sevdeskpy/
│       ├── __init__.py          ← Public API exports
│       ├── client.py            ← Base SevdeskClient class
│       ├── exceptions.py        ← Typed error classes
│       ├── types/
│       │   ├── common.py        ← Shared models (pagination, refs, errors)
│       │   ├── contact.py
│       │   ├── invoice.py
│       │   └── ...
│       └── endpoints/
│           ├── contacts.py
│           ├── invoices.py
│           └── ...
├── scripts/
│   ├── generate.py              ← Type generation from live API
│   ├── validate.py              ← Live API validation
│   └── iterate.py               ← Prompt templates for Claude
├── tests/
├── iterations/                  ← Logs from each iteration
│   ├── iteration-001.log
│   └── samples/                 ← Raw API response snapshots
├── pyproject.toml
└── .env.example

Usage

from sevdeskpy import SevdeskClient

client = SevdeskClient(api_token="your_token")

# List contacts
contacts = client.contacts.list(limit=10)
for c in contacts:
    print(c.name, c.customer_number)

# Get a single invoice
invoice = client.invoices.get("12345")
print(invoice.invoiceNumber, invoice.status)

# Create an invoice with positions
result = client.invoices.create_via_factory(
    invoice={...},
    invoice_pos_save=[{...}],
)

# Full invoice lifecycle
client.invoices.render("12345")           # Generate PDF
pdf = client.invoices.get_pdf("12345")     # Download PDF bytes
client.invoices.send_via_email("12345",    # Send via email
    to_email="kunde@example.com",
    subject="Rechnung", text="Anbei.",
)
client.invoices.book_amount("12345",       # Book payment
    amount=1190.0, date="2026-03-30",
    check_account_id="77",
)
client.invoices.cancel("12345")            # Create cancellation invoice
client.invoices.enshrine("12345")          # Lock permanently

Contributing

The best way to contribute is to run iterations and submit PRs that include both the improved generated code AND the updated INSTRUCTIONS.md.

License

MIT