sevdesk Python Client

Minimal Python client library for the sevdesk API using generic CRUD methods.

Installation

pip install sevdesk

Quick Start

from sevdesk import SevdeskClient

# From environment variable (recommended)
client = SevdeskClient.from_env()  # Uses SEVDESK_API_TOKEN

# Or with explicit token
client = SevdeskClient("your-api-token")

Configuration

Environment Variables

Variable	Description	Default
SEVDESK_API_TOKEN	Your sevdesk API token	(required)
SEVDESK_BASE_URL	Custom API base URL	https://my.sevdesk.de/api/v1

export SEVDESK_API_TOKEN="your-token-here"

Client Options

client = SevdeskClient(
    api_token="...",
    base_url="https://my.sevdesk.de/api/v1",  # Custom URL
    validate_resources=True,  # Validate resource names
    timeout=30.0,  # Request timeout in seconds
)

Usage

from sevdesk import SevdeskClient

client = SevdeskClient.from_env()

# List contacts (with pagination)
contacts = client.list("Contact", limit=10, offset=0)

# Iterate all invoices (auto-pagination)
for invoice in client.list_all("Invoice", status=1000):
    print(invoice["invoiceNumber"])

# Get invoice with embedded contact
invoice = client.get("Invoice", 123, embed="contact")

# Create contact
contact = client.create("Contact", {
    "name": "ACME Corp",
    "category": {"id": 3, "objectName": "Category"},
})

# Update contact
client.update("Contact", contact["id"], {"name": "ACME Corporation"})

# Delete contact
client.delete("Contact", contact["id"])

# Create invoice via Factory endpoint
client.factory("Invoice", "saveInvoice", {
    "invoice": {...},
    "invoicePosSave": [...]
})

# Send invoice email
client.action("Invoice", 123, "sendViaEmail", data={
    "toEmail": "customer@example.com",
    "subject": "Invoice",
    "text": "Please find attached..."
})

Methods

Method	Description
get(resource, id, embed)	GET /Resource/{id}
list(resource, limit, offset, **filters)	GET /Resource with pagination
list_all(resource, ...)	Auto-paginating iterator
create(resource, data)	POST /Resource
update(resource, id, data)	PUT /Resource/{id}
delete(resource, id)	DELETE /Resource/{id}
factory(resource, action, data)	POST /Resource/Factory/{action}
action(resource, id, action, ...)	POST /Resource/{id}/{action}

Resource Validation

Invalid resource names raise SevdeskUnknownResourceError with suggestions:

client.list("Contacts")  # Typo
# SevdeskUnknownResourceError: Unknown resource 'Contacts'.
#   Did you mean: Contact, ContactAddress, ContactCustomField?

Disable validation if needed:

client = SevdeskClient.from_env(validate_resources=False)

Valid Resources

AccountingContact, CheckAccount, CheckAccountTransaction, CommunicationWay, Contact, ContactAddress, ContactCustomField, CreditNote, CreditNotePos, Export, Invoice, InvoicePos, Layout, Order, OrderPos, Part, Report, Tag, Voucher, VoucherPos, and more.

Exceptions

Exception	Description
SevdeskError	Base exception
SevdeskAPIError	API returned an error (includes status code)
SevdeskAuthError	Authentication failed (401)
SevdeskNotFoundError	Resource not found (404)
SevdeskValidationError	Client-side validation error
SevdeskUnknownResourceError	Unknown resource type

License

MIT