Skip to content

Fortnox (accounting) ​

Reads a company's bookkeeping out of Fortnox as a SIE4 export, sums it per account, cost centre and month, and lands the result into a scope through the consuming vertical's own operation.

Verified against a live company — and it found two bugs

Every claim below has now been checked against api.fortnox.se, and two of them were wrong. The SIE4 export is PC8/CP437, not ISO-8859-1 — decoding it as latin1 turned every ö into ” in account names, silently, with no error anywhere. And companyinformation returns explicit null for unset text fields, which the response schema rejected outright. Both are fixed; both were invisible to a mock, because the mock encoded latin1 too and so agreed with the reader while both disagreed with Fortnox.

The credential model is now proven rather than argued: grant_type=client_credentials with a TenantId header really does mint, with no refresh token in the response.

At a glance ​

ProviderFortnox (Swedish accounting), REST API v3 + SIE4 export
CategoryAccounting
StatusLedger live-verified against a Fortnox test company; supplier invoices, their files and the write-back verified against the mock only — poll-only, and it writes to Fortnox only for an invoice binding that declares writeback
Package@substrat-run/connector-fortnox — 0.x
Consumesnothing — this connector answers no event
Registered withnothing — it is a ConnectorSweeper, bound into the platform sweeper

What it consumes ​

Nothing, and that is the design. Every other connector so far answers an event: a vertical does something, the engine emits, the connector effects it outside. This one runs the other way. Nobody inside a scope initiates it — a vertical does not ask for last month's bookkeeping the way it asks for a signature. The books change at Fortnox, and the platform finds out by looking.

So there is no registerConnector call and no dispatch handler. sweepFortnoxLedger is a ConnectorSweeper, the deployment binds it into the platform sweeper beside Scrive's, and that is the entire trigger surface.

What replaces the event is a binding: a one-time, explicit declaration of which scope this connection syncs into, which operation the ledger lands through, and which permission that operation checks.

ts
await bindFortnoxScope(host, {
  connectionId, tenantId, scopeId, vertical,
  operation: 'ledger/record-period',   // yours
  permission: 'ledger:record',         // what it checks
});

bindFortnoxScope refuses when the connection does not hold that permission on that scope. A sweep can therefore never be configured into a state where it fetches a year of bookkeeping and then cannot write it down — the failure lands in the operator's hands, naming what to grant, instead of in a background timer nobody is watching.

How a binding comes into existence ​

Declare it, and the platform makes it. The consuming vertical names the landing in its module manifest:

ts
connections: [
  { provider: 'fortnox', operation: 'ledger/record-period', permission: 'ledger:record' },
],

The optional options.kind selects the data the operation receives: ledger (the default, including existing declarations) or supplier-invoice. For an invoice landing, declare:

ts
connections: [
  { provider: 'fortnox', operation: 'invoices/record', permission: 'invoices:record',
    options: { kind: 'supplier-invoice', firstPass: 'all' } },
],

options.firstPass says how far back an invoice binding's first pass reads: a number of days, or 'all' for every invoice the company has. Left out it is 90 days. Changing it re-binds the landing, and a re-bound landing starts its first pass again, which is also how a vertical reads further back after the fact. The landing upserts, so the invoices it already holds only cost a resend.

A ledger binding can ask for more than the monthly sums:

ts
connections: [
  { provider: 'fortnox', operation: 'ledger/record-file', permission: 'ledger:record',
    options: { form: 'sie', years: 'all' } },
],

See the whole SIE file. Changing either option re-binds the landing, and a re-bound landing starts over. A re-bind that changes nothing keeps the years already landed.

The platform validates the option before binding. A connection can have one Fortnox landing kind per scope. An omitted kind means ledger, including when a scope is already bound for invoices. A declaration or staff bind that asks for the other kind is refused before a new permission is granted: use a separate scope for the other kind. A single scope cannot declare both kinds at once. Ledger polling reads only ledger bindings, and the invoice sweep reads only invoice bindings. An unrecognized stored kind fails closed, naming the kind, without fetching or delivering anything.

This option requires the platform and @substrat-run/connector-fortnox release containing this change (see their release changelogs). Older platforms reject kind as an unknown binding option: the connection's sweep row says its declared landing could not be bound, and the staff failure names the invalid option. A platform whose connector predates the invoice sweep seats an invoice binding but polls nothing for it, and reports it as unsupported.

