fortnox-api 0.9.1 → 0.9.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: ea75f17f262d1586930c15e3114c1d65590a7f542ea7d75069c6d864c0db52ba
-  data.tar.gz: bcdc7c31ac33686637badff069fc6eedf9668e915a974420bccfef183c3e335b
+  metadata.gz: a0605a1ea41ed7a7322a560e9e27255b60df149c486f875bd968354adbf1b826
+  data.tar.gz: b66ce8b6a31fa9ef28b5ae0a99e8531df1027253bde63338291c875bfaa15367
 SHA512:
-  metadata.gz: 56e587b9a912a34d08ceaed8207d9097638726423b62bc8cacd0b440d57203f079f8c527aa30bb78bd3f82cd359a11f6c153d344026109e0c9de92ff1f054e44
-  data.tar.gz: e02fe96b0107463dbeab810717dc08549a8d2292216455c59089f7477725df1e1ecf883af02d521c3ec69bee52fe22f4afaeddf2b473408e7f8e8f40fe039b7f
+  metadata.gz: 347bab9a453b33bd19d396d2b142fb8e133ee9615529f307fbe2ecc47f79e37d907731940267da551481c62ae8a17bd0df8b83de8c955c5cdbed8ba2e0517130
+  data.tar.gz: d5ea5952ecc427a24ba0264197ed5cfa364119f37921a742304a9aec41d55b13d24ff379001af4087ce5d3235456413ade7b2a5d51ad733040de13710a3b5d6e

data/CHANGELOG.md

