fortnox-api 1.0.0.rc1 → 1.0.0.rc3

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: d4ab3f55b3783c477974abba27bae6b9104baf418e131532a746f822177605bd
-  data.tar.gz: 882d8f34d8246f74052823894fd7286a146bdaa745155928059cad7abfe0d6ef
+  metadata.gz: 2297de9b35ce0c8d7f3f0e3b84f0a44a443062d257f843876657a6d26a4da160
+  data.tar.gz: b328a297acaa35278c2b943b10bc2dc04b7e8dfbf2dd65642346f35c572bb950
 SHA512:
-  metadata.gz: 2e4a87ea6c15df6acce08ef2e3006f6cf4acd936a933e8449af585f5426f0a5f951e06f84a96ec34a044248519b013d2085b3c7ff8889e5016a4cc79af0074f1
-  data.tar.gz: '09c2e017f7dc98c61565c0dc00b9d8ab35a8ea8ad90928e523f822c5f6bb84a2ebc74c75cbd1d02a4cb2ba8d58147f39286b0de05c656170a7f55ae6f4792971'
+  metadata.gz: a73b124f68428feaaccbfea406a025bb24995b7dce7e88959dee7aca21ab449e4c92cbae11808b33c50cf8f8e498d6039399157cdcc5e68c3bcb6cfce5a35b30
+  data.tar.gz: aa5b472af7edc87d4f808581ae99545e1b99f33d7319890843d442d9f2c7d1afe7db6fb04d509a5524d5b7f405337e0b6043d8155be1e5b3ebf2b8e83d3e75e9

data/CHANGELOG.md

@@ -6,6 +6,61 @@ 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).
 
+## [1.0.0.rc3] - 2026-05-08
+
+### Changed
+
+- `Fortnox::RequestError#message` now includes the API's
+  `ErrorInformation.Message` and code from the response body when present,
+  normalising Fortnox's inconsistent key casing (PascalCase vs lowercase)
+  across endpoints. Previously the message was only `"Request failed: <status>"`,
+  hiding the cause from logs and uncaught backtraces.
+- `Article#commodity_code`, `Customer#phone`, `Invoice#accounting_method`,
+  `Invoice#invoice_period_reference`, `Invoice#invoice_reference`,
+  `Document#time_basis_reference`, `Document#total_to_pay`, and
+  `Document#warehouse_ready` are now flagged read-only to match the Fortnox
+  API. Values set on these attributes are silently excluded from save
+  requests; previously they were sent and rejected by the API.
+
+### Fixed
+
+- `Order` and `Invoice` rows now serialise the VAT field as `VAT` instead of
+  `Vat`. Saving rows with a `vat` value previously failed with Fortnox
+  rejecting the request as `"Felaktigt fältnamn"`. This bug was introduced in the 1.0.0.rc1,
+  it did not exist in 0.x.
+
+## [1.0.0.rc2] - 2026-05-05
+
+### Added
+
+- Per-resource OAuth scope declarations via the `scope` setting in
+  `Fortnox::Resource`, plus `Fortnox.scopes` returning a
+  `{ scope_string => [resource_classes] }` mapping derived from the
+  registered resources.
+
+### Changed
+
+- `fortnox-setup` lists the OAuth scopes covered by the gem's resources
+  and accepts a space-separated selection or `all`, replacing the
+  prescriptive default that didn't reflect the actual resource set. Other
+  Fortnox scopes (`salary`, `bookkeeping`, etc.) can still be entered
+  manually.
+- `TermsOfPayment.code` now has a 25-character limit, matching Fortnox
+  API documentation.
+- `Unit.code` now has a 20-character limit, matching Fortnox API
+  documentation.
+- `Unit.description` is now `Sized::String[100]` and required, matching
+  Fortnox API documentation. In 0.x and rc1 this was nullable client-side,
+  but the Fortnox API rejected unset descriptions anyway.
+
+### Fixed
+
+- `TermsOfPayment.code` is required again, matching Fortnox API
+  documentation. The rest-easy rewrite for rc1 briefly lost the required
+  flag.
+- `Unit.code` is required again, matching Fortnox API documentation. The
+  rest-easy rewrite for rc1 briefly lost the required flag.
+
 ## [1.0.0.rc1] - 2026-05-04
 
 Version 1.0 is a complete rewrite of the gem and is **not** a drop-in