The whole SIE file ​

form: 'sie' lands the year's SIE4 file itself, decoded to text, in one call parsed by fortnoxSieFile, in place of the FortnoxLedgerPages:

ts
{
  syncId,                                // the content hash: unchanged books, same id
  connectionId,
  company: { name, organizationNumber },
  financialYear: { id, from, to },
  sie,                                   // the whole file
}

The summary form lands monthly sums, which is what a chart wants, and it leaves out what the file holds beyond them: the opening and closing balances, and every voucher. A vertical that needs those already reads SIE, because that is how its users bring in the books by hand, so the file goes through the same door. There is no window and no paging: the file is the year, and the landing takes it or refuses it whole.

years says how many financial years before the current one the binding keeps, or 'all'. Left out, it keeps none.

  • One older year per pass. A year is one large download and a pass runs on a timer, so a company's history lands newest year first, one year per pass. After that each older year is read once a day. A closed year rarely moves, but Fortnox does not stop it from moving.
  • The current year is read every pass, and lands only if the file changed.
  • The cursor is per year, written after that year landed, so a refused file is offered again next pass and the other years are not held back. A landing should be idempotent on syncId.
  • The current year is the one that overlaps the calendar year, as for a summary, which for a broken financial year means the newest one. The year before it is an older year, and it needs years to be kept up to date past the turn of the year.

What an invoice binding lands ​

Each pass lists the supplier invoices changed since the binding's cursor, reads each one's rows, and lands them in one call to the declared operation, parsed by fortnoxSupplierInvoicePage:

ts
{
  connectionId,                              // the company's connection
  company: { name, organizationNumber },
  invoices: [{
    givenNumber,                             // Fortnox's number for the invoice in this company
    supplierNumber, supplierName, invoiceNumber,
    invoiceDate, dueDate,
    total: { amount, currency },             // in the invoice's own currency
    balance?, vat?,                          // the same; absent when Fortnox states none
    ocr, booked, cancelled, credit, paymentPending,
    comments,                                // the old single comment, while it has one
    commentLog: [{ comment, createdAt, userName }],
    voucher: { series, number, year } | null, // year is Fortnox's number for the financial year;
                                             // series and year are null when Fortnox states none
    project, costCentre,
    rows: [{ account, accountDescription, costCentre, project, transactionInformation,
             amount }],                       // debit-positive, in SEK
  }],
}

balance is the only fact on an invoice that says whether it has been paid. commentLog is where Fortnox's web UI writes new comments since September 2026, so an integration that reads only comments misses them.

Upsert by (connectionId, givenNumber). An invoice arrives again every time it changes in Fortnox (booked, cancelled, edited). The cursor also reads a few minutes back, so a change made in the same minute as the last pass is never missed, which means an unchanged invoice can arrive twice. A pass with no changes makes no call to the operation.

  • The first pass reads invoices changed in the last 90 days, or as far back as options.firstPass says. With 'all' the list carries no date filter until the run has drained.
  • The cursor moves only after the operation accepted the page. An operation that throws leaves it in place, and the next pass reads the same invoices again.
  • Rate. Every read of a pass is paced to Fortnox's documented limit, 25 requests in any 5 seconds, and a 429 is waited out for as long as its Retry-After says, up to three times per request. The pacing sees only this pass. A ledger connection to the same company, or the company's own integrations, spend from the same limit, and their share is absorbed by the retry rather than prevented. A pass reads at most 200 invoices per connection, about 40 seconds at the limit, and starts no new read after 90 seconds. When it stops, the invoices read so far land and the next pass resumes after them. A read already under way still finishes its own retries, so a Fortnox that is both throttling and timing out can stretch one pass by a few minutes past that, never more. A larger change set (a first pass over a busy company) lands over several passes, oldest number first, until it is through.
  • A read that fails. Invoices read before it still land, and the cursor moves past them. An invoice deleted between the list and its read (404) is stepped over. Any other failure (a 429 past its retries, a server error, an invoice the connector cannot read) fails the scope's row naming the invoice number, and the next pass starts from that invoice. One that can never be read fails every pass by its number rather than being skipped, because a skipped invoice would not reach the operation until someone edited it in Fortnox.
  • Read-only unless declared. A binding with no writeback writes nothing to Fortnox.