@@ -6,6 +6,13 @@ The format is based on [Keep a Changelog](http://keepachangelog.com/en/1.0.0/)
 and this project adheres to
 [Semantic Versioning](http://semver.org/spec/v2.0.0.html).
 
+## [0.9.2]
+
+### Fixed
+
+- Email validation now accepts internationalized domain names (IDN),
+  e.g. `user@teståäö.se` (RFC 6530)
+
 ## [0.9.1]
 
 ### Fixed
@@ -101,6 +108,7 @@ and this project adheres to
 
 - Model attribute `url` is no longer null
 
+[0.9.2]: https://github.com/accodeing/fortnox-api/compare/v0.9.1...v0.9.2
 [0.9.1]: https://github.com/accodeing/fortnox-api/compare/v0.9.0...v0.9.1
 [0.9.0]: https://github.com/accodeing/fortnox-api/compare/v0.8.0...v0.9.0
 [0.8.0]: https://github.com/accodeing/fortnox-api/compare/v0.7.2...v0.8.0

data/CLAUDE.md

@@ -0,0 +1,79 @@
+# CLAUDE.md
+
+This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+
+## Project Overview
+
+Ruby gem wrapping Fortnox AB's version 3 REST API. Uses the data mapper pattern (not ActiveRecord) with separate concerns for models, types, mappers, and repositories.
+
+## Common Commands
+
+```bash
+# Run all tests
+bundle exec rspec
+
+# Run a single test file
+bundle exec rspec spec/fortnox/api/repositories/customer_spec.rb
+
+# Run tests matching a pattern
+bundle exec rspec --example "Customer"
+
+# Run linter
+bundle exec rubocop
+
+# Run linter with auto-fix
+bundle exec rubocop -a
+
+# List rake tasks
+rake -T
+
+# Remove all VCR cassettes (for re-recording)
+rake throw_vcr_cassettes
+
+# Seed test Fortnox instance with required data
+rake seed_fortnox_test_instance
+
+# Get new OAuth tokens (requires credentials in .env)
+bin/get_tokens
+```
+
+## Architecture
+
+### Data Mapper Pattern
+
+Unlike Rails' ActiveRecord, this gem separates concerns:
+
+- **Models** (`lib/fortnox/api/models/`): Immutable data objects. Use `model.update(attr: value)` to get a new instance with changed attributes.
+- **Types** (`lib/fortnox/api/types/`): Enforce constraints on attribute values, lengths, and content.
+- **Mappers** (`lib/fortnox/api/mappers/`): Convert between Ruby objects and Fortnox JSON. Used internally by repositories.
+- **Repositories** (`lib/fortnox/api/repositories/`): Handle HTTP requests. Methods: `all`, `find(id)`, `find_by(attr: value)`, `save`.
+
+### Key Classes
+
+- `Fortnox::API` - Main module with configuration and thread-local access token
+- `Fortnox::API::Repository::Authentication` - Token renewal via `renew_tokens`
+- Available models: Article, Customer, Invoice, Label, Order, Project, TermsOfPayment, Unit
+
+### Exception Hierarchy
+
+- `Fortnox::API::AttributeError` - Invalid attribute value
+- `Fortnox::API::MissingAttributeError` - Required attribute missing
+- `Fortnox::API::RemoteServerError` - Server-side error from Fortnox
+
+## Testing
+
+- Uses VCR to record API responses as cassettes in `spec/vcr_cassettes/`
+- When re-recording cassettes, do one repository at a time to avoid 429 rate limits
+- Environment variables for testing go in `.env.test` (see `.env.template`)
+- Set `DEBUG=true` for debug output during tests
+- Set `REFRESH_TOKENS=true` to enable token refresh during testing
+
+## Fortnox API Gotchas
+
+See `docs/gotchas.md` for detailed API quirks including:
+- `SalesAccount` default values may reference non-existent accounts
+- Legacy `HouseWorkType` values that can't be used for new orders/invoices
+- `VATIncluded` affects all price fields (no VAT-inclusive fields when false)
+- `TermsOfPayments.code` is case-sensitive (`30DAYS` not `30days`)
+- Row descriptions limited to 255 characters (undocumented)
+- Only one active refresh token per Fortnox account per integration

data/README.md

@@ -16,12 +16,9 @@ PRs of your own 😃
 [![Maintainability](https://api.codeclimate.com/v1/badges/89d30a43fedf210d470b/maintainability)](https://codeclimate.com/github/accodeing/fortnox-api/maintainability)
 [![Test Coverage](https://api.codeclimate.com/v1/badges/89d30a43fedf210d470b/test_coverage)](https://codeclimate.com/github/accodeing/fortnox-api/test_coverage)
 
-The rough status of this project is as follows (as of spring 2023):
+The rough status of this project is as follows (as of spring 2025):
 
-- `master` branch and the released versions should be production ready.
-- We are actively working on our generalization of this gem:
-  [rest_easy gem](https://github.com/accodeing/rest_easy). It will be a base for
-  REST API's in general.
+- `master` branch and the released versions is production ready.
 - Basic structure complete. Things like getting customers and invoices, updating
   and saving etc.
 - Some advanced features implemented, for instance support for multiple Fortnox
@@ -175,11 +172,9 @@ $ gem install fortnox-api
 ## Authorization
 
 > :warning: Before 2022, Fortnox used a client ID and a fixed access token for
-> authorization. This way of is now deprecated. The old access tokens have a
-> life span of 10 years according to Fortnox. They can still be used, but you
-> can't issue any new long lived tokens and they recommend to migrate to the new
-> authorization process. This gem will no longer support the old way of
-> authorization since v0.9.0.
+> authorization. This way of is now deprecated. The old access tokens will be
+> deprecated April 30, 2025 according to Fortnox. This gem will no longer support
+> the old way of authorization from v0.9.0.
 
 You need to have a Fortnox app and to create such an app, you need to register
 as a Fortnox developer. It might feel as if "I just want to create an
@@ -207,7 +202,7 @@ Things you need:
 
 When you have authorized your integration you get an access token from Fortnox.
 It's a JWT with a expiration time (currently **1 hour**). You also get a long
-lived refresh token (currently lasts for **31 days** ). When you need a new
+lived refresh token (currently lasts for **45 days** ). When you need a new
 access token you send a renewal request to Fortnox. That request contains the
 new access token as well as a new refresh token and some other data. Note that
 **the old refresh token is invalidated when new tokens are requested**. As long

data/bin/fortnox

@@ -0,0 +1,285 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+lib = File.expand_path('../lib', __dir__)
+$LOAD_PATH.unshift(lib) unless $LOAD_PATH.include?(lib)
+
+require 'bundler/setup'
+require 'dry/cli'
+require 'securerandom'
+require 'base64'
+require 'socket'
+require 'cgi'
+require 'uri'
+require 'faraday'
+
+# TODO: Not implemented yet
+# require "fortnox/version"
+
+module Fortnox
+  module CLI
+    module Server
+      def self.start(port)
+        socket = TCPServer.new(port)
+        client = socket.accept
+        request = client.gets
+        _, path, = request.split
+        client.puts("HTTP/1.1 200\r\n\r\n#{response_html}")
+        client.close
+        socket.close
+
+        URI.decode_www_form(path[2..]).to_h.transform_keys(&:to_sym)
+      end
+
+      def self.response_html
+        assets_root = 'https://accodeing.com/assets/images'
+
+        favicon = "#{assets_root}/favicon-32x32.png"
+        bkg = "#{assets_root}/background.svg"
+        logo = "#{assets_root}/only_logo.svg"
+
+        <<~HTML
+          <html>
+            <head>
+              <title>Fortnox gem local server</title>
+              <link rel="icon" type="image/png" sizes="32x32" href="#{favicon}" />
+              <style>
+                main{display:block;width:800px;margin:2rem auto 0}html{color:#222;font-family:sans-serif}body{margin:0;background-color:#31926f;color:#fff;font-family:'Open Sans',sans-serif;background-image:url(#{bkg});background-repeat:no-repeat;background-size:cover;font-size:1em;line-height:1.4}h1{font-family:Quicksand,sans-serif;font-size:2em;margin:.67em 0;color:#f2dfc3}img{width:100%}
+              </style>
+            </head>
+            <body>
+              <main>
+                <img src="#{logo}" alt="According to you's logo, a happy otter.">
+                <h1>The response from Fortnox has been caught.</h1>
+                <p>You can safely close this tab now and continue in the terminal.</p>
+              </main>
+            </body>
+          </html>
+        HTML
+      end
+    end
+
+    module Commands
+      extend Dry::CLI::Registry
+
+      class Version < Dry::CLI::Command
+        desc 'Print version'
+
+        def call(*)
+          puts Fortnox::VERSION
+        end
+      end
+
+      class Init < Dry::CLI::Command # rubocop:disable Metrics/ClassLength
+        desc "Create initial authentication and refresh tokens using Fortnox's OAuth screen. " \
+             'If started without arguments it will run through a wizzard to get you set up. ' \
+             'If all the arguments are given it will run the process automatically, without prompting.'
+        option :port, default: '4242', type: :integer,
+                      desc: "Port used by a local server to catch Fortnox's auth response"
+        argument :client_id, type: :string, desc: 'Client ID'
+        argument :client_secret, type: :string, desc: 'Client secret'
+        argument :scopes, type: :array, desc: 'Array of scopes'
+
+        def call(port: 4242, client_id: nil, client_secret: nil, scopes: [], **) # rubocop:disable Metrics/AbcSize, Metrics/MethodLength
+          fast_track = !(client_id.nil? || client_secret.nil? || scopes.empty?)
+
+          confirm_ready unless fast_track
+
+          if fast_track
+            scopes = scopes.join(' ')
+          else
+            client_id = get_client_id
+            client_secret = get_client_secret
+            scopes = get_scopes
+          end
+
+          credentials = Base64.encode64("#{client_id}:#{client_secret}")
+          redirect_uri = "http://localhost:#{port}"
+          nonce = SecureRandom.base64
+          params = {
+            client_id:,
+            redirect_uri:,
+            scope: scopes,
+            state: nonce,
+            access_type: 'offline',
+            response_type: 'code',
+            account_type: 'service'
+          }
+          url = "https://apps.fortnox.se/oauth-v1/auth?#{URI.encode_www_form(params)}"
+
+          confirm_redirect_uri(redirect_uri) unless fast_track
+          launch_fortnox_authorisation(url)
+          auth_code = get_auth_code(port, nonce)
+          tokens = exchange_auth_code_for_tokens(auth_code, credentials, redirect_uri)
+          print_tokens(tokens)
+        end
+
+        private
+
+        def confirm_ready
+          puts "Before you can complete this setup you need to complete all the steps on Fortnox's side " \
+               "as documented in #{gem_homepage}/docs/getting_set_up.md"
+          print 'Do you have client ID, client secret and a list of scopes handy? [Y/n] '
+
+          confirmation = $stdin.gets.chomp.downcase
+
+          if confirmation == 'n'
+            puts 'Ok. Go read the guide, get setup as a developer in Fortnox and come back here when you are ready.'
+            exit 0
+          end
+
+          puts "Excellent, let's go! Input the information from Fortnox in the following prompts."
+        end
+
+        def get_client_id # rubocop:disable Naming/AccessorMethodName
+          print 'Client ID: '
+          $stdin.gets.chomp
+        end
+
+        def get_client_secret # rubocop:disable Naming/AccessorMethodName
+          print 'Client secret: '
+          $stdin.gets.chomp
+        end
+
+        def get_scopes # rubocop:disable Naming/AccessorMethodName
+          print 'Give a space separated list of all the scopes you will need. ' \
+                "See #{gem_homepage}/docs/scopes.md for reference.\n" \
+                'Scopes: '
+          $stdin.gets.chomp
+        end
+
+        def confirm_redirect_uri(url)
+          print "Set the redirect URL in your Fortnox application to #{url}, then press enter to continue."
+          $stdin.gets
+        end
+
+        def get_auth_code(port, nonce) # rubocop:disable Metrics/AbcSize, Metrics/MethodLength
+          response = Server.start(port)
+
+          if response[:error]
+            puts "An error occured. Fortnox returned \"#{response[:error]}\":\n   #{response[:description]}"
+            exit(-1)
+          end
+
+          normalized_state_response = CGI.unescape(response[:state]).gsub(' ', '+')
+
+          if normalized_state_response != nonce
+            puts 'The nonce returned from Fortnox did not match the one we sent, possible replay attack!'
+            puts "Raw sent: #{nonce.inspect}"
+            puts "Escaped sent: #{URI.encode_www_form({ nonce: }).inspect}"
+            puts "Raw returned: #{response[:state].inspect}"
+            puts "CGI escaped returned: #{CGI.unescape(response[:state]).inspect}"
+            puts "URI escaped returned: #{URI.decode_www_form(response[:state]).first.first.inspect}"
+            exit(-1)
+          end
+
+          response[:code]
+        rescue SocketError
+          puts "The local server failed to start so we can't catch the auth code automatically. " \
+               'If you look in the addressbar of the missing page Fortnox redirected you to after you completed ' \
+               'the authorisation you will see a request parameter called "code", paste the value below.'
+          print 'Auth code:'
+          $stdin.gets.chomp
+        end
+
+        def launch_fortnox_authorisation(url)
+          if (cmd = system_open)
+            system "#{cmd} \"#{url}\""
+          else
+            puts 'Could not identify a way to open default browser. ' \
+                 'Please open the following url in your prefered browser:'
+            puts url
+          end
+        end
+
+        def system_open
+          case RbConfig::CONFIG['host_os']
+          when /mswin|mingw|cygwin/
+            'start'
+          when /darwin/
+            'open'
+          when /linux|bsd/
+            'xdg-open'
+          end
+        end
+
+        def exchange_auth_code_for_tokens(auth_code, credentials, redirect_uri)
+          headers = {
+            'Content-type' => 'application/x-www-form-urlencoded',
+            'Authorization' => "Basic #{credentials}"
+          }
+          body = "grant_type=authorization_code&code=#{auth_code}&redirect_uri=#{redirect_uri}"
+
+          response = Faraday.post('https://apps.fortnox.se/oauth-v1/token', body, headers)
+
+          JSON.parse(response.body).transform_keys(&:to_sym)
+        end
+
+        def print_tokens(tokens) # rubocop:disable Metrics/MethodLength
+          puts 'Save these tokens in an appropriate place:'
+          puts ''
+          puts "refresh token: #{tokens[:refresh_token]}"
+          puts ''
+          puts "access token: #{tokens[:access_token]}"
+          puts ''
+          puts 'You can run this command with all the inputs as parameters if you want to reauthorize ' \
+               'without the guide in the future.'
+          puts ''
+          puts 'There is also a `fortnox refresh` command to run the refresh cycle manually ' \
+               'for use in cron jobs or other automated token refresh scenarios. ' \
+               'See `fortnox help` for more information.'
+          puts ''
+        end
+
+        def gem_homepage
+          @gem_homepage ||= gem_homepage_from_gemspec
+        end
+
+        def gem_homepage_from_gemspec
+          gem_root = File.expand_path('..', __dir__)
+          file = Dir.entries(gem_root).find do |f|
+            puts f
+            f.end_with? '.gemspec'
+          end
+          our_gemspec = Gem::Specification.load("#{gem_root}/#{file}")
+          our_gemspec.homepage
+        end
+      end
+
+      class Refresh < Dry::CLI::Command
+        desc 'Get a new set of tokens from Fortnox given a valid refresh token. ' \
+             'If you do not already have a set of tokens you want `fortnox init` instead.'
+        argument :client_id, required: true, type: :string, desc: 'Client ID'
+        argument :client_secret, required: true, type: :string, desc: 'Client secret'
+        argument :refresh_token, required: true, type: :string, desc: 'Valid refresh token'
+
+        def call(client_id:, client_secret:, refresh_token:, **)
+          credentials = Base64.encode64("#{client_id}:#{client_secret}")
+          headers = {
+            'Content-type' => 'application/x-www-form-urlencoded',
+            'Authorization' => "Basic #{credentials}"
+          }
+          body = "grant_type=refresh_token&refresh_token=#{refresh_token}"
+
+          response = Faraday.post('https://apps.fortnox.se/oauth-v1/token', body, headers)
+
+          print_tokens(JSON.parse(response.body).transform_keys(&:to_sym))
+        end
+
+        def print_tokens(tokens)
+          puts ''
+          puts "refresh token: #{tokens[:refresh_token]}"
+          puts ''
+          puts "access token: #{tokens[:access_token]}"
+          puts ''
+        end
+      end
+
+      register 'version', Version, aliases: ['v', '-v', '--version']
+      register 'init', Init, aliases: ['i', '-i', '--init']
+      register 'refresh', Refresh, aliases: ['r', '-r', '--refresh']
+    end
+  end
+end
+
+Dry::CLI.new(Fortnox::CLI::Commands).call

data/docs/gotchas.md

@@ -0,0 +1,146 @@
+# Gotchas
+Fortnox API is not perfect. There are a couple of things to take into consideration when using it.
+
+## Article
+If you create a new Article, the `SalesAccount` will default to the default sales account set in the Fortnox settings. An interesting thing though is that this account might not exist in the chart of accounts. Therefore, this strange thing can happen (requests and responses below are the raw HTTP requests/responses):
+
+1. You create an new Article via the API: `'{"Article":{"Description":"A value","SalesAccount":1250}}'` and you get an Article back that has `SalesAccount` set: `'{"Article":{"Description":"A Value",  "SalesAccount":1250, "PurchaseAccount":4000, ...}}'`.
+2. You try to update the newly created Article with `'{"Article":{"Description":"Updated description"}}'` and you get this back:
+`'{"ErrorInformation":{"error":1,"message":"Inköpskonto inte uppdaterat. Kontot \"4000\" existerar inte. (PurchaseAccount)", ...}}'`
+
+We haven't even touched the `SalesAccount` but you still get an error. So the account that the API says that the Article has does not necessarily need to exist in "reality"...
+
+## HouseWorkType
+### Legacy types
+Not all HouseWorkTypes available are possible to use when creating a new `Order` or `Invoice`. For instance, creating an `OrderRow` with `HouseWorkType` set to `COOKING` returns:
+> Skattereduktion för en av de valda husarbetestyperna har upphört.
+
+Unfortunately, their documentation does not tell you which types are deprecated... In fact, the deprecated types are simply removed from their documentation, so if you fetch an old `Order`/`Invoice`, you have no clue what HouseWorkType can be set to! There are two constants available in the gem: `CURRENT_HOUSEWORK_TYPES` and `LEGACY_HOUSEWORK_TYPES`, but we cannot guarantee that they are up to date and that they include all possible values.
+
+### OTHERCOSTS
+Another weird thing is that the option `OTHERCOSTS` is not allowed to be combined with `HouseWork` attribute. Yes, that is true...
+
+## VAT on Invoices and Orders rows
+
+If you create an Invoice with the following data:
+
+```
+$ curl -X "POST" "https://api.fortnox.se/3/invoices" \
+>      (credentials...)
+>      -d $'{
+>        "Invoice": {
+>          "CustomerNumber": "188",
+>            "InvoiceRows": [
+>            {
+>              "ArticleNumber": "1",
+>              "DeliveredQuantity": "10.00",
+>              "VAT": "25"
+>            }
+>            ]
+>        }
+>      }'
+```
+
+You get the following when you query the created Invoice:
+
+```
+{"Invoice":
+  {...,
+  "InvoiceRows":[
+    {
+      ...
+      DeliveredQuantity":"10.00",
+      ...,
+      "Price":100,
+      "PriceExcludingVAT":100,
+      ...,
+      "Total":1000,
+      "TotalExcludingVAT":1000,
+      "Unit":"",
+      "VAT":25}
+  ]
+```
+
+Notice that the `Price` and `PriceExcludingVAT` have the exact same amount. The same goes for `Total` and `TotalExcludingVAT`. Strange, right? The `VAT` is set to `25`%.
+
+It works like this: `Invoice` (and `Order`) has a `VATIncluded` attribute. If it is set to `true`, `Price` and `Total` will be VAT included and `PriceExcludingVAT` and `TotalExcludingVAT` will obviously be VAT excluded. BUT if you set `VATIncluded` to false, all those attributes will be VAT exclusive and none inclusive. If you want to know the VAT for each row, then you have to calculate it yourself! I have suggested to Fortnox to fix this weird logic by adding a `TotalVAT` and `PriceWithVAT` that always holds the `VAT` amount. Then `Price` and `Total` can be VAT included/excluded depending on the value of `VATIncluded`. Fortnox said they will add this to their to do list...
+
+## Dependent attributes
+Some attributes depends on other attributes.
+
+### `Invoice.InvoiceRows.Discount`
+`Discount` have two different limits depending on `DiscountType`. Calling Fortnox with
+```
+{
+  "Invoice":{
+    "CustomerNumber":"1",
+    "InvoiceRows":[
+      {"ArticleNumber":"0000","Discount":12.0001,"DiscountType":"PERCENT","Price":20.0}
+    ]
+  }
+}
+```
+gives an `InvoiceRow` with `"Discount":12,"DiscountType":"PERCENT"`
+
+Calling Fortnox with
+```
+{
+  "Invoice":{
+    "CustomerNumber":"1",
+    "InvoiceRows":[
+      {"ArticleNumber":"0000","Discount":123456.0,"DiscountType":"PERCENT","Price":20.0}
+    ]
+  }
+}
+```
+gives
+```
+     Fortnox::API::RemoteServerError:
+       Ogiltig rabatt. Får inte överstiga 100 %
+```
+
+## Types
+### Type of attribute DocumentNumber
+`Customer` attribute `DocumentNumber` can be both an `Integer` and a `String` according to Fortnox... See [#78](https://github.com/my-codeworks/fortnox-api/issues/78).
+
+### Default values for Date attributes
+The default values for date attributes from Fortnox API can be either an empty string or null. Fortnox is working on the issue. See [#79](https://github.com/my-codeworks/fortnox-api/issues/79).
+
+## Strange error messages
+### InternalError when creating Order without OrderRows
+Creating an `Order` without `OrderRows` returns `InternalError`. Fortnox is working on this issue. See [#84](https://github.com/my-codeworks/fortnox-api/issues/84).
+
+### Kunde inte hitta konto.
+If you create an `Order` or `Invoice` with an `OrderRow`/`InvoiceRow` without both `ArticleNumber` and `AccountNumber` Fortnox gives you this splendid message:
+> Kunde inte hitta konto.
+
+I think you can set a default account number for rows.
+
+## Fortnox rewrites attributes
+### TermsOfPayments
+This model has a `code` attribute. `30days` is a valid attribute value, but the API rewrites this as `30DAYS` and a `GET` request with `30days` will return `Not Found`. This is not documented anywhere...
+
+## Not documented limitations
+### TermsOfPayments
+The `code` attribute has no limits according to the documentations, but when sending `30 days` to the API, you get an error saying that the value must be alphanumeric.
+
+### Row description
+The row description for `Invoice` (and I guess for `Offer` and `Order` as well) has a limit of 255 characters.
+
+## Consistency
+### Customer's SalesAccount attribute
+If you create a `Customer` with the following JSON payload, with `SalesAccount` as a **string** just like the documentation says it should be
+```
+{"Customer":{"Name":"Customer with Sales Account","SalesAccount":"3001"}}
+```
+Fortnox returns `SalesAccount` as an **integer**...
+```
+{"Customer":{"@url":"https:\/\/api.fortnox.se\/3\/customers\/242",..., "SalesAccount":3001}}
+```
+When you then fetch **the same Customer you just created**, you get the `SalesAccount` as a **string**
+```
+{"Customer": "@url":"https:\/\/api.fortnox.se\/3\/customers\/242", ..., "SalesAccount":"3001"}}
+```
+
+## Authentication
+You can only have one active refresh token per Fortnox account and Fortnox integration. If you want multiple refresh tokens per Fortnox account you can create multiple integrations.

data/lib/fortnox/api/types.rb

@@ -91,7 +91,7 @@ module Fortnox
                      .constructor(EnumConstructors.default)
 
       Email = Strict::String
-              .constrained(max_size: 1024, format: /^$|\A[[[:alnum:]]+-_.]+@[\w+-_.]+\.[a-z]+\z/i)
+              .constrained(max_size: 1024, format: /^$|\A[[[:alnum:]]._+-]+@[[[:alnum:]]._-]+\.[a-z]+\z/i)
               .optional
               .constructor { |v| v&.to_s&.downcase }
 

data/lib/fortnox/api/version.rb

@@ -2,6 +2,6 @@
 
 module Fortnox
   module API
-    VERSION = '0.9.1'
+    VERSION = '0.9.2'
   end
 end

data/spec/fortnox/api/repositories/customer_spec.rb

@@ -97,4 +97,23 @@ describe Fortnox::API::Repository::Customer, integration: true, order: :defined
       end
     end
   end
+
+  describe 'internationalized domain name email' do
+    context 'when saving a Customer with an IDN email address' do
+      subject(:customer) do
+        VCR.use_cassette("#{vcr_dir}/save_new_with_idn_email") do
+          repository.save(
+            described_class::MODEL.new(
+              name: 'Customer with IDN email',
+              email: 'user@teståäö.se'
+            )
+          )
+        end
+      end
+
+      it 'saves the email' do
+        expect(customer.email).to eq('user@teståäö.se')
+      end
+    end
+  end
 end

data/spec/fortnox/api/types/email_spec.rb

@@ -23,7 +23,8 @@ describe Fortnox::API::Types::Email do
     valid_emails = [
       'valid@example.com',
       'kanal_75_ab-faktura@mail.unit4agresso.readsoftonline.com',
-      'sköldpadda@example.com'
+      'sköldpadda@example.com',
+      'user@teståäö.se'
     ]
 
     valid_emails.each do |email|
@@ -32,7 +33,19 @@ describe Fortnox::API::Types::Email do
   end
 
   context 'when created with invalid email' do
-    include_examples 'raises ConstraintError', 'te$£@st@example.com'
+    invalid_emails = [
+      'te$£@st@example.com',
+      'user@exam!ple.com',
+      'user@exam<ple.com',
+      'user@exam>ple.com',
+      'user@exam=ple.com',
+      'user@exam[ple.com',
+      'user@exam]ple.com'
+    ]
+
+    invalid_emails.each do |email|
+      include_examples 'raises ConstraintError', email
+    end
   end
 
   context 'when created with more than 1024 characters' do

data/spec/support/vcr_setup.rb

@@ -9,7 +9,8 @@ VCR.configure do |c|
     interaction.request.headers['Authorization']&.first
   end
   c.filter_sensitive_data('<REFRESH_TOKEN>') do |interaction|
-    interaction.request.body.split('&refresh_token=').last
+    body = interaction.request.body
+    body&.split('&refresh_token=')&.last if body&.include?('&refresh_token=')
   end
   c.filter_sensitive_data('<ACCESS_TOKEN>') do |interaction|
     body = interaction.response.body

data/spec/vcr_cassettes/customers/save_new_with_idn_email.yml

@@ -0,0 +1,67 @@
+---
+http_interactions:
+- request:
+    method: post
+    uri: https://api.fortnox.se/3/customers/
+    body:
+      encoding: UTF-8
+      string: '{"Customer":{"Email":"user@teståäö.se","Name":"Customer with IDN email"}}'
+    headers:
+      Content-Type:
+      - application/json
+      Accept:
+      - application/json
+      Authorization:
+      - "<AUTHORIZATION>"
+      Accept-Encoding:
+      - gzip;q=1.0,deflate;q=0.6,identity;q=0.3
+      User-Agent:
+      - Ruby
+  response:
+    status:
+      code: 201
+      message: Created
+    headers:
+      Content-Length:
+      - '1479'
+      Content-Type:
+      - application/json
+      Date:
+      - Thu, 22 Jan 2026 21:10:13 GMT
+      Location:
+      - customers
+      X-Build:
+      - 0a146b2789
+      X-Frame-Options:
+      - sameorigin
+      X-Krakend:
+      - Version 2.9.4
+      X-Krakend-Completed:
+      - 'false'
+      X-Rack-Responsetime:
+      - '227'
+      X-Uid:
+      - 5e6d835b
+      Server:
+      - Fortnox
+      X-Content-Type-Options:
+      - nosniff
+      X-Xss-Protection:
+      - '0'
+      Referrer-Policy:
+      - strict-origin-when-cross-origin
+      Content-Security-Policy:
+      - 'upgrade-insecure-requests;frame-ancestors https://*.fortnox.se;report-uri
+        /api/cspreport;connect-src ''self'' https://a.storyblok.com wss://*.fortnox.se
+        *.fortnox.se *.findity.com *.ingest.de.sentry.io mybusiness.pwc.se themes.googleusercontent.com
+        s3.amazonaws.com/helpjuice-static/ *.helpjuice.com *.vimeo.com fonts.googleapis.com
+        fonts.gstatic.com fortnox.piwik.pro api.cling.se wss://api.cling.se app.boardeaser.com
+        ''unsafe-inline'' ''unsafe-eval'' blob: data:'
+      Strict-Transport-Security:
+      - max-age=31536000; includeSubdomains
+    body:
+      encoding: UTF-8
+      string: '{"Customer":{"@url":"https:\/\/api.fortnox.se\/3\/customers\/2","Address1":null,"Address2":null,"City":null,"Country":null,"Comments":null,"Currency":"SEK","CostCenter":null,"CountryCode":null,"Active":true,"CustomerNumber":"2","DefaultDeliveryTypes":{"Invoice":"PRINT","Order":"PRINT","Offer":"PRINT"},"DefaultTemplates":{"Order":"DEFAULTTEMPLATE","Offer":"DEFAULTTEMPLATE","Invoice":"DEFAULTTEMPLATE","CashInvoice":"DEFAULTTEMPLATE"},"DeliveryAddress1":null,"DeliveryAddress2":null,"DeliveryCity":null,"DeliveryCountry":null,"DeliveryCountryCode":null,"DeliveryFax":null,"DeliveryName":null,"DeliveryPhone1":null,"DeliveryPhone2":null,"DeliveryZipCode":null,"Email":"user@test\u00e5\u00e4\u00f6.se","EmailInvoice":"","EmailInvoiceBCC":"","EmailInvoiceCC":"","EmailOffer":"","EmailOfferBCC":"","EmailOfferCC":"","EmailOrder":"","EmailOrderBCC":"","EmailOrderCC":"","ExternalReference":null,"Fax":null,"GLN":null,"GLNDelivery":null,"InvoiceAdministrationFee":null,"InvoiceDiscount":null,"InvoiceFreight":null,"InvoiceRemark":"","Name":"Customer
+        with IDN email","OrganisationNumber":"","OurReference":"","Phone1":null,"Phone2":null,"PriceList":"A","Project":"","SalesAccount":null,"ShowPriceVATIncluded":false,"TermsOfDelivery":"","TermsOfPayment":"","Type":"COMPANY","VATNumber":"","VATType":"SEVAT","VisitingAddress":null,"VisitingCity":null,"VisitingCountry":null,"VisitingCountryCode":null,"VisitingZipCode":null,"WayOfDelivery":"","WWW":"","YourReference":"","ZipCode":null}}'
+  recorded_at: Thu, 22 Jan 2026 21:10:13 GMT
+recorded_with: VCR 6.2.0

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: fortnox-api
 version: !ruby/object:Gem::Version
-  version: 0.9.1
+  version: 0.9.2
 platform: ruby
 authors:
 - Jonas Schubert Erlandsson
@@ -11,7 +11,7 @@ authors:
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2025-01-08 00:00:00.000000000 Z
+date: 2026-01-23 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: countries
@@ -315,6 +315,7 @@ email:
 - info@accodeing.com
 executables:
 - console
+- fortnox
 - get_tokens
 - renew_tokens
 extensions: []
@@ -329,6 +330,7 @@ files:
 - ".tool-versions"
 - ".travis.yml"
 - CHANGELOG.md
+- CLAUDE.md
 - CONTRIBUTE.md
 - DEVELOPER_README.md
 - Gemfile
@@ -337,8 +339,10 @@ files:
 - README.md
 - Rakefile
 - bin/console
+- bin/fortnox
 - bin/get_tokens
 - bin/renew_tokens
+- docs/gotchas.md
 - fortnox-api.gemspec
 - lib/fortnox/api.rb
 - lib/fortnox/api/mappers.rb
@@ -522,6 +526,7 @@ files:
 - spec/vcr_cassettes/customers/multi_param_find_by_hash.yml
 - spec/vcr_cassettes/customers/save_new.yml
 - spec/vcr_cassettes/customers/save_new_with_country_code_SE.yml
+- spec/vcr_cassettes/customers/save_new_with_idn_email.yml
 - spec/vcr_cassettes/customers/save_new_with_sales_account.yml
 - spec/vcr_cassettes/customers/save_old.yml
 - spec/vcr_cassettes/customers/save_with_specially_named_attribute.yml