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 the 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.

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.

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.

Data Types

Date

Dates are represented as strings formatted as YYYY-MM-DD.

Examples:

Amount

Amounts are always represented as a number, and specifies the number of cents in the amount. Fractions will be ignored.

Examples:

Account

An account is a string with either four digits, or four digits, a colon and five digits ("reskontro"). Examples:

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

Objects

Company

FieldTypeAlways presentDescription
nameStringYesThe company name
organizationNumberStringNo

Example

{
  "name": "Min første bedrift",
  "organizationNumber": "987654321",
  "_links": {
    "self": {
      "href": "https://fiken.no/api/v1/companies/min-forste-bedrift"
    },
    "https://fiken.no/api/v1/rel/contacts": {
      "href": "..."
    },
    "https://fiken.no/api/v1/rel/search": {
      "href": "..."
    }
  }
}

Sale

FieldTypeAlways presentDescription
dateDateyesThe date the sale was done.
kindStringyesEither CASH_SALE, INVOICE or EXTERNAL_INVOICE.
identifierString (max 50)yesInvoice/sale number or similar.
paidBooleanyesTrue if the sale has been marked as paid.
linesArray[OrderLine] (see below)yesAt least one line has to be included.
customerURImaybeThe related customer for this sale.
currencyStringnoThe currency of this sale, if different than NOK. Currently read-only.
dueDateDatenoWrite only.
kidStringnoIf present it has to be a valid Norwegian KID-number. Write only.
paymentAccountAccountmaybeFor instance "1920:10001". Write only.
paymentDateDatemaybeWrite only.

Kind

Three kinds of sales can be registered; cash sales, invoices issued by Fiken and invoices issued by other systems. A cash sale is a sale that was paid at the same time as the transaction was done ("Kontantsalg"); although not necessarily paid in cash.

Invoices issued by Fiken are the same as those created in the Fiken web pages.

If an external system issued an invoice it can also be registered in Fiken. If a payment account and date is included, the invoice will be marked as payed. If not, payments can be registered on this invoice at a later time.

Note that it is currently not possible to create a Sale with a foreign currency.

FieldCash saleExternal invoice
customermust not be includedrequired
paymentAccountrequiredoptional. If present, paymentDate is required
paymentDaterequired, must be the same as the sale dateoptional. If present, paymentAccount is required
Link RelationReferences
attachmentsAttachments of this sale. This can be a generated PDF for invoices issued by Fiken.
paymentsPayments of this sale

Example

{
  "date": "2014-04-22",
  "identifier": "1337",
  "lines": [
    {
      "description": "12 x SKU 7461 Blue high-speed Yo-Yo",
      "netPrice" : 12000,
      "vat" : 6250,
      "account": "3000",
      "vatType" : "HIGH"
    }
  ],
  "kind": "CASH_SALE",
  "paymentAccount" : "1920:10001",
  "paymentDate": "2014-04-22"
}


{
  "date": "2014-12-14",
  "identifier": "1338",
  "lines": [
    {
      "description": "Something spitzy",
      "netPrice" : 1200,
      "vat" : 625,
      "vatType" : "HIGH"
    }
  ],
  "kind": "EXTERNAL_INVOICE",
  "company": "https://fiken.no/api/v1/companies/aleksander-blomskold-consulting",
  "customer": "https://fiken.no/api/v1/companies/aleksander-blomskold-consulting/contacts/1813088"
}

Attachment

The content to post should be a form/multipart with the following parts:

SaleAttachment

FieldTypeRequiredDescription
filenameString (max 200)YesThe filename. Must end with either .png, .jpeg, .jpg, .gif or .pdf
commentString (max 4000)NoA comment for this attachment.
attachToPaymentbooleanYesTrue if this attachment may document the payment (i.e. transaction receipt from credit card/payment company, export from bank, etc.)
attachToSalebooleanYesTrue if this attachment may document the sale (i.e. invoice, etc)

At least one of attachToPayment and attachToSale must be true.

Example

With curl:

curl -n -v https://fiken.no/api/v1/companies/aleksander-blomskold-consulting/sales/1135071/attachments  \
-F "AttachmentFile=@adwords.png" -F 'SaleAttachment={"filename":"adwords.png", "attachToSale": true, "attachToPayment": false}'

Account

Note that the accounts URL is templated with the accounting year (four digits).

Example