The invoice's file ​

The operation asks for files in its answer. It names each invoice whose file it wants, and the entity the file lands on:

ts
return { files: [{ givenNumber: '12', entity: { entityType: 'invoice', entityId } }] };

The entity's type must be a declared attachment target the landing's key can write. An answer that names no files, or that does not parse as fortnoxSupplierInvoiceLandingAnswer, asks for none.

For each one, the pass reads GET /3/supplierinvoicefileconnections?supplierinvoicenumber= and then GET /3/archive/{FileId} for every file connected to the invoice, and uploads the bytes to the entity as the connection, with internal visibility. No operation is called afterwards: the attachment on the entity is the record.

  • The queue. A file is asked for once, when its invoice lands, and an unchanged invoice does not land again. So what has been asked for is held on the binding until it has been read, across passes. A pass reads the queue before it lists new invoices, so the queue stays within one pass's budget. An invoice costs one read and a file two from the pass's 200, which puts a first pass over 2,000 invoices with one file each at about eight hours. The budget is checked before each file, so an invoice with many files is read across passes rather than overrunning one. A re-bind keeps the queue.
  • A file lands once per entity. What has landed is recorded per invoice, by FileId, so an invoice that changes and is asked about again lands only files connected since. Naming another entity for the invoice lands its files there too. Upload is still at least once: a pass that stops between an upload and its record uploads that file again on the next pass.
  • A file that cannot be read stays queued and fails the scope's row by the invoice's number, and the pass moves on to the next one. The invoices keep landing. After eight failed passes it is stepped over, with the last error in the pass's result, so files that never read cannot use up every pass's budget.
  • A refused read (401/403) stops the files for that pass, because it is the company's consent and every other file would answer the same. The scope's row says the consent must cover connectfile and archive. A company that consented before those scopes were asked for has to connect again; nothing compares granted with requested scopes, so this row is how it shows.
  • Stepped over, with the reason in the pass's result (a pass that only stepped over a file is reported, not counted as unchanged): a file gone from the archive, and a file over 16 MiB, which is the most a pass holds. An invoice with no file connected asks nothing more until it next lands. Whether connecting a file later moves an invoice's lastmodified is not verified, so a file connected after the fact may wait for the next change to the invoice.

Each client company is its own connection, told apart by its externalAccountRef. On the connector pass after a company's connection appears — through the dashboard's Connect, a connect link the vertical mailed, or the vertical's own relay — the platform grants that connection the declared permission on every primary, active install of the vertical in the tenant and binds it, through bindFortnoxScope and its grant check. A bureau with ten companies gets ten bindings into the same install, and each one is swept with its own company's credential: the binding records the company, so the sweep opens that connection and no other. The landing is part of the vertical's permission registry, so PERMISSIONS.md shows it and a change to it is acknowledged at promote. See connection landings.

An install that is already running picks the landing up with no reconcile, promote or command: pushing and promoting the version that declares it is enough, and the next pass (every quarter hour) grants and binds every company connected so far. A binding written by hand before bindings recorded the company is re-written once on that pass.

Each due pass writes one row per connection, shown in Health › Connections: ok when every polled binding, ledger or invoice, landed or was unchanged, skipped when the connection has no binding, and failed, naming the scope, when a scope could not be landed in or a declared landing could not be granted or bound. An operation that refuses the invoice page fails its scope this way, naming the scope.

Writing back ​

A vertical that decides on invoices, a board approving them for example, declares two more operations on the landing:

ts
options: {
  kind: 'supplier-invoice',
  writeback: { read: 'invoices/writeback', record: 'invoices/writeback-recorded' },
},

Both run as the connection, so both check the landing's permission. Every pass, idle ones too, the sweep calls read with { connectionId, company } and does what it answers, parsed by fortnoxInvoiceWriteback:

ts
{
  hold: [{ givenNumber }],        // keep it from being paid until it is decided
  decisions: [{
    key,                          // yours, handed back in the receipt
    givenNumber,
    book,                         // book it, unless it already is
    release,                      // clear the hold this binding set
    comment,                      // one entry for the comment log, or null
  }],
}

