Recording session runbook
sevDesk has no sandbox and no developer test account: every write is real, and finalized documents cannot be deleted. This project therefore checks its assumptions about the API in one recording session on a free 14-day trial account, with three tools. This page is the maintainer's runbook for it.
| Command | What it does | Writes? |
|---|---|---|
pnpm probe | Asks sevDesk the open questions of spec/deviations.md and writes a Markdown report with scrubbed evidence. | Only with --allow-writes (tagged data) |
pnpm fixtures:record | Records scrubbed read responses as test fixtures into test/fixtures/recorded/<date>/. | Never |
pnpm test:live | Calls every read tool through the real server and checks the output; optionally runs the write lifecycle through the tools. | Only with the two lifecycle flags (tagged data) |
Caution
Never point any of this at a production account. The read-only parts are harmless anywhere, but the write parts create, finalize, pay and cancel real documents.
Safety rails (built in)
- The tools read only these variables:
SEVDESK_API_TOKEN(orSEVDESK_API_TOKEN_FILE),SEVDESK_BASE_URL,SEVDESK_RATE_LIMIT,SEVDESK_TIMEOUT_MS. Tier switches in your shell (SEVDESK_ALLOW,SEVDESK_CONFIRM,SEVDESK_READ_ONLY, …) are ignored. - Read-only runs force
SEVDESK_READ_ONLY=1: the HTTP client refuses every request that changes data before it is sent. PDFs are always fetched withpreventSendBy=true. - Write runs need an explicit flag and
SEVDESK_LIVE_I_UNDERSTAND_WRITES=1, print a warning, and refuse an account that already holds more than 60 invoices plus contacts they did not create (SEVDESK_LIVE_MAX_EXISTING_RECORDSchanges the limit). They enable thewriteandcommittiers. Theexternaltier (e-mail) is enabled only when you pass an address of your own (pnpm probe --probe-email,SEVDESK_LIVE_EMAIL_TOfortest:live), and then exactly one e-mail goes to that address, never to a contact. Nothing is enshrined. The only export is the DATEV CSV job of the M4 probe and scenario (it starts a job; never withenshrineDocuments). - Everything written is named after a run tag such as
MCP-E2E 20261120-1432-k3f9and listed in a cleanup list (end of the probe report, end of thetest:livelog). - Recordings and reports are scrubbed (
scripts/lib/scrub.ts): names, e-mails, phones, IBAN/BIC, VAT and tax ids, addresses, free texts, bank purposes, file names, URLs, document numbers and the account id are replaced by obvious fakes; the token is refused at write time.
1. Create the trial account (about 10 minutes)
- Sign up for the free 14-day trial on sevdesk.de with an e-mail alias you use for nothing else. The trial includes the API (Buchhaltung Pro features).
- Use fake company data (Musterfirma GmbH, Musterstraße 1, 10115 Berlin). Do not enter real customers, real bank accounts or real receipts: whatever the account holds can end up in a recording, scrubbed or not.
- Check the bookkeeping system version in the settings: a new account should be on Update 2.0 (the probe report states it too).
- Switch the account to standard VAT (required for everything after finalizing): Einstellungen
→ Unternehmen → "Buchhaltung & Steuern" → Umsatzsteuer "Standard 19%". The 2026-11-07
trial started as a Kleinunternehmer (small-business scheme): drafts with tax rule 1 were saved,
but every
sendByfailed with 422 "Tax rule 'USTPFL_UMS_EINN' is not valid for account '4400' with taxation scope 'SMALL_BUSINESS'" (D-067), so the payment, cancellation, reminder and credit-note probes all came back inconclusive.GET /SevClientshows the setting assmallSettlement("1"= small business). - Confirm the account's e-mail address in sevDesk before any e-mail probe: until it is
confirmed,
sendViaEmailanswers 400 "Confirm your email address to send mails." (D-069). - Add a cash register (Kasse) or an offline bank account: required for the payment probes and the lifecycle scenario. Give the cash register a positive opening balance (one cash entry is enough): a credit note payout takes money out of it.
- Optional, so more read probes give an answer instead of "inconclusive": one person contact (not
only organisations); two or three cash entries or a small CSV of bank transactions with
different value and entry dates; one fake receipt as a voucher (Beleg); one invoice marked as
an e-invoice (E-Rechnung) and finalized, for the
getXmlshape.
2. Create an API token (about 5 minutes)
-
If the trial allows more users, create a dedicated user (e.g. "MCP API") and use its token, so the token can be revoked without touching your login. Otherwise use the owner's token.
-
In the web app: Settings → Users → the user → API token. sevDesk tokens never expire and have no scopes: treat it like a password.
-
Store it in a file only you can read, outside the repository, never in
.envfiles of this repository, shell history, issues or chat:umask 077 && pbpaste > ~/.config/sevdesk-trial.token # or paste with an editorexport SEVDESK_API_TOKEN_FILE=~/.config/sevdesk-trial.token
3. Run the session (about 20 minutes)
Run everything from the repository root after pnpm install. Each step takes a few minutes at
the client's pace of about 4 requests per second. Behind a filtering HTTP proxy, add
NODE_USE_ENV_PROXY=1 to every command: Node's fetch ignores HTTPS_PROXY without it.
# 3.1 See every probe and what is never probed (no token needed, nothing sent).pnpm probe --list# 3.2 Read-only probes: harmless, run them first.pnpm probe --out probe-report-read-only.md# 3.3 Write probes: create tagged drafts, finalize/pay/cancel some of them, then re-run the reads.# --probe-email (optional) also sends ONE invoice e-mail to the account's own login address,# to record the sendViaEmail answer; without it nothing is e-mailed.SEVDESK_LIVE_I_UNDERSTAND_WRITES=1 pnpm probe --allow-writes --probe-email login@example.org \ --out probe-report.md# 3.4 Optional: a burst of 40 requests to see whether sevDesk rate-limits (D-022).pnpm probe --only read-rate-limit-burst --out probe-report-rate-limit.md# 3.5 Fixtures: first the plan, then the recording (read-only; PDFs only of finalized documents).pnpm fixtures:record --dry-runpnpm fixtures:record # writes test/fixtures/recorded/<date>/…# 3.6 Live read-only checks of every read tool through the real server.pnpm test:live# 3.7 Lifecycle through the write tools (contact → draft → PDF preview stays a draft → finalize →# partial + full payment → reminder → cancellation → credit note). Add# SEVDESK_LIVE_EMAIL_TO=login@example.org to also e-mail the paid invoice to yourself.SEVDESK_LIVE_LIFECYCLE=1 SEVDESK_LIVE_I_UNDERSTAND_WRITES=1 pnpm test:liveNotes:
- Step 3.3 runs the write probes first and then every read probe again, so the read probes find
the documents the write probes created (for example that every cancellation invoice points to
its original). Each write probe creates its own data; one failing probe does not stop the
others (it is reported as
error).pnpm probe --listshows the question of each probe. - The write probes cover: draft numbering (B4/D-027: what sevDesk does with documents saved
without a number; the write tools themselves leave only invoices unnumbered and reserve the next
order and credit note number, D-066) and
getNextOrderNumber; getPdf previews of 2.0 drafts (B1); position price fields pershowNet(B8); updates throughsave*with an id and omitted fields; the address of API-created drafts; credit notes withoutdeliveryDate; payments (answer, date formats, the calendar day of a 12:00 Berlin date, credit note payout sign, bookings on a cash register andresetToOpen, payments on a reminder, foreign currency); cancellation; credit notes from invoices; reminders (query vs body); invoices from orders (RE or ER for a full invoice);DELETEof a draft; parts (pricevs net/gross); contacts (assigned customer number, partialPUT, unknown fields); thesendViaEmailanswer (only with--probe-email). - Step 3.7 drives the M3 write tools with the arguments in
ARGSat the top oftest/live/lifecycle.test.ts. If a tool's arguments change, adjust them there. Refusing to write: the account already holds …means the account does not look like a fresh trial. Stop and check which account the token belongs to.- E-mail on a trial account: after the sender address is confirmed (step 1.5), a trial can only
e-mail its own login address; any other recipient is refused with 400 "During the test phase,
you can only send emails to your own email address." (D-069). A refused send changes nothing:
run the probe again with
--only write-send-email-shape. - With automatic Festschreibung on (as on the 2026-11-07 trial), finalizing (
sendBy) enshrines every invoice and credit note: they can only be cancelled or left alone, not reset or deleted. Payments andresetToOpenstill work on them (D-059, D-060). - The 2026-11-07 session needed three write runs: one on the Kleinunternehmer account, one after switching to standard VAT, and e-mail re-runs after confirming the sender address. Doing steps 1.4 and 1.5 first saves the extra runs.
3a. M4: receipts, reconciliation, exports, e-invoices (about 30 minutes)
The M4 probes and the M4 lifecycle scenario cover vouchers, bank transactions, the DATEV export and e-invoices. They need company data and a DATEV configuration first; preparation, runs, what they create and what to commit are on their own page: M4 runs.
3b. M5 remote check (about 60 to 90 minutes)
The remote mode is checked by hand once against the same trial account: the image, a tunnel, a claude.ai connector and Claude Code over HTTP. The steps are on their own page: M5 remote check.
4. Review before anything is shared (about 15 minutes)
-
Read the end of the
fixtures:recordoutput: the line starting withReview: text under these keyslists keys the scrubber did not know. Check that nothing useful was lost and nothing personal kept. -
Search the recordings and reports for anything of yours (name, e-mail domain, company, street, IBAN, phone):
rg -n -i 'yourname|yourcompany|@yourdomain|DE\d{2} ?\d{4}' test/fixtures/recorded probe-report*.md -
Open a few fixtures: keys,
nulls and string scalars ("100","0"/"1") must look exactly like sevDesk sends them; names should readMusterfirma 1 GmbH, e-mailsperson1@example.com, PDF content a tiny fake PDF, XML only its root element. -
Skim the probe report: every
contradictedanderrorresult needs a follow-up inspec/deviations.md(the "By deviation entry" section groups the findings per entry).
5. What to commit, and what never
Commit, after the review, in a PR: test/fixtures/recorded/<date>/** (the recorder refuses to
overwrite existing files; --force replaces a session's files); the updates to
spec/deviations.md, tests and code that the findings call for; and the findings themselves in
the PR description (or the scrubbed report as a PR attachment).
Never commit the token, a token file, .env files or shell history excerpts; unscrubbed responses
(test/fixtures/_raw/ is git-ignored for that reason), raw PDFs or XML from the account,
screenshots of the trial; or the cleanup list's account ids next to any personal data.
Recorded fixtures do not replace the committed community/spec fixtures automatically: each
recorded file says in its _provenance.note which committed fixture it mirrors, and replacing one
is a normal code change with its tests. Every recorded file must run through its production parser
in a contract test (test/contract/recorded-fixtures.test.ts for the 2026-11-07 session, which
fails when a recorded file has no contract); a recorded shape a parser rejects is a contract break
to fix in the parser, pinned with it.fails until then. Findings go into spec/deviations.md with
the source "recorded <date>, trial account, Update 2.0 (probe <id>)".
6. Optional: the live environment for the CI workflow
.github/workflows/live-e2e.yml runs pnpm test:live by hand (Actions → Live E2E → Run
workflow; tick lifecycle for the write scenario). It skips with a notice when no token is set.
To use it during the trial:
- Repository settings → Environments → New environment
live: required reviewer (you), deployment branchesmainonly. - Add the environment secret
SEVDESK_API_TOKEN(the trial token). - Remove the secret when the trial ends.
7. End the trial (about 5 minutes)
- Revoke the API token in the web app (or delete the dedicated API user).
- Delete the
SEVDESK_API_TOKENsecret of theliveenvironment and the local token file (rm ~/.config/sevdesk-trial.token). - Let the trial expire without booking a plan, or delete the account in the web app's account settings (contact sevDesk support if the option is missing). Finalized test documents cannot be deleted one by one; they disappear with the account.