Account & reference data
5 tools in this toolset, each with its tier, traits, description and arguments.
sevdesk_account_info
sevDesk account overview
Overview of the connected sevDesk account and of this server's permissions. Call it first in a session to orient yourself: it returns the bookkeeping system version (1.0 or 'Update 2.0', which decides whether documents use taxRule or taxType), the VAT regulation (regular or Kleinunternehmer, which decides the tax rules) and chart of accounts, the sevDesk users (Benutzer; their ids are needed as contactPerson on invoices, orders and credit notes) and which permission tiers (read, write, commit, external), toolsets, dry-run and confirmation mode are active, so you know what you may do before you try.
No arguments.
sevdesk_document_save
Save a document file
Save the PDF of an invoice (Rechnung), credit note (Gutschrift) or order (Angebot, Auftragsbestätigung, Lieferschein), or the XML of an e-invoice (E-Rechnung, XRechnung), as a new file in SEVDESK_OUTPUT_DIR (on a remote server: a download link), e.g. to archive or attach it. It writes only inside that folder, never overwrites a file (a taken name gets a suffix such as RE-1001-1.pdf) and never changes anything in sevDesk: PDFs are fetched as previews (preventSendBy), so nothing is marked as sent. Every call creates another file or link, so save each document once. To only look at a file, use sevdesk_invoice_pdf, sevdesk_credit_note_pdf, sevdesk_order_pdf or sevdesk_invoice_xml instead.
documentrequiredinvoice_pdf |credit_note_pdf | order_pdf | invoice_xml - Which file: invoice_pdf, credit_note_pdf, order_pdf, or invoice_xml (e-invoice XML).
idrequiredinteger- sevDesk id of the document (not its number such as RE-1001).
sevdesk_reference_lookup
Look up sevDesk ids and codes
Look up the ids and codes other sevDesk tools need instead of guessing them: tax_rules (Steuerregeln for Update 2.0, e.g. 1 = steuerpflichtig, 11 = Kleinunternehmer §19), contact_categories (Kunde, Lieferant, …), status_codes (Entwurf, offen, bezahlt per document type), document_types (RE, AN, …), users (SevUser), countries (StaticCountry), units (Einheiten), payment_methods (Zahlungsarten) and receipt_guidance (Kontierungshilfe: which booking account (accountDatev) allows which tax rules and tax rates for expense or revenue receipts (Belege); filter with accountNumber, taxRuleId and receiptType, paged with limit/offset). Use query to filter by a case-insensitive substring of names, codes or ids.
kindrequiredtax_rules |contact_categories | status_codes | document_types | users | countries | units | payment_methods | receipt_guidance - Which list to return.
queryoptionalstring- Case-insensitive substring filter on names, codes and ids, e.g. 'reverse'.
accountNumberoptionalstring- receipt_guidance only: exact account number in the chart of accounts.
taxRuleIdoptionalinteger- receipt_guidance only: accounts that allow this tax rule id.
receiptTypeoptionalexpense |revenue - receipt_guidance only: accounts for expense or revenue receipts.
limitoptionalinteger- receipt_guidance only: page size, 1–100 (default 25).
offsetoptionalinteger- receipt_guidance only: entries to skip; pass the previous nextOffset.
sevdesk_upload_request
Request a file upload
Let the user upload a file to this remote server, for the tools that take a file (sevdesk_voucher_create_draft, sevdesk_voucher_update_draft, sevdesk_einvoice_parse, sevdesk_voucher_import_einvoice): purpose receipt (Beleg, Belegbild: PDF, PNG or JPEG) or einvoice (E-Rechnung: XRechnung XML or ZUGFeRD/Factur-X PDF). Returns a link: give it to the user, who opens it in the browser they connected this server with and uploads the file there. Wait until the user says the upload is done, then pass uploadId as file. Each request expires (expiresAt). Optional count (1–10, default 1) reserves several files on one page: for count > 1, call sevdesk_uploads_list with batchId after the upload to match cleaned names to uploadIds. Uploaded files stay usable until expiry or successful attachment. Nothing is sent to sevDesk.
countoptionalinteger- Files to upload on one page (default 1). Every file uses one account slot.
purposerequiredreceipt |einvoice - receipt (PDF, PNG, JPEG) for a voucher draft, einvoice (XML, PDF) for
sevdesk_einvoice_parseandsevdesk_voucher_import_einvoice.
sevdesk_uploads_list
List files in an upload batch
Read the status of a batch from sevdesk_upload_request (count > 1). Returns one slot per requested file with its uploadId; uploaded slots include the cleaned file name, kind, size, SHA-256 and file expiry. Match names to the intended voucher drafts (Belege), then pass each uploaded slot's uploadId as file. Duplicate cleaned names need clarification; use size and SHA-256 to distinguish them. Pending slots can still be uploaded on the same page until the batch expiry. Only this connection's batches are visible. Reads no file bytes, creates no upload requests and changes nothing in sevDesk.
batchIdrequiredstring- batchId from
sevdesk_upload_request.