Data structures

We have some basic types, and then we have our objects.

Table of Contents

Data Types

These are simple data-types that are used in several of our objects.

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:

Objects

Company

FieldTypeAlways presentDescription
nameStringYesThe company name
organizationNumberStringNo

Example

{
  "name": "Min første bedrift",
  "organizationNumber": "993275999",
  "_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.
totalPaidAmountyesRead only. Total amount paid in NOK.
totalPaidInCurrencyAmountnoRead only. Total amount paid in other currency
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.

Query parameters

The following query parameters can be applied to the resource to filter the results in the sales collection. The date and lastModified fields can use different variations of filtering, as explained in the generic filter section.

ParameterFieldFormatDescription
datedateyyyy-MM-ddDate-field, so searchable with parameter name permutations
lastModifiedlastModifiedyyyy-MM-ddDate-field, so searchable with parameter name permutations
paidpaidtrue/falseIf specified, only returns Sales with paid true or false

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
numberAccountThe accounting account number of this bank account, eg 1920:10001
bankAccountNumberStringThe number of the account (12345678903 for instance for norwegian banks

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.

Query parameters

The following query parameters can be applied to the resource to filter the results in the sales collection. The date and lastModified fields can use different variations of filtering, as explained in the generic filter section.

ParameterFieldFormatDescription
lastModifiedlastModifiedyyyy-MM-ddDate-field, so searchable with parameter name permutations

Examples

Creating a customer
POST
{
  "name": "Pianolærer Kamomilla",
  "email": "kamomilla@kardemommeby.com",
  "organizationIdentifier": "993275999",
  "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": "993275999",
        "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

Example

Posting a payment of 123,45.

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

Payments in foreign currencies

If you want to register payments in foreign currencies (on Sales that are in a foreign currency), you need to supply more information:

FieldTypeRequiredDescription
dateDateYesThe date when the payment was done
accountAccountYesThe accounting account that received the payment. For example "1920:10002".
amountAmountYesThe amount in NOK that actually appeared in your bank account.
currencyAmountAmountYesOnly required for payents in foreign currencies
currencyStringYesOne of the currencies Fiken supports, like USD, EUR etc
feeAmountNoIf your bank charged you anything, add it here

See create invoice in foreign currency for an example flow.

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.

Query parameters

The following query parameters can be applied to the resource to filter the results in the invoices collection.

ParameterFieldFormatDescription
datedateyyyy-MM-ddDate-field, so searchable with parameter name permutations
lastModifiedlastModifiedyyyy-MM-ddDate-field, so searchable with parameter name permutations

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
bankAccountNumberStringNoThe bank account number of the Invoice.
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
discountNumberNoDiscount percentage given when this invoice was created
productURLNoLink to product if product-line
descriptionStringNoDescription of the line
incomeAccountAccountYesThe income account for accounting purposes (i.e. '3000')

The invoice will also include a link to the sale.

Credit Note

You can currently only list and get information about credit notes, not create them, through the API.

Query parameters

The following query parameters can be applied to the resource to filter the results in the credit notes collection.

ParameterFieldFormatDescription
datedateyyyy-MM-dddate equal to parameter value
dateLedateyyyy-MM-dddate less than or equal to parameter value
dateLtdateyyyy-MM-dddate less than parameter value
dateGedateyyyy-MM-dddate greater than or equal to parameter value
dateGtdateyyyy-MM-dddate greater than parameter value

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
discountNumberNoDiscount percentage given when this invoice was created
productURLNoLink to product if product-line
descriptionStringNoDescription of the 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)