@waltermedia/fortnox-client

A TypeScript client for the Fortnox API — Sweden's leading cloud-based accounting platform. Built for reliability with built-in rate limiting, OAuth token refresh, input validation, and security hardening.

Features

• Rate limiting — Respects Fortnox API limits (1 concurrent request, 250ms minimum between requests)
• OAuth token management — TokenManager handles refresh flows automatically
• Full TypeScript support — Typed requests, responses, and parameters
• Security — Path injection prevention, sanitized error logging, no credential leakage
• Read-only operations — Vouchers, accounts, invoices, company info, SIE export

Installation

npm install @waltermedia/fortnox-client

Or with Yarn or pnpm:

yarn add @waltermedia/fortnox-client
pnpm add @waltermedia/fortnox-client

Quick Start

You need an OAuth access token from Fortnox. Obtain one via the Fortnox OAuth flow.

import { FortnoxClient } from '@waltermedia/fortnox-client';

const client = new FortnoxClient({
  accessToken: 'your-access-token',
});

// Fetch vouchers
const vouchers = await client.getVouchers({
  fromDate: '2023-01-01',
  toDate: '2023-12-31',
  limit: 100,
  page: 1,
});

console.log(vouchers.Vouchers);
console.log(vouchers.MetaInformation['@TotalPages']);

Usage

Vouchers

// List vouchers with filters
const vouchers = await client.getVouchers({
  fromDate: '2023-01-01',
  toDate: '2023-12-31',
  financialYear: 7,
  limit: 100,
  page: 1,
});

// Get a single voucher by series and number
const voucher = await client.getVoucherDetails({
  voucherSeries: 'A',
  voucherNumber: 1,
  financialYear: 7,
});

Accounts

// List accounts
const accounts = await client.getAccounts({
  limit: 100,
  offset: 0,
  financialYear: 7,
});

// Get account details
const account = await client.getAccountDetails({
  accountNumber: 1920,
  financialYear: 7,
});

Invoices

const invoices = await client.getInvoices({
  limit: 100,
  filter: 'unpaid',
  financialYear: 7,
});

const supplierInvoices = await client.getSupplierInvoices({
  limit: 100,
  filter: 'unpaid',
});

Other

const companyInfo = await client.getCompanyInformation();
const financialYears = await client.getFinancialYears({ date: '2023-06-01' });
const sieExport = await client.getSIE({ type: '4', financialYear: 7 });

Pagination

Collection responses include MetaInformation with pagination metadata:

interface MetaInformation {
  '@TotalPages': number;
  '@CurrentPage': number;
  '@TotalResources': number;
}

Example: fetch all vouchers across pages:

async function fetchAllVouchers() {
  let currentPage = 1;
  const results = [];
  let hasMorePages = true;

  while (hasMorePages) {
    const response = await client.getVouchers({
      fromDate: '2023-01-01',
      toDate: '2023-12-31',
      limit: 100,
      page: currentPage,
    });

    results.push(...response.Vouchers);
    hasMorePages = currentPage < response.MetaInformation['@TotalPages'];
    currentPage++;
  }

  return results;
}

Error Handling

API errors are wrapped in FortnoxError. Import it to check error type and access status/code:

import { FortnoxClient, FortnoxError } from '@waltermedia/fortnox-client';

try {
  const vouchers = await client.getVouchers({ fromDate: '2023-01-01', toDate: '2023-12-31' });
} catch (error) {
  if (error instanceof FortnoxError) {
    console.error('Fortnox API Error:', error.message);
    console.error('Status:', error.statusCode);
    console.error('Code:', error.code);
    // error.response contains sanitized status/data (no auth headers)
  } else {
    throw error;
  }
}

Token Management

Use TokenManager to handle OAuth token refresh:

import { TokenManager } from '@waltermedia/fortnox-client';

const tokenManager = new TokenManager(
  'initial-access-token',
  'initial-refresh-token',
  new Date(/* expiration timestamp */),
  'your-client-id',
  'your-client-secret'
);

const { accessToken, refreshToken, expiresIn, expiresAt } = await tokenManager.getToken();

Security: Store client credentials in environment variables. Never expose them in client-side code.

TypeScript Types

All response and parameter types are exported:

import type {
  VoucherCollection,
  DetailedVoucher,
  AccountCollection,
  DetailedAccount,
  InvoiceCollection,
  SupplierInvoicesCollection,
  GetVouchersParams,
  GetAccountParams,
  // ... and more
} from '@waltermedia/fortnox-client';

API Reference

| Method | Description | |--------|-------------| | getVouchers(params) | List vouchers with filters | | getVoucherDetails(params) | Get single voucher by series/number | | getAccounts(params) | List accounts | | getAccountDetails(params) | Get single account | | getInvoices(params) | List customer invoices | | getSupplierInvoices(params) | List supplier invoices | | getCompanyInformation() | Company info | | getFinancialYears(params) | Financial years | | getSIE(params) | SIE export (type "3" or "4") |

Security

This client includes:

• Path parameter validation — Voucher series, numbers, and account IDs are validated to prevent path injection
• Sanitized error logging — Tokens and credentials are never logged
• Safe error storage — FortnoxError.response excludes auth headers

Publishing to npm

For maintainers. Ensure you're logged in (npm login) and have publish access to @waltermedia:

npm run release       # patch: build → version → publish → push
npm run release-minor # minor: build → version → publish → push

Or manually:

npm run build
npm version patch   # or minor/major
npm publish
git push && git push --tags

License

MIT © Walter Media AB