{
  "_links": {
    "self": {
      "href": "https://fiken.no/api/v1/companies/min-forste-bedrift/accounts/{year}"
    }
  },
  "_embedded": {
    "accounts": [
      {
        "code": "1001",
        "name": "Forskning og utvikling, ervervet",
        "_links": {
          "self": {
            "href": "..."
          }
        }
      },
      {
        "code": "1500:10021",
        "name": "Kaptein Sabeltann",
        "_links": {
          "self": {
            "href": "..."
          }
        }
      }
    ]
  }
}

Bank account

For now these are simple objects, but you need the url of them to create invoices

FieldTypeDescription
nameThe name used in Fiken when registering the account

OrderLine

FieldTypeRequiredDescription
descriptionString (max 200)A description of the line (product name, etc)
netPriceAmountYesThe net price in NOK øre
vatAmountYesThe VAT in NOK øre
accountAccountMaybeThe income (sales) / expense (purchase) account. Required for purchases. If not provided a sensible default is chosen for sales
vatTypeStringYesSee VatTypes for sales and purchases below. "HIGH" is the most common.
netPriceInCurrencyAmountMaybeThe net price in the foreign currency (set if and only if it is on a sale in a foreign currency)
vatInCurrencyAmountMaybeThe VAT in the foreign currency (set if and only if it is on a sale in a foreign currency)

VatTypes for sales

ValueCorresponding SAF-T code
NONE7
HIGH3
MEDIUM31
RAW_FISH32
LOW33
EXEMPT_IMPORT_EXPORT52
EXEMPT5
OUTSIDE6
EXEMPT_REVERSE51

VatTypes for purchases

ValueCorresponding SAF-T code
NONE0
HIGH1
MEDIUM11
RAW_FISH12
LOW13
EXEMPT_IMPORT_EXPORT85
HIGH_DIRECT14
HIGH_BASIS21
MEDIUM_DIRECT15
MEDIUM_BASIS22
NONE_IMPORT_BASIS23
HIGH_IMPORT_DEDUCTIBLE81
HIGH_IMPORT_NONDEDUCTIBLE82
MEDIUM_IMPORT_DEDUCTIBLE83
MEDIUM_IMPORT_NONDEDUCTIBLE84
HIGH_FOREIGN_SERVICE_DEDUCTIBLE86
HIGH_FOREIGN_SERVICE_NONDEDUCTIBLE87
LOW_FOREIGN_SERVICE_DEDUCTIBLE88
LOW_FOREIGN_SERVICE_NONDEDUCTIBLE89
HIGH_PURCHASE_OF_EMISSIONSTRADING_OR_GOLD_DEDUCTIBLE91
HIGH_PURCHASE_OF_EMISSIONSTRADING_OR_GOLD_NONDEDUCTIBLE92

Contact

FieldTypeRequiredMutableDescription
nameStringyesYesThe (company) name of the customer
emailStringnoYes
organizationIdentifierStringnoYesOrganization number or similar
address.postalCodeStringnoYes
address.postalPlaceStringnoYes
address.address1StringnoYes
address.address2StringnoYes
address.countryStringnoYes
phoneNumberStringnoYes
customerNumberIntegernoRead-only
customerBooleannoWrite-onlyIf true, a customer number will be generated if not already present
supplierNumberIntegernoRead-only
supplierBooleannoWrite-onlyIf true, a supplier number will be generated if not already present
currencyStringnoYesDefault foreign currency to use when creating invoice to this contact (USD, EUR, SEK etc)
memberNumberIntegernoYesA number that can be used to connect a contact to your own data
languageStringnoYesThe language to use when sending documents to this contact. NORWEGIAN or ENGLISH. Defaults to NORWEGIAN.

Examples

Creating a customer

POST
{
  "name": "Pianolærer Kamomilla",
  "email": "kamomilla@kardemommeby.com",
  "organizationIdentifier": "987654321",
  "address": {
    "postalCode": "1337",
    "postalPlace": "Kardemommeby",
    "address1": "Tårngata 2"
  },
  "customer": true
}

Listing all contacts

