lexware-office

Files (5)

• SKILL.md
• scenarios.json · evals/
• index.cjs
• lexware_office.cjs
• operator-setup.md · references/

SKILL.md (first lines)

# 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 "<api-key>"`.
3. Local console fallback:

```bash
hybridclaw secret set LEXWARE_OFFICE_API_KEY "<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
```

From HybridAIOne/hybridclaw, MIT.

More from HybridAIOne/hybridclaw