The sweep asks rather than listens. A hosted connector has no delivery of a scope's events, and it does not need one: what the operation still answers is what is still to do, so a lost pass costs fifteen minutes and nothing else. The operation answers for the company it is given, because GivenNumber repeats between companies and a bureau holds many in one install.

  • A hold sets DisablePaymentFile, which keeps the invoice out of payment files and out of Fortnox's payment view. Only a hold this binding set is ever cleared. The flag is also used on purpose, for a supplier paid by direct debit for example, and a new invoice inherits it from the supplier, so a block the sweep finds stays. A found block is read again each pass while the invoice is listed in hold, and if someone lifts it the sweep sets its own. What it set is remembered per connection, written before the PUT and marked confirmed after it: a pass that dies between them, or a PUT that gets no clear answer, leaves an unconfirmed note that the next pass checks against the invoice, never a block nobody knows about.
  • A decision's order is the order that fails safe: book, clear the hold, add the comment. An invoice that could not be booked stays held, and the comment log is append-only, so it goes last. Each step looks first, so a pass cut off part-way repeats nothing: a booked invoice is not booked again, and a comment already in the log is not added.
  • The receipt goes to record, parsed by fortnoxInvoiceWritebackReceipt, as { key, status: 'done' | 'failed', error }. A refusal in Fortnox's own words (a 4xx, a locked period for example) is failed at once, because the next pass would get the same answer and a person has to act. Anything else, an outage for example, is tried on the next passes, and is failed after eight. Answering the same key again after a failed is how a vertical retries.
  • A write that fails also fails the scope's row by the invoice's number. It never stops the invoices landing, and a landing that fails never stops the writes.
  • Budget. A hold costs two calls and a decision up to five, from the pass's 200, and the 90-second deadline applies. What does not fit is answered again next pass.

A company that books only attested invoices cannot use the release yet

Measured in a Fortnox sandbox on 2026-11-11: there, bookkeep refuses an invoice nobody has attested, and once an invoice is attested Fortnox lets a write change only its OCR, invoice number and due date. So the hold can be set before attest and never cleared after it. An approved invoice is booked, stays blocked from payment, and gets no comment, and the vertical receives failed with Fortnox's message. An invoice attested before it is held cannot be held at all. Whether a company without that rule can clear a booked invoice's block is not measured yet. See what's missing.

Bind a hosted connection by hand ​

The declaration is the normal path. A staff or service operator can still bind a company's connection directly, for a vertical that declares nothing:

sh
substrat connection bind <connection-id> --tenant <tenant-id> --scope <scope-id> \
  --operation ledger/record-period --permission ledger:record
substrat connection bindings <connection-id> --tenant <tenant-id>

The connection must already hold ledger:record on that scope, from a declaration or the vertical's own relay. This command grants nothing. It verifies the live scope projection, refuses preview/fork and mismatched-vertical targets, and records the binding change in the admin log. The read reports permissionHeld alongside each stored binding. See the hosted Planima binding door for the HTTP paths and deployment prerequisite. Planima-specific options are rejected for Fortnox.

The credential ​

Fortnox's usual flow is OAuth2 authorization-code: a person signs in, you store an access token and a refresh token, and you refresh forever. This connector deliberately does not do that.

Fortnox refresh tokens are single-use and rotating — each refresh mints a new one and invalidates the old. Two concurrent refreshes therefore race: one wins, the other receives invalid_grant and writes an already-dead token, and the connection is bricked until someone reconnects it by hand. Every integration built that way carries the same three mitigations (coalescing concurrent refreshes per company, optimistic locking on the token write, a distinct "reconnect Fortnox" error).

This connector holds no refresh token, so it cannot reach that state. Fortnox supports grant_type=client_credentials against a service consent, and a token minted that way comes from three static values:

FieldWhat
clientIdFrom the Fortnox Developer Portal — the integration's identity
clientSecretFrom the Developer Portal — sealed at rest by the host's SecretBox
tenantIdThe company's numeric DatabaseNumber, sent as the TenantId header
POST https://apps.fortnox.se/oauth-v1/token
Authorization: Basic base64(clientId:clientSecret)
TenantId: 123456
grant_type=client_credentials
→ { access_token, token_type, expires_in: 3600, scope }     // note: no refresh_token