@@ -24,6 +79,14 @@ for the full list of breaking changes.
 - **Breaking** Authorization now uses the new Fortnox client credentials flow.
   Refresh tokens are no longer needed, nor supported. A tenant ID is now required;
   obtain one with the new `fortnox-setup` executable.
+- **Breaking** Environment variables lose the `_API_` infix:
+  `FORTNOX_API_CLIENT_ID` → `FORTNOX_CLIENT_ID`, `FORTNOX_API_CLIENT_SECRET`
+  → `FORTNOX_CLIENT_SECRET`, `FORTNOX_API_ACCESS_TOKEN` →
+  `FORTNOX_ACCESS_TOKEN`. `FORTNOX_API_REFRESH_TOKEN`,
+  `FORTNOX_API_REDIRECT_URI`, and `FORTNOX_API_SCOPES` are removed —
+  refresh tokens are no longer supported, and the redirect URI and scopes
+  are now selected interactively in `fortnox-setup`. The new
+  `FORTNOX_TENANT_ID` is required for the client credentials flow.
 - **Breaking** `Fortnox.request_access_token` replaces
   `Fortnox::API::Repository::Authentication` for token management.
 - **Breaking** Configuration moves from `Fortnox::API.configuration` to
@@ -60,6 +123,16 @@ for the full list of breaking changes.
   `size`, `length`, `empty?`, `[]`, and `to_a`, so most existing Array
   usage works unchanged. Code that explicitly checks `is_a?(Array)` or
   compares with `==` against an Array literal needs updating.
+- **Breaking** `Invoice.accounting_method` is now an enum accepting only
+  `''`, `'ACCRUAL'`, or `'CASH'`. In 0.x this was a free-form
+  `Nullable::String` so any value passed client-side.
+- **Breaking** `Invoice.invoice_type` is now an enum accepting only `''`,
+  `'INVOICE'`, `'AGREEMENTINVOICE'`, `'INTRESTINVOICE'`, `'SUMMARYINVOICE'`,
+  or `'CASHINVOICE'`. In 0.x this was a free-form `Nullable::String`.
+- `your_order_number` on Invoice and Order (inherited from Document) max
+  length raised from 30 to 75 characters to match the current Fortnox API.
+- Article dimension fields (`depth`, `height`, `weight`, `width`) max raised
+  from 99,999,999 to 999,999,999 to match the documented Fortnox range.
 
 ### Added
 