GET
{
  "_links": {
    "self": {
      "href": "..."
    }
  },
  "_embedded": {
    "contacts": [
      {
        "_links": {
          "self": {
            "href": "..."
          }
        },
        "name": "Pianolærer Kamomilla",
        "email": "kamomilla@kardemommeby.com",
        "organizationIdentifier": "987654321",
        "address": {
          "postalCode": "1337",
          "postalPlace": "Kardemommeby",
          "address1": "Tårngata 2"
        },
        "customerNumber": "12345"
      },
      {
        "_links": {
          "self": {
            "href": "..."
          }
        },
        "name": "Kasper, Jesper og Jonatans inkassobyrå",
        "email": "kjenning@politimester-sebastian.no",
        "organizationIdentifier": "865723112",
        "address": {
          "postalCode": "2145",
          "postalPlace": "Kardemommeby"
        },
        "supplierNumber": "666"
      }
    ]
  }
}

Payment

FieldTypeRequiredDescription
dateDateYesThe date when the payment was done
accountAccountYesThe accounting account that received the payment. For example "1920:10002".
amountAmountYes

Note that payments to sales and purchases in foreign currency is currently not supported by the API

Example

Posting a payment of 123,45.

{
  "uuid": "...",
  "date": "2001-02-03",
  "account": "1920:10002",
  "amount": 12345
}

Product

FieldTypeRequiredDescription
nameDateYesThe name of the product
unitPriceAmountNoThe unit price in cents(øre)
incomeAccountAccountYesThe accounting account that will receive the payment. For example "3000".
vatTypeStringYesOne of: {"HIGH", "MEDIUM", "LOW", "EXEMPT", "EXEMPT_IMPORT_EXPORT", "EXEMPT_REVERSE", "OUTSIDE", "NONE"}. "HIGH" is the most common.
activeBooleanYesIf product is in use or not
productNumberStringNo

Example

Posting a new product "Spade"

{
    "name": "Spade",
    "unitPrice": 300000,
    "incomeAccount": "3000",
    "vatType": "HIGH",
    "active": true,
    "productNumber": "1"
}

Invoice

To create an invoice, use the Create Invoice Service.

For invoices created by Fiken there will always be a sale. Attachments and payment data are available from the Sale object.

Fields

FieldTypeAlways presentDescription
invoiceNumberIntegerYesUnique invoice number generated by us
kidStringNoUnique KID-number for those with an KID/OCR-agreement
customerURIYesThe related customer for this invoice
netAmountYesNet amount (in invoice currency)
vatAmountYesVat amount (in invoice currency)
grossAmountYesGross amount (= net+vat) (in invoice currency)
netInNokAmountYesNet amount
vatInNokAmountYesVat amount
grossInNokAmountYesGross amount (= net+vat)
invoiceTextStringNoComment/description printed above the invoice lines
yourReferenceStringNoYour reference
ourReferenceStringNoOur reference
addressAddressYesThe address printed on the invoice.
linesArray[InvoiceLine]No
currencyStringNoDefault currency is NOK
Link RelationReferences
saleThe sale object for this invoice

InvoiceLine

FieldTypeAlways presentDescription
netAmountYesNet amount (in invoice currency)
vatAmountYesVat amount (in invoice currency)
grossAmountYesGross amount (= net+vat) (in invoice currency)
netInNokAmountYesNet amount
vatInNokAmountYesVat amount
grossInNokAmountYesGross amount (= net+vat)
vatInPercentNumberYesVat in percent (i.e. 25)
unitPriceAmountYesPrice per unit (in invoice currency)
quantityNumberYesQuantity
productURLNoLink to product if product-line
incomeAccountAccountYesThe income account for accounting purposes (i.e. '3000')

The invoice will also include a link to the sale.

Credit Note

Fields

FieldTypeAlways presentDescription
creditNoteNumberIntegerYesUnique creditNote number generated by us
kidStringNoUnique KID-number for those with an KID/OCR-agreement
customerURIYesThe related customer for this credit note
netAmountYesNet amount (in creditNote currency)
vatAmountYesVat amount (in creditNote currency)
grossAmountYesGross amount (= net+vat) (in creditNote currency)
netInNokAmountYesNet amount
vatInNokAmountYesVat amount
grossInNokAmountYesGross amount (= net+vat)
creditNoteTextStringNoComment/description printed above the credit note lines
yourReferenceStringNoYour reference
ourReferenceStringNoOur reference
addressAddressYesThe address printed on the credit note.
linesArray[CreditNoteLine]No
currencyStringNoDefault currency is NOK
Link RelationReferences
invoiceThe original invoice for this credit note (if present)

CreditNoteLine