An access token lives an hour and is minted on demand, cached for the life of one sweep pass. One client pair serves a whole fleet; tenantId is the only part that differs per company.

What is never stored: nothing sensitive beyond the client secret. A ledger binding reads bookkeeping totals — accounts, cost centres, months, sums. An invoice binding reads supplier invoices, their accounting rows and the files connected to them, and only for a scope that declared it. Neither reads a customer register or an employee record. An invoice binding writes to Fortnox only if it declares writeback, and then only the three things above.

Client credentials are not consent-free. Each company's sysadmin authorizes once, in a browser, and the consent must be created with account_type=service — that is what makes it mintable by client credentials afterwards.

The dashboard runs that round for you. The Fortnox card in the dashboard's Integrations view offers two ways through it, and both end in a sealed connection on the chosen app with nothing typed:

  • Connect — a dashboard admin clicks it, approves at Fortnox, and comes back. The link behind that button lives ten minutes, because this browser is about to spend it.
  • Copy connect link — the same URL, handed to whoever actually administers Fortnox. It needs no dashboard login: the person approving is usually finance or an external accounting firm, and making them a dashboard member first would be the wrong door. Seven days by default, single-use, and revocable from the same card right up until it is spent.

From the vertical itself. A bookkeeping bureau whose staff work in its own vertical does not need the dashboard for either door: the vertical starts the round for the person in front of it with requestConnectUrl, or mints the copy-able link itself with mintConnectLink and mails it to the client company's Fortnox administrator — the same single-use, revocable, seven-day link, listed on the dashboard card beside the ones minted there.

Either way the closing page names which company was attached — name, organisation number, database number, and how many financial years the new credential can read. That naming is the point: a consent granted while signed into the wrong company-switcher entry looks identical to a correct one up to that moment.

The client pair is a platform secret here, one integration for the whole fleet, so a customer has no client id or client secret to paste even if they wanted to — and the third value, DatabaseNumber, does not exist until a consent has happened. The dialog's Enter credentials manually toggle is the fallback for an already-assembled triple, not the way in.

Hosting your own callback? Do not re-implement the round. completeFortnoxConsent is the exported sequence, and it is the same code the dashboard and the local pnpm fortnox:connect script both run:

ts
import { completeFortnoxConsent } from '@substrat-run/connector-fortnox';

// Judge `state` FIRST — see below. Only then:
const { secret, company, financialYears } = await completeFortnoxConsent({
  clientId, clientSecret, code, redirectUri, fetch,
});
// secret: the sealed-ready { clientId, clientSecret, tenantId } triple
// company: whose consent this was — show CompanyName to the person who clicked approve

Two things stay yours, because the helper takes a bare code and cannot know them.