@@ -94,3 +167,7 @@ for the full list of breaking changes.
 
 For changes prior to the 1.0 rewrite, see the
 [0.x changelog](https://github.com/accodeing/fortnox-api/blob/v0.9.2/CHANGELOG.md).
+
+[1.0.0.rc3]: https://github.com/accodeing/fortnox-api/compare/v1.0.0.rc2...v1.0.0.rc3
+[1.0.0.rc2]: https://github.com/accodeing/fortnox-api/compare/v1.0.0.rc1...v1.0.0.rc2
+[1.0.0.rc1]: https://github.com/accodeing/fortnox-api/releases/tag/v1.0.0.rc1

data/README.md

@@ -16,7 +16,7 @@ Adding more resources is quick and easy, see the
 ## Status
 
 Version 1.0 is a complete rewrite, currently in release candidate
-(`1.0.0.rc1`). It is built on
+(`1.0.0.rc3`). It is built on
 [rest-easy](https://github.com/accodeing/rest-easy), replacing the old
 HTTParty + Data Mapper architecture with a single resource class per entity.
 Authorization uses the Fortnox client credentials flow.
@@ -35,21 +35,21 @@ snake_case in Ruby).
 
 ### Immutability
 
-The model instances are immutable. That means:
+Resource instances are immutable. That means:
 
 ```ruby
-customer.model.name # => "Old Name"
-customer.model.name = 'New Name' # => NoMethodError
+customer.name # => "Old Name"
+customer.name = 'New Name' # => NoMethodError
 ```
 
 Any operation that updates state returns a new instance with the updated
 attributes while leaving the old instance alone:
 
 ```ruby
-customer.model.name # => "Old Name"
+customer.name # => "Old Name"
 updated_customer = customer.update(name: 'New Name')
-updated_customer.model.name # => "New Name"
-customer.model.name # => "Old Name"
+updated_customer.name # => "New Name"
+customer.name # => "Old Name"
 ```
 
 This is how all resources work, they are all immutable.
@@ -68,8 +68,10 @@ The gem raises the following exceptions:
 
 - `Fortnox::Error` — base class for everything below. Rescue this to catch
   any error raised by the gem.
-- `Fortnox::RequestError` — 4xx/5xx responses from the Fortnox API. Carries
-  the response object as `.response`.
+- `Fortnox::RequestError` — 4xx/5xx responses from the Fortnox API. The
+  exception message includes the API's `ErrorInformation.Message` and code
+  when present (Fortnox is inconsistent about the key casing — the gem
+  normalises both). The full response is on `.response`.
 - `Fortnox::AttributeError` — base for attribute validation failures.
   - `Fortnox::ConstraintError` — an attribute value violates a type
     constraint (max size, format, etc.). Carries `.attribute_name` and
@@ -141,20 +143,26 @@ fortnox-setup
 
 The script will:
 
-1. Ask for your client ID, client secret, and scopes
-2. Offer to use a local server on `http://localhost:4242` to catch the
-   authorization response automatically. If you choose this, set your Fortnox
-   app's redirect URL to `http://localhost:4242`. Otherwise, enter your existing
-   redirect URL and paste the authorization code manually.
-3. Open your browser to the Fortnox authorization page
-4. You log in to Fortnox and grant your app access
-5. The script exchanges the authorization code for an access token and extracts
-   the tenant ID from the JWT
-6. The tenant ID is printed for you to store in your application's configuration
+1. Ask for your client ID and client secret.
+2. List the OAuth scopes covered by the gem's resources and ask which ones
+   you need. Enter a space-separated list, or `all` for everything the gem
+   supports. You can also enter scopes the gem doesn't expose directly
+   if you plan to call those endpoints manually.
+3. Offer to use a local server to catch the authorization response automatically.
+   If you choose this, set your Fortnox app's redirect URL to `http://localhost:4242`.
+   Otherwise, enter your existing redirect URL and paste the authorization code manually.
+4. Open your browser to the Fortnox authorization page.
+5. You log in to Fortnox and grant your app access.
+6. The script exchanges the authorization code for an access token and extracts
+   the tenant ID from the JWT.
+7. The tenant ID is printed for you to store in your application's configuration.
 
 After this you have a tenant ID and never need to run this script again (unless
 you need to authorize against a different Fortnox account).
 
+Note: If you change the integration configuration in Fortnox it takes some time for
+Fortnox to propagate the changes (for instance changing the Redirect URI or the scope).
+
 ### Requesting access tokens
 
 Once you have a tenant ID, you can request access tokens programmatically.
@@ -176,6 +184,11 @@ It is up to you to manage the token lifecycle in your application. A common
 approach is to request a new token before each batch of API calls, or to cache
 the token and refresh it when it expires.
 
+Note: Fortnox only allows one active access token per integration. Requesting a
+new token invalidates the previous one. If you need multiple active access
+tokens in parallel, you need a separate integration (client ID and secret) for
+each token.
+
 ### Updating access tokens in env files
 
 For development and testing, the gem includes an executable that reads your
@@ -228,11 +241,11 @@ returns alongside collection responses:
 
 ```ruby
 customers = Fortnox::Customer.all
-customers.first.model.name # => "Acme Corp"
-customers.size             # => 50
-customers.total            # => 327
-customers.pages            # => 7
-customers.current_page     # => 1
+customers.first.name   # => "Acme Corp"
+customers.size         # => 50
+customers.total        # => 327
+customers.pages        # => 7
+customers.current_page # => 1
 ```
 
 `Collection` is `Enumerable`, so `.each`, `.map`, `.select`, `.first`, etc.
@@ -265,13 +278,13 @@ See the
 [Fortnox documentation](https://developer.fortnox.se/general/parameters/)
 for available parameters.
 
-The returned object wraps the model. Access attributes through `.model`:
+Attributes are exposed directly on the returned instance:
 
 ```ruby
 customer = Fortnox::Customer.find(1)
-customer.model.name       # => "Acme Corp"
-customer.model.city       # => "Stockholm"
-customer.unique_id        # => "1"
+customer.name      # => "Acme Corp"
+customer.city      # => "Stockholm"
+customer.unique_id # => "1"
 ```
 
 ### Creating a record
@@ -281,7 +294,7 @@ Use `.stub` to build a new instance and `.save` to persist it:
 ```ruby
 customer = Fortnox::Customer.stub(name: 'Acme Corp', city: 'Stockholm')
 result = Fortnox::Customer.save(customer)
-result.model.customer_number # => "1"
+result.customer_number # => "1"
 ```
 
 ### Updating a record

data/bin/fortnox-setup

@@ -11,6 +11,7 @@ require 'securerandom'
 require 'socket'
 require 'uri'
 require 'faraday'
+require 'fortnox'
 
 OAUTH_ENDPOINT = 'https://apps.fortnox.se/oauth-v1'
 LOCAL_PORT = 4242
@@ -108,10 +109,25 @@ puts
 
 client_id = prompt('Client ID')
 client_secret = prompt('Client secret')
+
+puts
+puts 'Available scopes:'
+Fortnox.scopes.each do |scope, resources|
+  resource_names = resources.map { |r| r.name.split('::').last }.join(', ')
+  puts "  #{scope.ljust(10)} → #{resource_names}"
+end
+puts
+puts 'These must match the scopes configured on your Fortnox app in the developer'
+puts 'portal. Other Fortnox scopes (salary, bookkeeping, etc.) can be added manually.'
 puts
-puts 'Enter the scopes you need. These must match the scopes configured on your'
-puts 'Fortnox app in the developer portal.'
-scopes = prompt('Scopes', default: 'article customer invoice order project settings')
+
+scopes = loop do
+  input = prompt("Enter scopes (space-separated, or 'all')").strip
+  break Fortnox.scopes.keys.join(' ') if input == 'all'
+  break input unless input.empty?
+
+  puts 'Please enter at least one scope.'
+end
 
 puts
 puts 'The script can catch the authorization response automatically using a'

data/lib/fortnox/mappers/document_row.rb

@@ -6,7 +6,8 @@ module Fortnox
       struct    Structs::DocumentRow
       overrides housework: 'HouseWork',
                 housework_hours_to_report: 'HouseWorkHoursToReport',
-                housework_type: 'HouseWorkType'
+                housework_type: 'HouseWorkType',
+                vat: 'VAT'
     end
   end
 end

data/lib/fortnox/resource.rb

@@ -7,8 +7,11 @@ module Fortnox
     settings do
       setting :instance_wrapper, reader: true
       setting :collection_wrapper, reader: true
+      setting :scope, reader: true
     end
 
+    @registered_resources = []
+
     before_parse do |data, meta|
       if data.key?(config.instance_wrapper)
         meta.partial = false
@@ -38,6 +41,13 @@ module Fortnox
     end
 
     class << self
+      attr_reader :registered_resources
+
+      def inherited(subclass)
+        super
+        Fortnox::Resource.registered_resources << subclass
+      end
+
       def parse(response)
         with_translated_errors do
           pagination = extract_pagination(response)

data/lib/fortnox/resources/article.rb

@@ -8,6 +8,7 @@ module Fortnox
       path 'articles'
       instance_wrapper 'Article'
       collection_wrapper 'Articles'
+      scope 'article'
     end
 
     # @url Direct URL to the record.
@@ -154,6 +155,6 @@ module Fortnox
     attr :default_stock_location, Coercible::String.optional
 
     # CommodityCode Commodity code of the article.
-    attr :commodity_code, Coercible::String.optional
+    attr :commodity_code, Coercible::String.optional, :read_only
   end
 end

data/lib/fortnox/resources/customer.rb

@@ -8,6 +8,7 @@ module Fortnox
       path 'customers'
       instance_wrapper 'Customer'
       collection_wrapper 'Customers'
+      scope 'customer'
     end
 
     # Direct URL to the record.
@@ -130,6 +131,9 @@ module Fortnox
     # Our reference
     attr :our_reference, Sized::String[50]
 
+    # Phone number of the customer. Only present in collection responses.
+    attr :phone, Coercible::String.optional, :read_only
+
     # First phone number of the customer
     attr :phone1, Sized::String[1024]
 
@@ -190,9 +194,6 @@ module Fortnox
     # Active If the customer is active.
     attr :active, Bool.optional, Boolean
 
-    # Phone number of the customer. Only present in collection responses.
-    attr :phone, Coercible::String.optional
-
     # External reference
     attr :external_reference, Sized::String[1024]
 

data/lib/fortnox/resources/document.rb

@@ -191,12 +191,12 @@ module Fortnox
     attr :outbound_date, Date.optional, Mappers::Date
 
     # TimeBasisReference Reference to time basis.
-    attr :time_basis_reference, Coercible::Integer.optional
+    attr :time_basis_reference, Coercible::Integer.optional, :read_only
 
     # TotalToPay Total amount to pay.
-    attr :total_to_pay, Coercible::Float.optional
+    attr :total_to_pay, Coercible::Float.optional, :read_only
 
     # WarehouseReady If the document is warehouse ready.
-    attr :warehouse_ready, Bool.optional, Boolean
+    attr :warehouse_ready, Bool.optional, :read_only, Boolean
   end
 end

data/lib/fortnox/resources/invoice.rb

@@ -8,10 +8,11 @@ module Fortnox
       path 'invoices'
       instance_wrapper 'Invoice'
       collection_wrapper 'Invoices'
+      scope 'invoice'
     end
 
     # AccountingMethod Accounting Method.
-    attr :accounting_method, AccountingMethods
+    attr :accounting_method, AccountingMethods, :read_only
 
     # Balance Balance of the invoice.
     attr :balance, Coercible::Float.optional, :read_only
@@ -50,10 +51,10 @@ module Fortnox
     attr :invoice_period_end, Date.optional, :read_only, Mappers::Date
 
     # InvoicePeriodReference Reference to the invoice period.
-    attr :invoice_period_reference, Coercible::String.optional
+    attr :invoice_period_reference, Coercible::String.optional, :read_only
 
     # InvoiceReference Reference to another invoice.
-    attr :invoice_reference, Coercible::String.optional
+    attr :invoice_reference, Coercible::String.optional, :read_only
 
     # InvoiceRows Separate object
     attr :invoice_rows, Strict::Array.of(Structs::InvoiceRow), Mappers::StructArray.for(Mappers::InvoiceRow)

data/lib/fortnox/resources/label.rb

@@ -6,6 +6,7 @@ module Fortnox
       path 'labels'
       instance_wrapper 'Label'
       collection_wrapper 'Labels'
+      scope 'settings'
     end
 
     attr :id, Coercible::Integer.optional, :read_only, :key

data/lib/fortnox/resources/order.rb

@@ -8,6 +8,7 @@ module Fortnox
       path 'orders'
       instance_wrapper 'Order'
       collection_wrapper 'Orders'
+      scope 'order'
     end
 
     # CopyRemarks If remarks shall be copied from order to invoice

data/lib/fortnox/resources/project.rb

@@ -8,6 +8,7 @@ module Fortnox
       path 'projects'
       instance_wrapper 'Project'
       collection_wrapper 'Projects'
+      scope 'project'
     end
 
     # @url Direct URL to the record.

data/lib/fortnox/resources/terms_of_payment.rb

@@ -8,13 +8,14 @@ module Fortnox
       path 'termsofpayments'
       instance_wrapper 'TermsOfPayment'
       collection_wrapper 'TermsOfPayments'
+      scope 'settings'
     end
 
     # @url Direct URL to the record.
     attr :url <=> '@url', Coercible::String.optional, :read_only
 
     # Code The code of the term of payment.
-    key :code, Strict::String
+    key :code, Sized::String[25], :required
 
     # Description The description of the term of payment.
     attr :description, Strict::String, :required

data/lib/fortnox/resources/unit.rb

@@ -8,16 +8,17 @@ module Fortnox
       path 'units'
       instance_wrapper 'Unit'
       collection_wrapper 'Units'
+      scope 'settings'
     end
 
     # @url Direct URL to the record.
     attr :url <=> '@url', Coercible::String.optional, :read_only
 
     # Code The code of the unit.
-    key :code, Strict::String
+    key :code, Sized::String[20], :required
 
     # Description The description of the unit.
-    attr :description, Coercible::String.optional
+    attr :description, Sized::String[100], :required
 
     # CodeEnglish English code of the unit
     attr :code_english, Sized::String[100]

data/lib/fortnox/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Fortnox
-  VERSION = '1.0.0.rc1'
+  VERSION = '1.0.0.rc3'
 end

data/lib/fortnox.rb

@@ -5,14 +5,14 @@ require 'json'
 require 'rest_easy'
 require 'zeitwerk'
 
-loader = Zeitwerk::Loader.for_gem
-loader.collapse("#{__dir__}/fortnox/resources")
-loader.inflector.inflect(
-  'edi_information' => 'EDIInformation'
-)
-loader.setup
-
 module Fortnox
+  @loader = Zeitwerk::Loader.for_gem
+  @loader.collapse("#{__dir__}/fortnox/resources")
+  @loader.inflector.inflect(
+    'edi_information' => 'EDIInformation'
+  )
+  @loader.setup
+
   extend RestEasy
 
   class Error < StandardError; end
@@ -23,11 +23,49 @@ module Fortnox
     def initialize(arg = nil)
       if arg.respond_to?(:status)
         @response = arg
-        super("Request failed: #{arg.status}")
+        super("Request failed: #{arg.status}#{format_body(arg.body)}")
       else
         super
       end
     end
+
+    BODY_FALLBACK_LIMIT = 500
+    private_constant :BODY_FALLBACK_LIMIT
+
+    private
+
+    def format_body(body)
+      return '' if body.nil? || body.empty?
+
+      " - #{error_details(body) || truncate(body.to_s)}"
+    end
+
+    # Fortnox have at least in the past sometimes returned HTML responses on error,
+    # for instance 503 Service Temporarily Unavailable.
+    # In that case, the body might be long and useful for debugging,
+    # so let's truncate it to a reasonable length if we end up here.
+    def truncate(string)
+      string.length > BODY_FALLBACK_LIMIT ? "#{string[0, BODY_FALLBACK_LIMIT]}…" : string
+    end
+
+    def error_details(body)
+      info = error_information(body)
+      message = info && info['message']
+      return nil unless message
+
+      code = info['code']
+      code ? "#{message} (#{code})" : message
+    end
+
+    def error_information(body)
+      parsed = body.is_a?(String) ? JSON.parse(body) : body
+      info = parsed['ErrorInformation'] if parsed.is_a?(Hash)
+      # Fortnox responds with inconsistently-cased error keys (see tests),
+      # so let's normalise to lowercase before reading.
+      info.is_a?(Hash) ? info.transform_keys(&:downcase) : nil
+    rescue JSON::ParserError
+      nil
+    end
   end
 
   class AttributeError < Error; end
@@ -76,6 +114,15 @@ module Fortnox
       parsed['access_token']
     end
 
+    def scopes
+      @loader.eager_load
+      Resource.registered_resources
+              .group_by(&:scope)
+              .reject { |scope, _| scope.nil? }
+              .sort
+              .to_h
+    end
+
     private
 
     def token_request(client_id, client_secret, tenant_id, scopes)

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: fortnox-api
 version: !ruby/object:Gem::Version
-  version: 1.0.0.rc1
+  version: 1.0.0.rc3
 platform: ruby
 authors:
 - Jonas Schubert Erlandsson
@@ -11,7 +11,7 @@ authors:
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2026-05-04 00:00:00.000000000 Z
+date: 2026-05-08 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: countries