fortnox-api 0.9.2 → 1.0.0.rc1

data/README.md

@@ -1,355 +1,341 @@
-# Fortnox API
+# fortnox-api
 
-Wrapper gem for Fortnox AB's version 3 REST(ish) API. If you need to integrate
-an existing or new Ruby or Rails app against Fortnox this gem will save you a
-lot of time, you are welcome. Feel free to repay the community with some nice
-PRs of your own 😃
+Ruby gem for Fortnox's version 3 REST API, built on
+[rest-easy](https://github.com/accodeing/rest-easy). If you need to integrate an existing or new Ruby
+or Rails app against Fortnox this gem will save you a lot of time.
 
-# Status for master
+Feel free to repay the community with some nice PRs of your own.
 
-[![Gem version](https://img.shields.io/gem/v/fortnox-api.svg?style=flat-square)](https://rubygems.org/gems/fortnox-api)
-[![Build Status](https://app.travis-ci.com/ehannes/fortnox-api.svg?branch=master)](https://app.travis-ci.com/github/accodeing/fortnox-api)
+## Supported resources
 
-# Status for development
+Article, Customer, Invoice, Label, Order, Project, TermsOfPayment, Unit
 
-[![Build Status](https://app.travis-ci.com/ehannes/fortnox-api.svg?branch=development)](https://app.travis-ci.com/github/accodeing/fortnox-api)
-[![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)
+Adding more resources is quick and easy, see the
+[Contributing](#contributing) section.
 
-The rough status of this project is as follows (as of spring 2025):
+## Status
 
-- `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
-  accounts and filtering entities.
-- We have ideas for more advanced features, like sorting entities, pagination of
-  results but it's not implemented...
-- A few models implemented. Right now we pretty good support for `Customer`,
-  `Invoice`, `Order`, `Article`, `Label` and `Project`. Adding more models in
-  general is quick and easy (that's the whole point with this gem), see the
-  developer guide further down.
+Version 1.0 is a complete rewrite, currently in release candidate
+(`1.0.0.rc1`). 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.
 
-# Architecture overview
+## Migrating from 0.x
 
-The gem is structured with distinct models for the tasks of data, JSON mapping
-and saving state. These are called: model, type, mapper and repository.
+See the [Migration guide](MIGRATING_TO_1.0.md).
 
-If you come from a Rails background and have not been exposed to other ways of
-structuring the solution to the CRUD problem this might seem strange to you
-since ActiveRecord merges these roles into the `ActiveRecord::Base` class.
+## Architecture overview
 
-To keep it simple: The active record pattern (as implemented by Rails) is easier
-to work with if you only have one data source, the database, in your
-application. The data mapper pattern is easier to work with if you have several
-data sources, such as different databases, external APIs and flat files on disk
-etc, in your application. It's also easier to compose the data mapper components
-into active record like classes than to separate active records parts to get a
-data mapper style structure.
+The gem uses the [rest-easy](https://github.com/accodeing/rest-easy) framework to map between Ruby
+objects and the Fortnox JSON API. Each resource is a class that declares its
+attributes with types and constraints. rest-easy handles the HTTP requests,
+JSON serialisation, and attribute convention mapping (PascalCase in the API,
+snake_case in Ruby).
 
-If you are interested in a more detailed description of the difference between
-the two architectures you can read this post that explains it well using simple
-examples:
-[What’s the difference between Active Record and Data Mapper?](http://culttt.com/2014/06/18/whats-difference-active-record-data-mapper/)
+### Immutability
 
-## Model
+The model instances are immutable. That means:
 
-The model role classes serve as dumb data objects. They do have some logic to
-coheres values etc, but they do not contain validation logic nor any business
-logic at all.
+```ruby
+customer.model.name # => "Old Name"
+customer.model.name = 'New Name' # => NoMethodError
+```
 
-### Attribute
+Any operation that updates state returns a new instance with the updated
+attributes while leaving the old instance alone:
 
-Several of the models share attributes. One example is account, as in a
-`Bookkeeping` account number. These attributes have the same definition,
-cohesion and validation logic so it makes sense to extract them from the models
-and put them in separate classes. For more information, see Types below.
+```ruby
+customer.model.name # => "Old Name"
+updated_customer = customer.update(name: 'New Name')
+updated_customer.model.name # => "New Name"
+customer.model.name # => "Old Name"
+```
 
-### Immutability
+This is how all resources work, they are all immutable.
 
-The model instances are immutable. That means:
+### Types
 
-```ruby
-customer.name # => "Old Name"
-customer.name = 'New Name' # => "New Name"
+Types automatically enforce constraints on values, lengths and, in some cases,
+content of the resource attributes. Types force your data to be correct before
+sending it to the API, which saves you API calls and time debugging. You can
+still get errors from the server; our implementation is not perfect. Also,
+Fortnox sometimes requires a specific combination of attributes.
 
-customer.name == "New Name" # => false
-```
+#### Exceptions
 
-Normally you would expect an assignment to mutate the instance and update the
-`name` field. Immutability explicitly means that you can't mutate state this
-way, any operation that attempts to update state needs to return a new instance
-with the updated state while leaving the old instance alone.
+The gem raises the following exceptions:
 
-So you might think you should do this instead:
+- `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::AttributeError` — base for attribute validation failures.
+  - `Fortnox::ConstraintError` — an attribute value violates a type
+    constraint (max size, format, etc.). Carries `.attribute_name` and
+    `.value`.
+  - `Fortnox::MissingAttributeError` — a required attribute is missing
+    from an API response. Carries `.attribute_name`.
+- `Fortnox::MissingAccessToken` — `Fortnox.access_token=` was not called
+  on the current thread before an API call.
 
-```ruby
-customer = customer.name = 'New Name' # => "New Name"
-```
+## Requirements
+
+Ruby 3.1 or higher.
+
+### Installation
 
-But if you are familiar with chaining assignments in Ruby you will see that this
-does not work. The result of any assignment, `LHS = RHS`, operation in Ruby is
-`RHS`. Even if you implement your own `=` method and explicitly return something
-else. This is a feature of the language and not something we can get around. So
-instead you have to do:
+Add this line to your application's Gemfile:
 
 ```ruby
-customer.name # => "Old Name"
-updated_customer = customer.update( name: 'New Name' ) # => <Fortnox::API::Model::Customer:0x007fdf22949298 ... >
-updated_customer.name == "New Name" # => true
+gem 'fortnox-api'
 ```
 
-And note that:
+And then execute:
 
-```ruby
-customer.name # => "Old Name"
-customer.update( name: 'New Name' ) # => <Fortnox::API::Model::Customer:0x007fdf21100b00 ... >
-customer.name == "New Name" # => false
+```shell
+bundle install
 ```
 
-This is how all the models work, they are all immutable.
+## Authorization
 
-### Exceptions
+Fortnox uses OAuth2 for authorization. This gem supports the **client
+credentials** flow, which is the recommended way to authenticate server-to-server
+integrations. The older refresh token flow is no longer supported. Read more
+about this change in the
+[Fortnox blog post](https://www.fortnox.se/developer/blog/say-goodbye-to-refresh-tokens-).
 
-Models can throw `Fortnox::API::AttributeError` if an attribute is invalid in
-some way (for instance if you try to assign a too long string to a limited
-string attribute) and `Fortnox::API::MissingAttributeError` if a required
-attribute is missing.
+With client credentials you can request a new access token at any time using
+three pieces of information: your **client ID**, **client secret**, and the
+**tenant ID** of the Fortnox account you are integrating with.
 
-## Type
+### Prerequisites
 
-The types automatically enforce the constraints on values, lengths and, in some
-cases, content of the model attributes. Types forces your models to be correct
-before sending data to the API, which saves you a lot of API calls and rescuing
-the exception we throw when we get a 4xx/5xx response from the server (you can
-still get errors from the server; our implementation is not perfect. Also,
-Fortnox sometimes requires a specific combination of attributes).
+You need:
 
-## Repositories
+- A Fortnox developer account
+  ([register here](https://developer.fortnox.se/getting-started/))
+- A Fortnox app in the developer portal with:
+  - Service account setting enabled
+  - Correct scopes configured
+  - A redirect URL
+- A Fortnox test environment for testing your integration
 
-Used to load, update, create and delete model instances. These are what is
-actually wrapping the HTTP REST API requests against Fortnox's server.
+Read the
+[Fortnox getting started guide](https://developer.fortnox.se/getting-started/)
+and
+[authorization documentation](https://www.fortnox.se/developer/authorization/get-access-token-using-client-credentials)
+for more details.
 
-### Exceptions
+### Initial setup
 
-Repositories can throw `Fortnox::API::RemoteServerError` if something went wrong
-at Fortnox.
+Before you can use client credentials you need to perform a one-time
+authorization code exchange. This grants your app access to a specific Fortnox
+account and gives you the **tenant ID** you need for all future token requests.
 
-## Mappers
+This gem includes an executable to help with this:
 
-These are responsible for the mapping between our plain old Ruby object models
-and Fortnox JSON requests. The repositories use the mappers to map models to
-JSON requests and JSON to model instances when working with the Fortnox API, you
-will not need to use them directly.
+```shell
+fortnox-setup
+```
 
-# Requirements
+The script will:
 
-This gem is built for Ruby 2.6 or higher (see Travis configuration file for what
-versions we are testing against).
+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
 
-## Installation
+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).
 
-Add this line to your application's Gemfile:
+### Requesting access tokens
+
+Once you have a tenant ID, you can request access tokens programmatically.
+Access tokens expire after 1 hour, but you can request a new one at any time:
 
 ```ruby
-gem 'fortnox-api'
-```
+require 'fortnox'
 
-And then execute:
+token = Fortnox.request_access_token(
+  client_id: 'your-client-id',
+  client_secret: 'your-client-secret',
+  tenant_id: 'your-tenant-id'
+)
 
-```shell
-$ bundle
+Fortnox.access_token = token
 ```
 
-Or install it yourself as:
+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.
+
+### Updating access tokens in env files
+
+For development and testing, the gem includes an executable that reads your
+credentials from an env file, requests a new access token, and writes it back:
 
 ```shell
-$ gem install fortnox-api
+fortnox-update-env              # reads/writes .env
+fortnox-update-env .env.local   # reads/writes a specific file
 ```
 
-# Usage
+See [.env.test.local.template](.env.test.local.template) for the required
+variables.
 
-## Authorization
+### Multiple Fortnox accounts
 
-> :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 will be
-> deprecated April 30, 2025 according to Fortnox. This gem will no longer support
-> the old way of authorization from v0.9.0.
+The access token is stored per thread, so concurrent threads — Sidekiq
+workers, Puma threads, etc. — can use different tokens without leaking to
+each other. Each thread must set its own token before making API calls.
 
-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
-integration to Fortnox, not build a public app to in the marketplace". Yeah, we
-agree... You don't need to release the app on the Fortnox Marketplace, but you
-need that Fortnox app. Also, see further Fortnox app requirements down below.
+Within a single thread you can switch tokens between calls. Each call uses
+the token currently set on the calling thread:
 
-Start your journey at
-[Fortnox getting started guide](https://developer.fortnox.se/getting-started/).
-Note that there's a script to authorize the Fortnox app to your Fortnox account
-bundled with this gem to help you getting started, see
-[Initialization](#initialization). Also read
-[Authorizing your integration](https://developer.fortnox.se/general/authentication/).
+```ruby
+Fortnox.access_token = 'account1_token'
+Fortnox::Customer.all
 
-Things you need:
+Fortnox.access_token = 'account2_token'
+Fortnox::Customer.all
+```
 
-- A Fortnox developer account
-- A Fortnox app with:
-  - Service account setting enabled (it's used in server to server integrations,
-    which this is)
-  - Correct scopes set
-  - A redirect URL (just use a dummy URL if you want to, you just need the
-    parameters send to that URL)
-- A Fortnox test environment so that you can test your integration.
-
-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 **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
-as you have a valid refresh token you will be available to request new tokens.
-
-The gem exposes a specific repository for renewing tokens. You use it like this:
+## Usage
 
-```ruby
-require 'fortnox/api'
+Set the access token before making any API calls:
 
-tokens = Fortnox::API::Repository::Authentication.new.renew_tokens(
-  refresh_token: 'a valid refresh token',
-  client_id: "the integration's client id",
-  client_secret: "the integration's client secret"
-)
+```ruby
+require 'fortnox'
 
-# You probably want to persist your tokens somehow...
-store_refresh_token(tokens[:refresh_token])
-store_access_token(tokens[:access_token])
+Fortnox.access_token = 'your-access-token'
+```
 
-# Set the new access token
-Fortnox::API.access_token = tokens[:access_token]
+### Listing all records
 
-# The gem will now use the new access token
-Fortnox::API::Repository::Customer.new.all
+```ruby
+Fortnox::Customer.all
 ```
 
-It's up to you to provide a valid token to the gem and to renew it regularly,
-otherwise you need to start over again with the
-[Initialization](#initialization).
-
-## Get tokens
+`.all`, `.search`, `.only`, and `.find(hash)` return a `Fortnox::Collection`
+— an iterable wrapper that also exposes the pagination metadata Fortnox
+returns alongside collection responses:
 
-There's a script in `bin/get_tokens` to issue valid access and refresh tokens.
-Provide valid credentials in `.env`, see `.env.template` or have a look in the
-script itself to see what's needed.
+```ruby
+customers = Fortnox::Customer.all
+customers.first.model.name # => "Acme Corp"
+customers.size             # => 50
+customers.total            # => 327
+customers.pages            # => 7
+customers.current_page     # => 1
+```
 
-### Configuration
+`Collection` is `Enumerable`, so `.each`, `.map`, `.select`, `.first`, etc.
+all work as expected.
 
-The gem can be configured in a `configure` block, where `setting` is one of the
-settings from the table below.
+Fortnox's collection endpoints return fewer attributes per record than
+single-resource endpoints, so instances from a `Collection` are flagged as
+partial. Check `instance.meta.partial?` and re-fetch via `find(id)` if you
+need the full record:
 
 ```ruby
-Fortnox::API.configure do |config|
-  config.setting = 'value'
-end
+customers = Fortnox::Customer.all
+customers.first.meta.partial?            # => true
+Fortnox::Customer.find(1).meta.partial?  # => false
 ```
 
-| Setting     | Description                       | Required | Default                                                         |
-| ----------- | --------------------------------- | -------- | --------------------------------------------------------------- |
-| `base_url`  | The base url to Fortnox API       | No       | `'https://api.fortnox.se/3/'`                                   |
-| `token_url` | The url to Fortnox token endpoint | No       | `'https://apps.fortnox.se/oauth-v1/token'`                      |
-| `debugging` | For debugging                     | No       | `false`                                                         |
-| `logger`    | The logger to use                 | No       | A simple logger that writes to `$stdout` with log level `WARN`. |
+### Finding a record
 
-### Support for multiple Fortnox accounts
+```ruby
+# By ID
+customer = Fortnox::Customer.find(1)
 
-Yes, we support working with several accounts at once. Simply switch access
-token between calls. The token is stored in the current thread, so it's thread
-safe.
+# By query parameters (pagination, limits, etc.)
+customers = Fortnox::Customer.find(limit: 10, offset: 0)
+```
 
-```ruby
-repository = Fortnox::API::Repository::Customer.new
+Note that `find` supports a hash as an argument, which adds the given keys as
+HTTP parameters to the call. This lets you use limits, offsets, and pagination.
+See the
+[Fortnox documentation](https://developer.fortnox.se/general/parameters/)
+for available parameters.
 
-Fortnox::API.access_token = 'account1_access_token'
-repository.all # Calls account1
+The returned object wraps the model. Access attributes through `.model`:
 
-Fortnox::API.access_token = 'account2_access_token'
-repository.all # Calls account2
+```ruby
+customer = Fortnox::Customer.find(1)
+customer.model.name       # => "Acme Corp"
+customer.model.city       # => "Stockholm"
+customer.unique_id        # => "1"
 ```
 
-### Automatic access tokens rotation (deprecated)
+### Creating a record
 
-As of november 2021 and the new OAuth 2 flow, Fortnox has made
-[adjustments to the rate limit](https://developer.fortnox.se/blog/adjustments-to-the-rate-limit/)
-and it is no longer calculated per access token (if you are not using the old
-auth flow, but that flow is deprecated in this gem since v0.9.0).
+Use `.stub` to build a new instance and `.save` to persist it:
 
-# Usage
+```ruby
+customer = Fortnox::Customer.stub(name: 'Acme Corp', city: 'Stockholm')
+result = Fortnox::Customer.save(customer)
+result.model.customer_number # => "1"
+```
 
-## Repositories
+### Updating a record
 
-Repositories are used to load,save and remove entities from the remote server.
-The calls are subject to network latency and are blocking. Do make sure to
-rescue appropriate network errors in your code.
+Fetch, update, and save. Models are immutable, so `.update` returns a new
+instance:
 
 ```ruby
-require 'fortnox/api'
+customer = Fortnox::Customer.find(1)
+updated = customer.update(name: 'Acme Inc')
+Fortnox::Customer.save(updated)
+```
 
-Fortnox::API.access_token = 'valid_access_token'
+### Searching
 
-# Instanciate a repository
-repo = Fortnox::API::Repository::Customer.new
+```ruby
+Fortnox::Customer.search(name: 'Acme')
+```
 
-# Get a list of all the entities
-repo.all #=> <Fortnox::API::Collection:0x007fdf2104575638 @entities: [<Fortnox::API::Customer::Simple:0x007fdf21033ee8>, <Fortnox::API::Customer::Simple:0x007fdf22994310>, ... ]
+### Filtering
 
-# Get entity by id
-repo.find( 5 ) #=> <Fortnox::API::Model::Customer:0x007fdf21100b00>
+Some resources support server-side filters:
 
-# Get entities by attribute
-repo.find_by( customer_number: 5 ) #=> <Fortnox::API::Collection:0x007fdf22994310 @entities: [<Fortnox::API::Customer::Simple:0x007fdf22949298>]
+```ruby
+Fortnox::Invoice.only('unpaid')
 ```
 
-If you are eagle eyed you might have spotted the different classes for the
-entities returned in a collection vs the one we get from find. The simple
-version of a class is used in thouse cases where the API-server doesn't return a
-full set of attributes for an entity. For customers the simple version has 10
-attributes while the full have over 40.
+### Gotchas
 
-### Additional parameters
+See [docs/gotchas.md](docs/gotchas.md) for known quirks and edge cases in the
+Fortnox API.
 
-Note that `find` also supports a hash as an argument, which simply adds given
-hash keys as HTTP parameters to the call. This will let you search, sort, use
-limits and offsets as well as do pagination. See
-[Fortnox documentation](https://developer.fortnox.se/general/parameters/) for
-more information about available parameters.
+### Resources
 
-```ruby
-# Get second page of Customers
-Fortnox::API::Repository::Customer.new.find { page: 2 }
-```
+Each resource maps to a Fortnox API endpoint. Attributes are typed and
+validated before sending data to the API. Read-only attributes (like `url`)
+cannot be set when creating or updating records.
 
-## Entities
+Resources that share structure inherit from a common base. For example,
+`Invoice` and `Order` both extend `Document`, which defines shared attributes
+like administration fee, delivery address, and row items.
 
-All the repository methods return instances or collections of instances of some
-resource class such as customer, invoice, item, voucher and so on.
+## Changelog
 
-Instances are immutable and any update returns a new instance with the
-appropriate attributes changed (see the Immutable section under Architecture
-above for more details). To change the properties of a model works like this:
+See the [Changelog](CHANGELOG.md).
 
-```ruby
-require 'fortnox/api'
+## Development
 
-customer #=> <Fortnox::API::Model::Customer:0x007fdf228db310>
-customer.name #=> "Nelly Bloom"
-customer.update( name: "Ned Stark" ) #=> <Fortnox::API::Model::Customer:0x0193a456ff0307>
-customer.name #=> "Nelly Bloom"
+See the [Developer readme](DEVELOPER_README.md).
 
-updated_customer = customer.update( name: "Ned Stark" ) #=> <Fortnox::API::Model::Customer:0x0193a456fe3791>
-updated_customer.name #=> "Ned Stark"
-```
+## Contributing
 
-The update method takes an implicit hash of attributes to update, so you can
-update as many as you like in one go.
+See the [Contribute readme](CONTRIBUTE.md).
 
-# Contributing
+## License
 
-See the [CONTRIBUTE](CONTRIBUTE.md) readme.
+[LGPL-3.0](LICENSE.md). Copyright (c) 2015-2026 Accodeing to you KB.