state is judged before anything else, including a reported error. The helper validates the authorization code and nothing more, so a callback that calls it on whatever arrives will happily complete a round it never started — and attach the attacker's Fortnox company to the victim's scope. Bind the round when you build the consent URL and verify it on the way back before you read code at all. That is what the dashboard does (its state is a signed claim naming the connect link's row, which is also what makes the link single-use and revocable), and what scripts/connect.mts does locally.

Then, still before the helper, two callbacks end the round rather than start an exchange: one carrying ?error=… (Fortnox declined — a denial usually carries no code at all), and one carrying no code for any other reason. completeFortnoxConsent is for the remaining case, where a real authorization code came back.

redirectUri must be the registered one, character for character, and the same string twice — once in the consent URL, once in the exchange. Fortnox validates it only after login, so an unregistered value gets you a login screen and then an invalid_grant at the exchange, which reads exactly like a spent code.

What that button actually does ​

fortnoxConsentUrl builds the URL the admin is sent to:

ts
fortnoxConsentUrl({ clientId, redirectUri, state, scopes: ['bookkeeping', 'companyinformation', 'supplierinvoice', 'archive', 'connectfile'] });
// always sets account_type=service and access_type=offline

When the redirect comes back, three steps follow, and the third is the one that matters:

  1. Exchange the code, once. grant_type=authorization_code is used here and nowhere else in this connector, and the tokens it yields are discarded after step 2.
  2. Read GET /3/companyinformation for DatabaseNumber. That number becomes the connection's tenantId, and it is shown nowhere in the Developer Portal — which is why the credential cannot be assembled by hand at all.
  3. Mint again with client_credentials from the assembled triple. This is the connector's whole premise, so it is proven at connect time, in the operator's hands, instead of first discovered by a background sweep nobody is watching.

Scopes cannot be widened without a new consent round

Ask for what the integration will need, not what it needs today. Fixing this later means going back to every customer. Note also that every Fortnox scope grants read and write — there is no read-only variant — so an extra scope widens what the credential could do, even for a binding that writes nothing.

What the customer needs before any of this works ​

Two prerequisites sit outside your code, and neither announces itself clearly when missing.

The customer needs a Fortnox integration licence. Connecting any third-party integration requires it, it is bought by the Fortnox customer on their own subscription — not by you as the integrator — and it is added once and then covers unlimited integrations. A customer who already runs some other integration pays nothing more to add yours. One who does not will be stopped at the consent screen by a purchase prompt, so it belongs in your onboarding text rather than as a surprise mid-flow.

Your scopes must be ticked on the integration in the Developer Portal. The authorize endpoint validates scope against what that integration registered, before login, and answers a bare invalid_scope — naming neither which scope was refused nor that registration is the fix. With several scopes in one request you cannot tell which one it objected to.

There is a quick way to find out, and it needs no browser: request the authorize URL one scope at a time and read the Location header. A refused scope redirects straight back with error=invalid_scope; an accepted one returns the login page.

bash
curl -s -D - -o /dev/null \
  "https://apps.fortnox.se/oauth-v1/auth?client_id=$CLIENT_ID\
&redirect_uri=http%3A%2F%2Flocalhost%3A8899%2Fcallback\
&scope=companyinformation&state=probe&response_type=code&account_type=service" \
  | grep -i '^location:'

redirect_uri, by contrast, is validated only after login, so the same trick cannot tell you whether a callback URL is registered — an unregistered one still returns the login page.

The flow ​

Per bound scope, each sweep pass:

  1. Mint an access token (cached for the pass — one mint, not one per request).
  2. GET /3/financialyears and pick the year that overlaps the period.
  3. GET /3/sie/4?financialyear=<id> — the whole year's bookkeeping in one request, instead of walking per-voucher REST endpoints.
  4. Hash the payload. Unchanged since last sync ⇒ stop here, land nothing.
  5. Parse the SIE4 (#VER / #TRANS, plus #KONTO, #DIM, #OBJEKT for labels).
  6. Sum per (account, cost centre, month) with exact decimal arithmetic.
  7. Land it in pages of 500 through the binding's operation, as the connection itself.

The cursor is written only after every page lands, so a mid-way failure leaves it at the previous hash and the next sweep retries the whole year rather than resuming into a half-written ledger.

Four things the format will bite you with ​

These are not incidental; each one produces wrong data rather than an error.

SIE4 is PC8 — code page 437 — and getting this wrong is invisible. The file declares it (#FORMAT PC8), but the HTTP response does not: there is no charset in the content type. CP437 is a pre-Unicode MS-DOS encoding, so 0x94 is ö, 0x84 is ä, 0x86 is å. Two traps follow.

Decoding as UTF-8 throws on the first Swedish letter, which is the good case — you find out. Decoding as latin1 is the bad case: every byte 0x00–0xFF is a valid latin1 code point, so nothing fails, and you get a ledger full of plausible-looking account names with the wrong letters in them. This connector shipped that way, and every test in the package passed, because the mock encoded latin1 too — the reader and the fixture agreed with each other while both disagreed with Fortnox. Only a live call could see it.

Two consequences worth copying into any SIE reader you write:

  • TextDecoder cannot do this. CP437 is not in the WHATWG Encoding registry, so new TextDecoder('cp437') throws RangeError in Node, browsers and Workers alike. A mapping table for bytes 0x80–0xFF is the only portable option. Note also that new TextDecoder('iso-8859-1') silently gives you windows-1252, which differs from latin1 in exactly the 0x80–0x9F range where CP437 keeps its Swedish letters.
  • "No replacement character" is not a charset test. Asserting that the decoded text contains no � cannot fail for a latin1 decode, so it proves nothing. Assert instead that no C1 control (U+0080–U+009F) appears and that the Swedish letters do — a chart of accounts has them.

decodeSie is the one place that knows, it reads #FORMAT and refuses a charset it does not implement rather than guessing, and FortnoxMock now encodes CP437 the way the provider really does.

Pick the year by overlap, never containment. A newly-acquired company's first financial year can start mid-month (24 April, say). Searching for "the year containing 1 January" finds nothing, and the sync reports empty books for a company with a full year of bookkeeping.

Amounts are debit-positive, and this connector does not normalize them. A cost account carries a positive amount for a cost; a revenue account (a credit) carries a negative one. That is correct double-entry — inventing a sign here would put business meaning in a format reader. Your mapping applies the sign.

#IB / #UB / #RES are skipped. They are the opening and closing balances the vouchers already sum to. A reader that adds them to the #TRANS rows reports every figure twice.

Cost centres come free ​

SIE reserves dimension 1 for kostnadsställe, and Fortnox follows the standard. So a per-property or per-unit breakdown needs no extra API call and no server-side filtering — it is read straight out of each transaction's object list, and #OBJEKT rows carry the labels.

Where the data lands, and why the connector does not decide ​

The connector hands you a FortnoxLedgerPage — neutral accounting fact — and stops.

What a business means by those numbers (which account is lokal_grundhyra, which sign normalizes it, which group it rolls into) is vocabulary, and vocabulary is the vertical’s layer. A connector that mapped account numbers to row keys would be a vertical wearing a connector's clothes, and the second customer with a different chart of accounts would have to fork it.

This is also why the connector declares no standing grants. Every other connector names its return-path permissions so the dashboard's door can be checked against them; this one's permission belongs to the consuming vertical and is unknown at build time. The check moves from build time to bind time rather than disappearing — see bindFortnoxScope above.

What's missing ​

  1. A live verification run. Done, against a Fortnox test company. It found the charset bug above and a schema that rejected null in optional text fields, and it confirmed the two claims that mattered most: client_credentials mints with a TenantId header and no refresh token, and DatabaseNumber is what the header wants.

    test/live.test.ts runs whenever secrets/connectors.env (shared by every connector) holds FORTNOX_CLIENT_ID, FORTNOX_CLIENT_SECRET and FORTNOX_TENANT_ID, and skips otherwise, so CI without secrets stays green. Assembling that credential is not copy-paste — DatabaseNumber is shown nowhere in the portal — so pnpm fortnox:connect runs the one-time service consent locally, reads it, verifies client_credentials against it, and prints the line to add.

    The suite reads only: the data calls are GETs and the one POST is the token mint, which creates no Fortnox record. It binds no write-back, so it is safe against a production company too — and that property is worth protecting, which is why seeding a sandbox with test data lives in a separate script, pnpm fortnox:seed, that refuses to write to any company whose organisation number is not Fortnox's sandbox marker 555555-5555.

    An empty sandbox is worse than no sandbox

    A fresh test environment has no financial year and no vouchers. Three of the five live tests then fail on absent data rather than on a defect — and, far worse, the two assertions that matter most never execute: the charset check and the double-entry check both need a real export with real Swedish account names in it. An empty sandbox lets a broken decoder pass. Seed first, then judge a red.

  2. A consumer. No vertical in this repo binds it yet, so the landing operation exists only in the test suite. The seam is proven; the first real mapping is not written.

  3. A deployment that schedules the sweep. The connector provides the driver and cannot hold a timer. Without startPlatformSweeper or definePlatformSweeperDO wired, a binding is inert.

  4. A measured write-back. The write-back was measured against a Fortnox sandbox on 2026-11-11, with pnpm fortnox:measure-writeback. The answers, verbatim, are in MEASUREMENTS-writeback.md. A block set over the API changes nothing else, bookkeep books with no body, and the comment log keeps its order and takes at least 65,536 characters. The release does not work where booking needs attest (the warning under writing back). Still open, for a person in the sandbox's web UI:

    • Can an unbooked supplier invoice be paid at all?
    • Does a block set over the API hide the invoice from the payment view?
    • Without the attest rule, can a booked invoice's block be cleared?