Introduction

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. This is currently not automatically enforced, but it might be in the future. If you break this rule you might be banned. In case of a ban please contact us to be unbanned.

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:

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.

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
URISortable?Sortable fields
https://fiken.no/api/v1/rel/companiesYescreated, name, organizationNumber
https://fiken.no/api/v1/rel/salesYescreated, date
https://fiken.no/api/v1/rel/attachmentsNo
https://fiken.no/api/v1/rel/contactsYescreated, name, email
https://fiken.no/api/v1/rel/paymentsNo
https://fiken.no/api/v1/rel/productsYescreated, name, unitPrice, productNumber
https://fiken.no/api/v1/rel/accountsNo
https://fiken.no/api/v1/rel/bank_accountsYescreated, name, number, bankAccountNumber
https://fiken.no/api/v1/rel/invoicesYescreated, issueDate
https://fiken.no/api/v1/rel/creditNotesYescreated, issueDate
https://fiken.no/api/v1/rel/create-invoiceN/A
https://fiken.no/api/v1/rel/document-sending-serviceN/A
https://fiken.no/api/v1/rel/create-general-journal-entry-serviceN/A
https://fiken.no/api/v1/rel/searchNo

Pagination Request Headers

Request HeaderFormatDescription
Fiken-Api-PageintegerWhich page to request, starting with 0
Fiken-Api-Page-SizeintegerThe number of elements to be returned on each page
Fiken-Api-Sort-BystringOptional sort specification

Pagination Response Headers

Response HeaderFormatDescription
Fiken-Api-PageintegerFrom the request header
Fiken-Api-Page-SizeintegerFrom the request header
Fiken-Api-Page-CountintegerThe total number of pages in this resource with this page size
Fiken-Api-Result-CountintegerThe total number of elements in this resource

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.

URIMethodsObjectsTypical use case
https://fiken.no/api/v1/rel/companiesGETCompanyGet companies (name and organization number) along with links to sales, accounts and contacts
https://fiken.no/api/v1/rel/salesGET, POSTSaleRegister new sales in Fiken (and list existing ones). Get links to add attachments and payments.
https://fiken.no/api/v1/rel/attachmentsGET, POSTAttachmentAdd ("bilag") to sales, such as invoices, payment receipts, etc.
https://fiken.no/api/v1/rel/contactsGET, POST, PUTContactAdd, update and find contacts (customers and suppliers).
https://fiken.no/api/v1/rel/paymentsGET, POSTPaymentAdd payments to a sale.
https://fiken.no/api/v1/rel/productsGET, POST, PUTProductList all products
https://fiken.no/api/v1/rel/accountsGETAccountFind the companies bookkeeping accounts in Fiken. Used for registering payments and income accounts on sales
https://fiken.no/api/v1/rel/bank_accountsGETBankAccountList bank accounts registered in Fiken. Needed when creating invoices.
https://fiken.no/api/v1/rel/invoicesGETInvoiceList invoices.
https://fiken.no/api/v1/rel/creditNotesGETCredit NoteList credit notes.
https://fiken.no/api/v1/rel/create-invoicePOSTCreate Invoice RequestCreate invoice.
https://fiken.no/api/v1/rel/document-sending-servicePOSTCreate Invoice RequestCreate a message from an business document.
https://fiken.no/api/v1/rel/create-general-journal-entry-servicePOSTGeneral journal entryCreate general journal entries ("Fri postering").
https://fiken.no/api/v1/rel/searchGET,POSTSearch serviceSearch the company for other resources

Data

See data resources for documentation on the data classes.

Services

See services for documentation on services.