Sevdesk
Manage Sevdesk contacts, invoices, orders, vouchers, positions, and rendered documents
Connect Sevdesk when a project needs customer records or accounting documents from an existing Sevdesk account. Swarmz stores the account's API token in a shared workspace connection. The AI can request that connection while it builds, and a linked published app can call the supported operations through the connector gateway.
A Swarmz administrator must make Sevdesk visible before workspaces can connect it. Sevdesk doesn't need an OAuth application in Swarmz. Each workspace enters a token from its own Sevdesk account.
Before you connect
Create a 32-character API token in Sevdesk. Follow Sevdesk's authentication documentation for the current provider steps. The token can read or change the records allowed by that account, so keep it out of chat, project files, browser code, and client-side environment variables.
Swarmz calls the fixed Sevdesk API at https://my.sevdesk.de/api/v1. Use the Sevdesk API reference to check required fields and document rules before you create an invoice, order, or voucher.
Available operations
| Area | Read operations | Write operations | Limit per minute |
|---|---|---|---|
| Account | get_profile | None | 30 |
| Contacts | list_contacts, get_contact | create_contact, update_contact | 30 read, 10 write |
| Invoices | list_invoices, get_invoice, get_invoice_positions, download_invoice | create_invoice, render_invoice | 30 read, 10 write |
| Orders | list_orders, get_order, get_order_positions, download_order | create_order, update_order | 30 read, 10 write |
| Vouchers | list_vouchers, get_voucher, get_voucher_positions | create_voucher, update_voucher | 30 read, 10 write |
List operations accept bounded Sevdesk query parameters. Swarmz limits each query to 24 scalar fields, request bodies to 128 KB, provider responses to 2 MB, and each call to 10 seconds.
Document creation uses Sevdesk's factory payloads. create_invoice, create_order, and create_voucher accept the matching provider body under fields; Swarmz doesn't invent or repair missing accounting fields. download_invoice and download_order return Sevdesk's PDF response, including its Base64 content and metadata.
Connect Sevdesk
- In Settings > Integrations, select Sevdesk, then select Connect new.
- Enter a name that identifies the account or test environment.
- Enter the 32-character API token in the secure form.
- Link the connection to the project when the AI requests it.
Swarmz validates the token by reading one Sevdesk user record. An authentication error means the token is invalid, revoked, or can't access the expected account.
Build with Sevdesk
Name the records the app should use and which actions need confirmation. These prompts map to supported operations:
- “Use Sevdesk to build a customer directory that searches contacts and lets an approved user update a contact.”
- “Build an invoice workspace that shows invoice positions, creates a draft from reviewed fields, renders it, and downloads its PDF.”
- “Create an order tracker that lists orders, opens their positions, and updates a draft order after confirmation.”
- “Build a voucher inbox that lists vouchers, shows their positions, and creates a voucher from an approved accounting payload.”
The AI requests a Sevdesk connection before it adds the first provider operation. Reads run immediately during a build. Writes pause for approval and still have to satisfy Sevdesk's accounting rules.
Test Sevdesk
Use a test account or disposable draft records for write checks.
- Run
get_profileand confirm the returned user belongs to the expected account. - List contacts, open one contact, create a disposable contact, then update it.
- List invoices and positions. Create a draft invoice with a valid Sevdesk factory payload, render it, download it, and open the returned PDF.
- Create a draft order, read its positions, update it, then download its PDF.
- Create a disposable voucher, read it and its positions, then update only fields that Sevdesk permits in its current state.
If reads work and a document write fails, compare the submitted fields object with the matching Sevdesk factory schema. If a token may have leaked, revoke it in Sevdesk first, create a replacement, then reconnect Sevdesk in Swarmz.