FieldTypeAlways presentDescription
netAmountYesNet amount (in credit note currency)
vatAmountYesVat amount (in credit note currency)
grossAmountYesGross amount (= net+vat) (in credit note currency)
netInNokAmountYesNet amount
vatInNokAmountYesVat amount
grossInNokAmountYesGross amount (= net+vat)
vatInPercentNumberYesVat in percent (i.e. 25)
unitPriceAmountYesPrice per unit (in credit note currency)
quantityNumberYesQuantity
productURLNoLink to product if product-line
incomeAccountAccountYesThe income account for accounting purposes (i.e. '3000')

Journal Entry

FieldTypeAlways presentDescription
dateDateyesThe date for ths journal entry.
descriptionStringyes
linesArray[JournalEntryLine]yesAt least one line should be present

JournalEntryLine

FieldTypeAlways presentDescription
amountAmountyesThe amount.
accountAccountyesThe account (i.e. '3000' or '1500:10001')
vatCodeStringnoVat code. Fiken uses standard SAF-T VAT-codes (See https://github.com/Skatteetaten/saf-t/tree/master/Standard%20Tax%20Codes)

Services

Search Service

The search service supports searching for resources inside a company. The basic operation is to POST a search object that will be processed accordingly. There are two kinds of searches; free-form searches and structured searches. Free-form is useful when the query is from a human and you want Fiken to take care of searching in as many places as possible. There are not many ways the question can be limited. The structured search is for searching specific fields for specific values and are useful for machines looking for specific data.

Examples

A search that queries for objects that matches the string 123. This will search in many types of resources and most of their fields.

POST /..

{
  "query": "123"
}

{
  "_embedded": {
    "https://fiken.no/api/v1/rel/contacts": [
      {
        ...
        "email": "foo123@gmail.com",
      }
    ],
    "https://fiken.no/api/v1/rel/sales": [
      {
        ...
        "date": "2016-05-24",
        "identifier": "123",
        ...
      }
    ]
  }
}

If you know what kind of resource you want, you can limit the search to a subset of the available collections:

POST /..

{
  "query": "123",
  "collections": [
    "https://...",
    "https://..."
  ]
}

{
  "_embedded": {
    "https://fiken.no/api/v1/rel/companies": [
      {
        ...
        "email": "foo123@gmail.com",
      }
    ]
  }
}

On the other hand it can be useful to be able to do more specific searches. If you know the collection that contain the resource you're after and the value of a field, specify that with a collection and the field:

POST /..

{
  "collection": "...",
  "query": "Foo Bar"
}

{
  "_embedded": {
    "https://fiken.no/api/v1/rel/contacts": [
      {
        ...
        "name": "Foo Bar",
      }
    ]
  }
}

For more advanced searches see the following section on technical details.

Technical Details

Collections

The search service introduces the term collections. A collection in this context means "all sales", "all contacts" for a specific company. To find the URL to a particular company's collection, start with the company's resource and use the rel to look up the URL from the _links object.

Free-form Searches

The free-form search is an unstructured query string in a similar style to what Google and other search services do.

To do a free-form search send a Json object with a query key. The search response object does not have any items on its own, but embeds other resources. The relations are the same as used elsewhere.

An example on how to search the entire company for data that matches the query 123. This query resulted in hits in two different resources, one contact and one sale. The relation will tell the client what kind of data that was returned.

Searchable Collections and Fields

These collections and fields are available for the search service:

Contact: supplier number, customer number, member number, name, and email.

Sale: sale number

Note that other collections and fields will be available later on which may change the results returned from a query.

Create General Journal Entry Service

Beta Notice: The General Journal Entry section of the API is currently in beta. While fully functional there might be small changes in the interfaces and functionality.

Create General Journal Entry Request

FieldTypeRequiredDescription
descriptionStringYes
journalEntriesArray of Create Journal EntryYesAt least one journal entry is required.

Create Journal Entry

FieldTypeRequiredDescription
descriptionStringYes
dateDateYes
linesArray of Create Journal Entry LineYesAt least one line is required.
Create Journal Entry Line
FieldTypeRequiredDescription
debitAmountYesThe net debit amount. Can be positive or negative, but not 0.
debitAccountAccountMaybeThe debit account code. Either debit account, credit account or both are required.
debitVatCodeStringNo
creditAccountAccountMaybeThe credit account code. Either debit account, credit account or both are required.
creditVatCodeStringNo
Link RelationReferences
attachmentsAttachments of this journal entry

Attachment

The content to post should be a form/multipart with the following parts:

JournalAttachment

FieldTypeRequiredDescription
filenameString (max 200)YesThe filename. Must end with either .png, .jpeg, .jpg, .gif or .pdf

Create Invoice Service

There is a separate service for creating invoices that takes its own special object. The URL can be found by following the from the create-invoice-service relation from a company.

When creating lines the following combination of fields are allowed:

CombinationProduct with unitPriceunitNetPricenetvatgross
Combination 1OptionalPresentPresentPresentPresent
Combination 2AbsentAbsentPresentPresentPresent
Combination 3PresentAbsentPresentPresentPresent
Combination 4PresentAbsentAbsentAbsentAbsent
Combination 5AbsentPresentAbsentAbsentAbsent

The vatType field is taken from either 1) the line or 2) the product. At least vatType or vatPercent has to be specified. If both are specified, Fiken will assert that the given vat type matches the given vat percent for the issue date.

