erp-mafia/accounted/accounted-api

Accounted API integration

Accounted is Swedish double-entry bookkeeping (bokföring) as a service: BAS chart of accounts, verifikationer with legally immutable audit trails, VAT (moms), payroll (lön), invoicing, bank reconciliation, and statutory reports, exposed as a REST API designed for agents and integrations first.

This skill is for building software against the REST API (an app, a backend job, an agent tool layer). If the goal is to operate a ledger conversationally (book receipts, run month close), use the Accounted MCP connector and its workflow skills instead: install the accounted plugin or see https://app.gnubok.se/docs/api/connect-claude.

If you have used Stripe's API the shape will feel familiar: bearer keys, dated versions, idempotency keys, webhook signatures, cursor pagination. The domain rules are Swedish accounting law; the Gotchas section below stops the classic violations before you ship them.

Auth and base URL

Every request sends a bearer key:

curl https://app.gnubok.se/api/v1/companies \
  -H "Authorization: Bearer gnubok_sk_live_..."

• Base URL: https://app.gnubok.se/api/v1 (legacy machine host, permanent).

https://app.accounted.se/api/v1 serves the identical API.

• Keys are created in the Accounted dashboard under Settings -> API

(/settings/api). Two prefixes:

• gnubok_sk_live_* commits real writes.
• gnubok_sk_test_* reads real company data but forces every write into

dry-run (responses carry X-Gnubok-Mode: test). Develop and run evals with a test key; switch to live last.

• Each key carries scopes (invoices:read, invoices:write,

payroll:write, webhooks:manage, ...). Every endpoint in the index below is annotated with its required scope; a missing scope returns 403.

• Rate limit: 100 requests/minute per key. On 429, honor Retry-After.
• URLs carry the company id explicitly

(/api/v1/companies/{companyId}/invoices). A key can act on any company its user is a member of; start every session with GET /api/v1/companies to discover ids. There is no implicit "current company".

First calls, in order: GET /api/v1/health (no auth, connectivity), then GET /api/v1/companies (auth works, discover companyId).

Conventions

These rules hold across the whole surface; endpoint entries below do not repeat them.

Response envelope. Success: { "data": ..., "meta": { "request_id", "api_version", "next_cursor"?, "audit"?, "partial_expansions"? } }. Errors replace data with error (no meta; request_id moves inside error).

Errors. Stable machine codes with agent-oriented remediation:

{ "error": { "code": "PERIOD_LOCKED", "message": "Svenska", "message_en": "English",
  "details": {}, "recovery_hint": "next step", "docs_url": "...",
  "valid_alternatives": {}, "request_id": "req_..." } }

React to code, read message_en and recovery_hint, follow valid_alternatives when present (e.g. next_open_period). Standard codes on every endpoint: 400 validation, 401 bad key, 403 missing scope, 404, 429 rate limited (honor Retry-After), 500. Full catalogue: https://app.gnubok.se/docs/api/errors. Only endpoint-specific codes are mentioned per endpoint below.

Cursor pagination. List endpoints take ?cursor= and return meta.next_cursor; loop until it is absent/null. A stale or tampered cursor is NOT an error: the first page is returned again, so terminate on next_cursor, never on "page looks familiar".

Dry-run on every write that supports it (dry-run badge in the index). Send ?dry_run=true (or X-Dry-Run: true): the response is always 200 with data.dry_run: true plus a preview (would-be record, journal lines, voucher number) and the X-Dry-Run: true response header; nothing is committed. Commit by re-issuing without the flag and with the SAME Idempotency-Key (the dry run is not cached against the key). Preview first on any financial write; it is free.

Idempotency-Key. Send a fresh UUID header on every POST/PATCH/DELETE; several endpoints reject writes without one (400). Replaying the same key+body returns the original response with the Idempotent-Replayed: true header; the same key with a different body returns 409 IDEMPOTENCY_KEY_REUSE (24h window). Safe retry loop: keep the key, keep the body.

Test keys are simulation-only. With a gnubok_sk_test_* key, reads return real company data (responses carry X-Gnubok-Mode: test) and every write is forced into dry-run; writes that cannot be simulated return 403 TEST_KEY_WRITE_BLOCKED. Nothing a test key does ever persists: it is ?dry_run=true baked into the credential. Full end-to-end write tests therefore need a live key against a company you own.

Atomic writes. A mutation either commits fully or errors with no side effects. There is no partial state to clean up after an error response (bulk-create endpoints that do partial success say so explicitly).

Audit inline. Successful financial writes include meta.audit (voucher number, audit-trail URL, immutability timestamp). No follow-up read needed to confirm what was booked.

Expansion. Some list/detail endpoints take ?expand=a,b (documented per endpoint). If an expansion fails the response still succeeds and names the failed parts in meta.partial_expansions; check it before trusting expanded fields.

Report query parameters. A report read never answers an unfiltered report to a dimension filter it cannot apply: dim_no, dim_code, dimensions, project or cost_center on a report that does not document them is 400 VALIDATION_ERROR. Any other query parameter a report does not document is not applied, and the response names it in the X-Ignored-Query-Params header: check that header when a filter seems to have had no effect.

Async operations. Long-running actions (fiscal-period lock/close/year-end, imports) return 202 with an operation id; poll GET /api/v1/operations/{id} until status is succeeded/failed. The response shape is identical whether the work ran inline or queued.

