This version of the API will be shut down starting from December 31, 2022. We will no longer accept new users after this date. APIv2 is available at https://api.fiken.no/

Introduction

!!!

_APIv1 is deprecated - APIv2 is available at https://api.fiken.no/

!!!

Fiken.no is an online accounting system aimed at making accounting easy for small businesses. This document describes Fiken's API.

For changes in the API please see the Change Log

Table of Contents

Using the API

Use of this API in production environments on live data is associated with a fee. Please contact Fiken for further details.

Fiken's REST style

We use the HAL media type which is a simplistic JSON-based data format. It's two main advantages compared to using plain JSON data is that it has a standard way of conveying links in the document and it can embedded other resources inside a response. The links and embedded data are inside the two object properties _links and _embedded.

Links are used to point the resource client to data that can be discovered from this resource, in a similar fashion that one links from one news story to other related news stories. One important addition that HAL's linking concept brings in addition to normal web links are link relations or rels for short. A link relation documents what kind of link it is and it tells the client what kind of data it can find if it follows the link. There is a set of standardized link relations in IANA's link relation registry. Any non-URI relations comes from this link registry. RFC5988 - Web Linking describes more on the link relation concepts.

Embedded resources is a way to allow for fine grained resources, without the overhead of the client having to do too many requests. Embedding uses link relations like links, but instead of including just a reference to the data, the actual objects are inlined inside the document. The object keys can be either full URIs or names registered in the link relations registry.

An example HAL response for an imaginary "news item" resource looks like this:

{
  "title": "Kasper arrestert igjen!",
  "body": "Kasper (36) stjal i går hatten til Politimester Sebastian, men ble arrestert etter kort tid."
  "published": "1955-05-06",
  "_links": {
    "self": {
      "href": "..."
    },
    "http://example.org/rels/related": {
      "href": "..."
    }
  },
  "_embedded": {
    "http://example.org/rels/comment": [
      {
        "text": "...",
        "author": "Tante Sofie",
        "_links": {
          "self": {
            "href": "..."
          },
          "author": {
            "href": "..."
          }
        }
      }
    ]
  }
}

This document describes a news item with three properties; title, body and published. In addition the document has two links, one called self and one called http://example.org/rels/related. Fiken will use both the standardized link relations and our own relations. The first link is a pointer back to the resource itself, and the second link is a reference to related news stories. If the client is rendering the news story it can choose to follow the related link and display the headlines of the stores as a part of the rendering.

The document also includes a list of comments. The object key http://example.org/rels/comment is a normal link relation, but the data is inlined. Each object in the array is a full HAL object so they also include _links and could also include other _embedded resources. If a client wanted to update the comment it could do so by doing a PUT request with just the embedded object and send it to the comment's self link.

Services vs Data

We have two kinds of resources; data resources and service resources. Data resources are lists and details on contacts, invoices, sales etc. When manipulating these resources the client always read and write the entire object. New items can often be created by posting new items to the collection directly.

Service resources are different, they only support posting requests and will reply with responses. They will normally create other resources and include those in its response.

Base URL

All URLs start with https://fiken.no/api/v1. Note that TLS is required, unencrypted HTTP is not supported. Although we currently redirect HTTP requests to HTTPS, you are not allowed to this with your application as using HTTP is a security risk. In the future we might respond with 403 Forbidden instead.

Concurrent requests / rate limiting

You are only allowed to make a single concurrent API-request. Breaking this rule might give you a 429 response.

Request

Authentication

The authentication is done with HTTP Basic Authentication. Your normal email and password could be used for authentication, but for audit purposes it is recommended that you create a separate user which access Fiken through the API. Even if the user who changed the object is not displayed in Fiken today we still store the data in our audit logging.

To test the authentication do a GET to https://fiken.no/api/v1/whoAmI

Response

Response code

All HTTP codes should be expected with their normal semantics. These are some of the common ones:

  • 200 for successful GET
  • 201 for successful POST where you get a Location-header for the created content
  • 204 for DELETE/PUT and POSTS that doesn't always create a single new resource
  • 400 when invalid content has be sent (for instance a required field is missing, unexpected fields, wrong format, etc)
  • 401: when the user is not authenticated
  • 403: when the user does not have the proper authorization
  • 404: you know this one...
  • 405: When you are trying a method to a resource which doesn't support it (i.e. DELETE on an account).
  • 415: Wrong media type. we accept application/json only.
  • 418: Wow, you win a free dinner with the Fiken team.

Response Content

The default content type on the result of GET requests is application/hal+json. On successful POSTs/PUTs and DELETEs an empty body is returned. For successful POSTs a Location header is given in most cases.

Pagination and sorting

By default the API returns all elements in a collection resource, if nothing else is specified. The collection resources marked as sortable in the table below also supports pagination using request and response headers.

To request a collection resource with pagination, query the resource with the request headers Fiken-Api-Page and Fiken-Api-Page-Size, note that both headers need to be set to enable pagination. The page counter starts at 0.

The response will contain up to Fiken-Api-Page-Size elements and the response headers below, detailing how many elements the resource has in total and the total number of pages as well.