The incomeAccount field is similar to vatType, it defaults to the product's income account. Either the line or the product needs to have an income account set.

If discountPercent is set, all amounts must be given before the discount is applied. Fiken will calculate the new totals.

Create Invoice Request

FieldTypeRequiredDescription
issueDateDateYes
dueDateDateYes
linesArray of Create Invoice PartyYesAt least one line is required.
ourReferenceStringNoA reference for the sender. Visible on the invoice.
yourReferenceStringNoA reference for the receiver. Visible on the invoice.
customerCreate Invoice CustomerYesThe customer (receiver) for this invoice.
bankAccountUrlURLYesThe bank account's number will be printed on the invoice.
currencyStringNoThe currency of this invoice, if different than NOK
invoiceTextStringNoComment/description printed above the invoice lines
cashBooleanNoTrue if this is a "Cash Invoice"/Receipt ("kontantfaktura")
paymentAccountAccountmaybeFor Cash Invoices only. For instance "1920:10001".

Create Invoice Line

FieldTypeRequiredDescription
netAmountAmountMaybe
vatAmountAmountMaybe
grossAmountAmountMaybe
vatTypeStringMaybeOne of: {"HIGH", "MEDIUM", "LOW", "EXEMPT", "EXEMPT_IMPORT_EXPORT", "EXEMPT_REVERSE", "OUTSIDE", "NONE"}. "HIGH" is the most common.
vatPercentNumberMaybe
unitNetAmountAmountMaybe
discountPercentNumberNoDefaults to 0.
quantityNumberNoDefaults to 1.
descriptionStringMaybe
commentStringNo
productUrlURLMaybeUsed to fill in missing fields.
incomeAccountAccountMaybe

If some fields are left blank and there is a product URL specified, the fields will be filled out with values from the product.

Create Invoice Customer

FieldTypeRequiredDescription
urlURLMaybeThe URL must reference a contact that is a customer (has a customer number)

Create Invoice Response

The server will response with a Invoice Resource

Document Sending Service

Beta Notice: The Invoice section of the API is currently in beta. While fully functional there might be small changes in the interfaces and functionality.

The document sending service supports sending invoices by email and EHF. The URL can be found by following the from the document-sending-service relation from a company.

The payload is different for each method used for sending the documents but shares two fields:

Method: auto lets Fiken select the best channel for sending the document. This currently means EHF if EHF is available, otherwise email will be used.

Payload fields when sending as auto:

FieldTypeRequiredDescription
resourceURLYesThe URL of the document to send.
methodStringYesHas to be auto.
recipientEmailEmail addressNo
recipientNameStringNo
organizationNumberStringNo

Payload fields when sending as email:

FieldTypeRequiredDescription
resourceURLYesThe URL of the document to send.
methodStringYesHas to be email.
recipientEmailEmail addressNoDefaults to the customers email if not provided.
recipientNameStringNoDefaults to the customers name if not provided.
emailSendOptionStringNodocument_link, attachment or auto. Defaults to auto.

Payload fields when sending as EHF:

FieldTypeRequiredDescription
resourceURLYesThe URL of the document to send.
methodStringYesHas to be ehf.
organizationNumberStringNoDefaults to the customers organization number if not provided.

Interaction Examples

These are detailed examples showing every request and response when performing a specific use case.