Versioning. Dated versions (current: see meta.api_version). Responses carry the Gnubok-Version header; request pinning via a Gnubok-Version request header is reserved for a future breaking change and is not read today. Additive changes ship without a version bump; see https://app.gnubok.se/docs/api/versioning.

Index badges. Every operation line below carries machine-readable annotations from the spec: scope: (required key scope), risk: (low/medium/ high; confirm with a human before unprompted high-risk calls), idempotent (safe to retry), dry-run (previewable), reversible (a single follow-up call can undo it, e.g. invoice credit).

Endpoint index

API version 2026-05-12, 294 operations. Paths are shown without their /api/v1 prefix (full base URL: https://app.gnubok.se/api/v1).

Core (11)

Full detail: references/core.md

GET /companies : List companies the API key can access [scope:companies:read risk:low idempotent]
POST /companies : Create a company and set it up for bookkeeping [scope:companies:write risk:medium dry-run]
POST /companies/{companyId}/peppol/access-request : Ask the operators to switch on Peppol for the company (sending, optionally receiving) [scope:companies:write risk:medium idempotent dry-run]
GET /companies/{companyId}/peppol/registration : Read the company's Peppol receiving status: access grant, eligibility and registration [scope:companies:read risk:low idempotent]
POST /companies/{companyId}/peppol/registration : Register the company as a Peppol participant so it can receive e-invoices [scope:companies:write risk:high idempotent dry-run]
GET /companies/{companyId}/settings : Read the company settings [scope:companies:read risk:low idempotent]
PATCH /companies/{companyId}/settings : Partially update company settings (contact, invoicing, reminders, voucher series, toggles) [scope:companies:write risk:medium idempotent dry-run reversible]
PATCH /companies/{companyId}/settings/bookkeeping-lock : Set, move or remove the company-wide bookkeeping lock date [scope:companies:write risk:high idempotent dry-run reversible]
PATCH /companies/{companyId}/settings/tax-profile : Change the tax and legal profile: VAT, F-skatt, employer registration, fiscal year, accounting method [scope:companies:write risk:high idempotent dry-run reversible]
GET /health : Health check [risk:low idempotent]
GET /operations/{id} : Poll a long-running operation by id [scope:operations:read risk:low idempotent]

Journal entries (18)

Full detail: references/journal-entries.md

GET /companies/{companyId}/journal-entries : List journal entries (verifikationer) [scope:reports:read risk:low idempotent]
POST /companies/{companyId}/journal-entries : Create a draft journal entry (verifikation) [scope:bookkeeping:write risk:high idempotent dry-run reversible]
GET /companies/{companyId}/journal-entries/{id} : Retrieve a single verifikation by id [scope:reports:read risk:low idempotent]
PATCH /companies/{companyId}/journal-entries/{id} : Replace the header and lines of a DRAFT journal entry [scope:bookkeeping:write risk:medium idempotent dry-run reversible]
DELETE /companies/{companyId}/journal-entries/{id} : Cancel an uncommitted draft verifikation [scope:bookkeeping:write risk:low idempotent dry-run]
POST /companies/{companyId}/journal-entries/{id}/commit : Commit a draft journal entry [scope:bookkeeping:write risk:high idempotent dry-run reversible]
POST /companies/{companyId}/journal-entries/{id}/correct : Correct a posted journal entry (BFL 5:5 storno-then-replace) [scope:bookkeeping:write risk:high idempotent dry-run]
POST /companies/{companyId}/journal-entries/{id}/correct-metadata : Correct the description and/or date of a posted verifikat inside the same verifikat (inline rättelse) [scope:bookkeeping:write risk:high idempotent dry-run]
POST /companies/{companyId}/journal-entries/{id}/no-document-required : Mark a verifikat as "Inget underlag krävs" (no supporting document required) [scope:bookkeeping:write risk:medium idempotent dry-run reversible]
DELETE /companies/{companyId}/journal-entries/{id}/no-document-required : Remove the "Inget underlag krävs" mark from a verifikat [scope:bookkeeping:write risk:low idempotent dry-run reversible]
PATCH /companies/{companyId}/journal-entries/{id}/notes : Set, replace or clear the internal note (anteckning) on a verifikat [scope:bookkeeping:write risk:low idempotent dry-run reversible]
GET /companies/{companyId}/journal-entries/{id}/rattelse-log : Read the inline rättelse history of a verifikat, newest first [scope:reports:read risk:low idempotent]
POST /companies/{companyId}/journal-entries/{id}/redate : Move a posted verifikat to another date, and thereby another period, by storno and re-post [scope:bookkeeping:write risk:high idempotent dry-run]
POST /companies/{companyId}/journal-entries/{id}/reverse : Storno a posted journal entry [scope:bookkeeping:write risk:high idempotent dry-run]
POST /companies/{companyId}/journal-entries/{id}/strike-lines : Strike lines of a posted verifikat and add replacement lines inside the same verifikat (inline rättelse) [scope:bookkeeping:write risk:high idempotent dry-run]
POST /companies/{companyId}/journal-entries/batch-create : Create up to 50 draft journal entries (partial-success) [scope:bookkeeping:write risk:high idempotent dry-run reversible]
POST /companies/{companyId}/journal-entries/no-document-required : Mark many posted verifikat as "Inget underlag krävs" in one call [scope:bookkeeping:write risk:medium idempotent dry-run reversible]
POST /companies/{companyId}/voucher-gap-explanations : Document a gap in the verifikationsserie (BFL 5 kap 6-7 §§) [scope:bookkeeping:write risk:low idempotent dry-run]

Periods and registers (49)