By default the API returns the resources in the order they were created, if nothing else is specified in the documentation.

Requesting a page out of bounds will result in an empty page.

To change the sort order for a resource, specify one or more sort fields and an optional direction using the Fiken-Api-Sort-By request header, see the table below for the relevant fields on each resource.

Sort by created date in descending order

Fiken-Api-Sort-By: created desc

Sort by created date in descending order, and the name in ascending order:

Fiken-Api-Sort-By: created desc, name asc
URI Sortable? Sortable fields
https://fiken.no/api/v1/rel/companies Yes created, lastModified, name, organizationNumber
https://fiken.no/api/v1/rel/sales Yes created, lastModified, date
https://fiken.no/api/v1/rel/attachments No
https://fiken.no/api/v1/rel/contacts Yes created, lastModified, name, email
https://fiken.no/api/v1/rel/payments No
https://fiken.no/api/v1/rel/products Yes created, lastModified, name, unitPrice, productNumber
https://fiken.no/api/v1/rel/accounts No
https://fiken.no/api/v1/rel/bank_accounts Yes created, lastModified, name, number, bankAccountNumber
https://fiken.no/api/v1/rel/invoices Yes created, lastModified, issueDate
https://fiken.no/api/v1/rel/creditNotes Yes created, lastModified, issueDate
https://fiken.no/api/v1/rel/create-invoice N/A
https://fiken.no/api/v1/rel/document-sending-service N/A
https://fiken.no/api/v1/rel/create-general-journal-entry-service N/A
https://fiken.no/api/v1/rel/search No

Pagination Request Headers

Request Header Format Description
Fiken-Api-Page integer Which page to request, starting with 0
Fiken-Api-Page-Size integer The number of elements to be returned on each page
Fiken-Api-Sort-By string Optional sort specification

Pagination Response Headers

Response Header Format Description
Fiken-Api-Page integer From the request header
Fiken-Api-Page-Size integer From the request header
Fiken-Api-Page-Count integer The total number of pages in this resource with this page size
Fiken-Api-Result-Count integer The total number of elements in this resource

Filtering

Some collections support filtering, and depending on the type of field, different filters can be used. Dates are the most complex, and allow you do apply different filters with different parameter names. For instance, for a field called date, the following mutations are available:

Parameter Field Format Description
date date yyyy-MM-dd date equal to parameter value
dateLe date yyyy-MM-dd date less than or equal to parameter value
dateLt date yyyy-MM-dd date less than parameter value
dateGe date yyyy-MM-dd date greater than or equal to parameter value
dateGt date yyyy-MM-dd date greater than parameter value

All date-fields will have these mutations of parameter name that applies the

Errors

On many types of errors (client and server side) the body will contain a vnd.error+json result. Please check the message in this result AND the HTTP code before contacting support for any questions.

Audit

The client MAY set an X-Request-ID header. If set it has to be a valid UUID. If it is not present or invalid, the server will generate a new X-Request-ID. All responses will always contain this X-Request-ID which could be used for audit and support purposes. We use this header field in our logs and audit trail, and it's a good idea for you to do the same.

Start URL

The start URL is https://fiken.no/api/v1. This is the only URL that the your client shall access that should be hard coded in the application. The rest of the URLs should be discovered by the _links.

Live testing

You can use the HAL Browser installed at /api/browser to browse/test the API.

Rels

These are the link relation specified by Fiken. In the documentation their last path segment is often used e.g., companies for https://fiken.no/api/v1/rel/companies.

URI Methods Objects Typical use case
https://fiken.no/api/v1/rel/companies GET Company Get companies (name and organization number) along with links to sales, accounts and contacts
https://fiken.no/api/v1/rel/sales GET, POST Sale Register new sales in Fiken (and list existing ones). Get links to add attachments and payments.
https://fiken.no/api/v1/rel/attachments GET, POST Attachment Add ("bilag") to sales, such as invoices, payment receipts, etc.
https://fiken.no/api/v1/rel/contacts GET, POST, PUT Contact Add, update and find contacts (customers and suppliers).
https://fiken.no/api/v1/rel/payments GET, POST Payment Add payments to a sale.
https://fiken.no/api/v1/rel/products GET, POST, PUT Product List all products
https://fiken.no/api/v1/rel/accounts GET Account Find the companies' bookkeeping accounts in Fiken. Used for registering payments and income accounts on sales
https://fiken.no/api/v1/rel/bank_accounts GET BankAccount List bank accounts registered in Fiken. Needed when creating invoices.
https://fiken.no/api/v1/rel/invoices GET Invoice List invoices.
https://fiken.no/api/v1/rel/creditNotes GET Credit Note List credit notes.
https://fiken.no/api/v1/rel/create-invoice POST Create Invoice Request Create invoice.
https://fiken.no/api/v1/rel/document-sending-service POST Create Invoice Request Create a message from an business document.
https://fiken.no/api/v1/rel/create-general-journal-entry-service POST General journal entry Create general journal entries ("Fri postering").
https://fiken.no/api/v1/rel/search GET,POST Search service Search the company for other resources

Data

See data resources for documentation on the data classes.

Services

See services for documentation on services.