# Lexware Office > Work with Lexware Office contacts, products, invoices, quotations, bookkeeping vouchers, receipts, payment status, and guarded invoice, quotation, or expense writes through the Public API. - Skill: `hybridaione/lexware-office` (Agent Skill, multi-file: 5 files) - Install (CLI): `npx skillmds@latest add hybridaione/lexware-office` - Raw SKILL.md: https://api.skillmd.com/api/skills/hybridaione/lexware-office/raw - Safety review: pending - Works with: Claude Code, Claude.ai, OpenAI Codex - Category: Finance & Business - Author: HybridAIOne (https://skillmd.com/u/hybridaione) - Updated: 2026-09-21 - Page: https://skillmd.com/skills/hybridaione/lexware-office --- # Lexware Office Use this skill when the user wants to inspect or manage Lexware Office data for German SME accounting workflows: customers, products/articles, invoices, quotations, bookkeeping vouchers, receipt files, posting categories, payment status, and high-level revenue or income-statement summaries. Lexware Office was formerly branded lexoffice. This skill uses the current Public API gateway at `https://api.lexware.io`. ## Scope - read contacts/customers - read articles/products/services used in invoice line items - list invoices through `voucherlist` and retrieve invoice details - download invoice files from the invoice file subresource - list quotations through `voucherlist`, retrieve quotation details, and download quotation PDF files from the quotation file subresource - list and retrieve bookkeeping vouchers, including purchase invoices and receipt records - read payment status and payment items for vouchers through `/v1/payments` - read bank-linked payment items by scanning voucher payments for `partPaymentFinancialTransaction` - read posting categories for revenue and expense classification - prepare local revenue and income-statement aggregation plans from voucherlist and posting-category reads - aggregate fetched voucher pages into revenue summaries and income statements - create contacts only after explicit operator grant - create draft or finalized invoices only after explicit operator grant - create draft or finalized quotations only after explicit operator grant - log expense vouchers and upload receipt files only after explicit operator grant - match incoming bank transactions against open invoices locally, then prepare a granted voucher reconciliation-note update through the documented voucher `PUT` endpoint - update vouchers only after reading the current `version` and receiving explicit operator grant ## Credential Rules Lexware Office authenticates with a bearer API key. Store the API key in HybridClaw encrypted runtime secrets; never paste it into the prompt. Recommended setup order: 1. Browser admin: open the active HybridClaw admin URL ending in `/admin/secrets` and set `LEXWARE_OFFICE_API_KEY`. 2. Browser `/chat` or TUI fallback: `/secret set LEXWARE_OFFICE_API_KEY ""`. 3. Local console fallback: ```bash hybridclaw secret set LEXWARE_OFFICE_API_KEY "" ``` For live API calls inside HybridClaw, run the helper to build an `http_request` payload wrapper, then pass only the emitted `httpRequest` object to the built-in `http_request` tool. The helper sets `bearerSecretName: "LEXWARE_OFFICE_API_KEY"` so the gateway injects the bearer token server-side. Do not verify the key with bash/curl. The model cannot inspect the gateway secret store, and shell commands intentionally should not receive runtime API keys. Only say the secret is missing if the `http_request` tool returns a gateway error that explicitly says `LEXWARE_OFFICE_API_KEY` cannot be resolved. ## Error Interpretation - Gateway errors saying `LEXWARE_OFFICE_API_KEY` is missing or unresolved: ask the operator to store the key in the active HybridClaw runtime and restart any already-running gateway if needed. - Gateway errors saying the secret is blocked by policy: report a policy/runtime configuration problem, not a missing API key. - Lexware `401` or `403`: the gateway injected a token, but Lexware rejected it or the account lacks Public API access. Ask the operator to regenerate the key and verify the Lexware Office plan/API add-on. - Lexware `429`: back off; Lexware documents a 2-request-per-second resource endpoint limit. - Lexware optimistic-locking errors on voucher updates: read the voucher again and retry only after the user confirms the current version should be changed. ## Default Workflow 1. Start with read-only commands: `profile`, `list-contacts`, `list-invoices`, `list-expenses`, `get-payment`, `list-bank-transactions`, or `posting-categories`. 2. Use `plan` for natural-language requests when the action tier is unclear. 3. For writes, stop unless the operator has granted that exact mutation in the current task. 4. Pass `--operator-grant` only after explicit approval or an approved F14 escalation. 5. Create invoices as drafts unless the user explicitly asks to finalize/send. 6. Create quotations as drafts unless the user explicitly asks to finalize or issue the quotation. Lexware finalizes quotations at creation with `finalize=true`; its public docs say quotation status cannot be changed later through the API. 7. Only send documents or finalize documents when it is clear the user wants that. If intent is ambiguous, ask whether to keep a draft or produce the final document. The current helper does not expose a Lexware send command, so never claim that a document was sent through Lexware. 8. Before voucher updates, fetch the current voucher and include its `version` property in the write payload. 9. For income-statement or revenue questions, use `income-statement-plan` or `revenue-summary-plan`, execute the returned read requests, then run `income-statement` or `revenue-summary` on the saved JSON responses. 10. For bank-transaction matching, use `list-bank-transactions` and `match-transaction` to score candidate invoices. Lexware Public API exposes payment status and bank-linked payment items but no documented direct bank assignment mutation, so the write path records an operator-approved reconciliation note on the voucher via documented voucher update. ## Command Contract Run the colocated helper with Node: ```bash node skills/lexware-office/lexware_office.cjs --help ``` Plan a natural-language request without contacting Lexware: ```bash node skills/lexware-office/lexware_office.cjs plan "Pull outstanding invoices and chase any over 30 days late" ``` Build read requests: ```bash node skills/lexware-office/lexware_office.cjs http-request profile node skills/lexware-office/lexware_office.cjs http-request list-contacts --name Acme --size 10 node skills/lexware-office/lexware_office.cjs http-request list-products --type SERVICE node skills/lexware-office/lexware_office.cjs http-request list-invoices --status open --size 25 node skills/lexware-office/lexware_office.cjs http-request get-invoice --id 11111111-1111-4111-8111-111111111111 node skills/lexware-office/lexware_office.cjs http-request list-quotations --status open --size 25 node skills/lexware-office/lexware_office.cjs http-request get-quotation --id 11111111-1111-4111-8111-111111111111 node skills/lexware-office/lexware_office.cjs http-request download-quotation-file --id 11111111-1111-4111-8111-111111111111 node skills/lexware-office/lexware_office.cjs http-request render-quotation-document --id 11111111-1111-4111-8111-111111111111 node skills/lexware-office/lexware_office.cjs http-request list-expenses --status open --start-date 2026-01-01 --end-date 2026-03-31 node skills/lexware-office/lexware_office.cjs http-request get-payment --voucher-id 11111111-1111-4111-8111-111111111111 node skills/lexware-office/lexware_office.cjs http-request list-bank-transactions --status paid node skills/lexware-office/lexware_office.cjs http-request posting-categories node skills/lexware-office/lexware_office.cjs http-request income-statement-plan --start-date 2026-10-01 --end-date 2026-12-31 node skills/lexware-office/lexware_office.cjs income-statement --revenue-file /tmp/lexware-revenue.json --expense-file /tmp/lexware-expenses.json --start-date 2026-10-01 --end-date 2026-12-31 node skills/lexware-office/lexware_office.cjs revenue-summary --revenue-file /tmp/lexware-revenue.json node skills/lexware-office/lexware_office.cjs match-transaction --transaction-json '{"id":"tx-1","amount":119,"purpose":"Invoice 2026-042 Acme GmbH"}' --invoices-file /tmp/lexware-open-invoices.json ``` Build write requests only after explicit operator grant: ```bash node skills/lexware-office/lexware_office.cjs http-request create-contact \ --json '{"roles":{"customer":{}},"company":{"name":"Acme GmbH"},"addresses":{"billing":[{"street":"Example Str. 1","zip":"10115","city":"Berlin","countryCode":"DE"}]}}' \ --operator-grant node skills/lexware-office/lexware_office.cjs http-request create-invoice \ --json '{"voucherDate":"2026-05-21T00:00:00.000+02:00","address":{"name":"Acme GmbH","street":"Example Str. 1","zip":"10115","city":"Berlin","countryCode":"DE"},"lineItems":[{"type":"custom","name":"Consulting","quantity":8,"unitName":"hours","unitPrice":{"currency":"EUR","netAmount":120,"taxRatePercentage":19}}],"totalPrice":{"currency":"EUR"},"taxConditions":{"taxType":"net"},"paymentConditions":{"paymentTermLabel":"Due in 14 days","paymentTermDuration":14}}' \ --operator-grant node skills/lexware-office/lexware_office.cjs http-request create-quotation \ --json '{"voucherDate":"2026-05-21T00:00:00.000+02:00","expirationDate":"2026-06-20T00:00:00.000+02:00","address":{"name":"Acme GmbH","street":"Example Str. 1","zip":"10115","city":"Berlin","countryCode":"DE"},"lineItems":[{"type":"custom","name":"Consulting","quantity":8,"unitName":"hours","unitPrice":{"currency":"EUR","netAmount":120,"taxRatePercentage":19}}],"totalPrice":{"currency":"EUR"},"taxConditions":{"taxType":"net"}}' \ --operator-grant node skills/lexware-office/lexware_office.cjs http-request log-expense \ --json '{"type":"purchaseinvoice","voucherDate":"2026-05-21T00:00:00.000+02:00","totalGrossAmount":119,"taxType":"gross","voucherItems":[{"amount":119,"taxAmount":19,"taxRatePercent":19,"categoryId":"cf03a2b0-f838-474f-ac5e-67adb9b830c7"}]}' \ --operator-grant node skills/lexware-office/lexware_office.cjs http-request match-transaction \ --voucher-id 11111111-1111-4111-8111-111111111111 \ --voucher-json '{"type":"salesinvoice","voucherNumber":"2026-042","version":3,"remark":"Reviewed"}' \ --transaction-json '{"id":"tx-1","amount":119,"bookingDate":"2026-05-21","counterpartyName":"Acme GmbH"}' \ --operator-grant ``` Upload a receipt file: ```bash node skills/lexware-office/lexware_office.cjs http-request upload-file --file /workspace/receipt.pdf --type voucher --operator-grant node skills/lexware-office/lexware_office.cjs http-request attach-file-to-voucher --voucher-id 11111111-1111-4111-8111-111111111111 --file /workspace/receipt.pdf --operator-grant ``` Run offline eval scenarios: ```bash node skills/lexware-office/lexware_office.cjs eval-scenarios ``` ## Conservative Mutations These helper operations require `--operator-grant`: - `create-contact` - `create-invoice` - `create-quotation` - `log-expense` - `upload-file` - `attach-file-to-voucher` - `update-voucher` - `match-transaction` `match-transaction` is intentionally conservative: it does not claim to assign the bank transaction inside Lexware's banking module, because the Public API does not document that mutation. It writes an auditable reconciliation note to the voucher after explicit operator grant. ## Working Rules - Never print or ask for the Lexware Office API key. - Never build an Authorization header manually in a prompt. Use `bearerSecretName: "LEXWARE_OFFICE_API_KEY"`. - Prefer helper-emitted `httpRequest` payloads over handcrafted API calls. - Lexware requires the `voucherStatus` query parameter on `GET /v1/voucherlist`; requests without it fail with HTTP 400. The helper always sends it, defaulting `--status` to `any` for `list-invoices`, `list-quotations`, `list-expenses`, `list-bank-transactions`, and the voucherlist-based report plans. Pass an explicit `--status` (single value or comma-separated; run `--help` for accepted values) only to filter. - Read before write when IDs, versions, posting categories, contact IDs, or invoice recipient details are ambiguous. - If multiple contacts or invoices match, stop and ask for the exact ID before writing. - Default invoice creation to draft. Use `--finalize` only after explicit user instruction. - Default quotation creation to draft. Use `--finalize` only after explicit user instruction to issue/finalize the quotation, and ask when the wording is ambiguous. - Prefer `download-quotation-file` for quotation PDFs. Use the deprecated `render-quotation-document` endpoint only when the user specifically needs a document file id for an older workflow. - Treat receipt uploads and voucher changes as account-data mutations. - Cost per assistant run is recorded by HybridClaw `UsageTotals`; helper output includes `costMeasurement.system = "UsageTotals"` so evals can verify the accounting contract. ## References - Operator setup: [references/operator-setup.md](references/operator-setup.md) - Lexware Public API docs: https://developers.lexware.io/docs/ ## Validation Run: ```bash python3 skills/skill-creator/scripts/quick_validate.py skills/lexware-office node skills/lexware-office/lexware_office.cjs --help node skills/lexware-office/lexware_office.cjs eval-scenarios node skills/lexware-office/lexware_office.cjs http-request list-invoices --status open node skills/lexware-office/lexware_office.cjs http-request list-quotations --status open node skills/lexware-office/lexware_office.cjs http-request list-bank-transactions --status paid node skills/lexware-office/lexware_office.cjs http-request create-invoice --json '{"voucherDate":"2026-05-21T00:00:00.000+02:00"}' node skills/lexware-office/lexware_office.cjs http-request create-quotation --json '{"voucherDate":"2026-05-21T00:00:00.000+02:00"}' ```