Jakob Wennberg
11b82cbb91
* feat(api): installable accounted-api agent skill + openapi-to-skill generator Three layers, per the July/August 2026 agent-skills ecosystem (skills.sh / npx skills add, as used by Stripe/Cloudflare/Supabase for their APIs): - skills/openapi-to-skill/: generic, installable skill that turns any OpenAPI spec into a consumer-side integration skill, with a portable stdlib-only inventory/condenser tool and an output template + quality checklist encoding the distill-not-restate methodology. - skills/accounted-api/: the installable skill for our own API, rendered deterministically by scripts/api-skill/generate.ts from the v1 endpoint registry + hand-authored overlays (auth, conventions, domain gotchas). CI gate: npm run apiskill:check (core-build.yml). - lib/api/v1/registry.ts: generateOpenApiSpec now emits requestBody (incl. multipart binary parts) and path parameters, and the Zod converter learned .default()/z.record()/.pipe()/.transform(), so the public spec carries request contracts instead of prose-only. Docs: /docs/api landing + /llms.txt now point agents at the skill install; corrected the stale test-key description in the landing (test keys read real data and force dry-run writes; they are not sandbox-company bound). Co-Authored-By: Claude Fable 5 <noreply@anthropic.com> * fix(skills): escape backslashes in markdown table cells (CodeQL js/incomplete-sanitization) Co-Authored-By: Claude Fable 5 <noreply@anthropic.com> --------- Co-authored-by: Jakob Wennberg <311770904+jakobwennberg-oss@users.noreply.github.com> Co-authored-by: Claude Fable 5 <noreply@anthropic.com>
39 lines
2.3 KiB
Markdown
39 lines
2.3 KiB
Markdown
## Gotchas (Swedish accounting domain)
|
|
|
|
Rules a generic REST integration will violate unless told:
|
|
|
|
- **Account numbers are strings, not numbers.** BAS accounts (`"1930"`,
|
|
`"3001"`) are identifiers; send them as JSON strings. Arithmetic on them,
|
|
zero-stripping, or number coercion corrupts postings.
|
|
- **Posted journal entries are immutable by law** (Bokföringslagen). There is
|
|
no PATCH or DELETE on a committed entry, ever. Undo with
|
|
`POST .../journal-entries/{id}/reverse` (storno), fix with
|
|
`POST .../journal-entries/{id}/correct`. Design flows around
|
|
reverse-and-repost, not edit-in-place.
|
|
- **Voucher numbers are gapless and server-assigned.** Never assume or
|
|
pre-allocate one; read it from `meta.audit.voucher_number` after commit. A
|
|
legally required gap explanation goes through
|
|
`POST .../voucher-gap-explanations`.
|
|
- **Every entry balances.** `sum(debit) === sum(credit)` to the öre, amounts
|
|
are decimal SEK numbers (max 2 decimals). Do rounding with
|
|
round-half-away-from-zero on öre; never float-accumulate line totals
|
|
client-side and "fix" the difference on a random line.
|
|
- **Period locks are a feature, not an error to retry.** Writes into a
|
|
locked/closed period return `PERIOD_LOCKED` (with `valid_alternatives`
|
|
pointing at open periods). Retrying the same request cannot succeed; either
|
|
target an open period or surface the lock to the user.
|
|
- **Drafts vs posted.** Invoices are created as drafts with
|
|
`invoice_number: null`; the F-series number is assigned atomically on send.
|
|
Journal entries follow draft -> commit. Nothing financial exists in the
|
|
ledger until the commit/send action.
|
|
- **Two invoice worlds.** `invoices` = accounts receivable (you bill
|
|
customers); `supplier-invoices` = accounts payable (you receive bills).
|
|
They are different resources with different lifecycles.
|
|
- **Swedish user-facing text.** `error.message` is Swedish by design; show it
|
|
to Swedish end users, and use `message_en` for your own logs/logic. Domain
|
|
terms in responses (moms, verifikat, kostnadsställe) are not translatable
|
|
labels but legal concepts.
|
|
- **Compliance pre-flight.** Before building your own validation for Swedish
|
|
rules, call `GET .../compliance/check`: it runs the server's own rule set
|
|
(VAT plausibility, sequence integrity, period status) and returns findings.
|