Table of Contents
Introduction
Creating a new invoice is a complex process as both depend on a lot of other resources and the resource itself is also quite big.
The first thing that has to be found is the company that issues the invoice. From this company you also have to find the correct bank account and customer.
Find company resource
In the start resource, find the link that has the https://fiken.no/api/v1/rel/companies relation and download the
resource. In the resource, find the issuing company. The organizationNumber or slug are useful for uniquely
identifying a company.
Exchange #1
Request
GET https://fiken.no/api/v1
Accept: application/hal+json, application/vnd.error+json
Response
200 OK
Content-Length: ...
Content-Type: application/hal+json;charset=utf-8
Date: ...
Expires: Thu, 01 Jan 1970 00:00:00 GMT
X-Request-ID: <random UUID>
{
"_links": {
"self": {
"href": "https://fiken.no/api/v1"
},
"https://fiken.no/api/v1/rel/companies": {
"href": "https://.../url-1"
}
}
}
Exchange #2
Request
GET https://.../url-1
Accept: application/hal+json, application/vnd.error+json
Response
200 OK
Content-Length: ...
Content-Type: application/hal+json;charset=utf-8
Date: ...
Expires: Thu, 01 Jan 1970 00:00:00 GMT
X-Request-ID: <random UUID>
{
"_links": {
"self": {
"href": "https://.../url-1"
}
},
"_embedded": {
"https://fiken.no/api/v1/rel/companies": [
{
"_links": {
"self": {
"href": "https://.../url-2"
},
"https://fiken.no/api/v1/rel/accounts": {
"href": "https://.../url-3{year}",
"templated": true
},
"https://fiken.no/api/v1/rel/bank-accounts": {
"href": "https://.../url-4"
},
"https://fiken.no/api/v1/rel/contacts": {
"href": "https://.../url-5"
},
"https://fiken.no/api/v1/rel/invoices": {
"href": "https://.../url-6"
},
"https://fiken.no/api/v1/rel/credit-notes": {
"href": "https://.../url-7"
},
"https://fiken.no/api/v1/rel/products": {
"href": "https://.../url-8"
},
"https://fiken.no/api/v1/rel/sales": {
"href": "https://.../url-9"
},
"https://fiken.no/api/v1/rel/purchases": {
"href": "https://.../url-10"
},
"https://fiken.no/api/v1/rel/create-invoice-service": {
"href": "https://.../url-11"
},
"https://fiken.no/api/v1/rel/create-general-journal-entry-service": {
"href": "https://.../url-12"
},
"https://fiken.no/api/v1/rel/document-sending-service": {
"href": "https://.../url-13"
},
"https://fiken.no/api/v1/rel/search": {
"href": "https://.../url-14"
},
"https://fiken.no/api/v1/rel/create-credit-note-service": {
"href": "https://.../url-15"
}
},
"name": "Test1",
"slug": "test1",
"organizationNumber": "893186352",
"hasApiAccess": true
}
]
}
}
In this example we are looking for the company with the organization number 123456789. By looking at the data in the
embedded https://fiken.no/api/v1/rel/companies array we find the company. The company's resource is
https://.../url-2.
Find Bank Account
The procedure here is similar to finding a company, but it since the bank account is owned by the company, you start with the company resource.
From the company resource that was just downloaded, you can find the link to a
https://fiken.no/api/v1/rel/bank-accounts and from that find the location to the bank account you need.
Exchange #3
Request
GET https://.../url-4
Accept: application/hal+json, application/vnd.error+json
Response
200 OK
Content-Length: ...
Content-Type: application/hal+json;charset=utf-8
Date: ...
Expires: Thu, 01 Jan 1970 00:00:00 GMT
X-Request-ID: <random UUID>
{
"_links": {
"self": {
"href": "https://.../url-4"
}
},
"_embedded": {
"https://fiken.no/api/v1/rel/bank-accounts": [
{
"_links": {
"self": {
"href": "https://.../url-16"
}
},
"name": "Min bankkonto",
"number": "1920:10001",
"bankAccountNumber": "12345678970"
}
]
}
}
Exchange #4
Request
GET https://.../url-8
Accept: application/hal+json, application/vnd.error+json
Response
200 OK
Content-Length: ...
Content-Type: application/hal+json;charset=utf-8
Date: ...
Expires: Thu, 01 Jan 1970 00:00:00 GMT
X-Request-ID: <random UUID>
{
"_links": {
"self": {
"href": "https://.../url-8"
}
},
"_embedded": {
"https://fiken.no/api/v1/rel/products": [
{
"_links": {
"self": {
"href": "https://.../url-17"
}
},
"name": "Testprodukt #1",
"unitPrice": 1337,
"incomeAccount": "3030",
"vatType": "MEDIUM",
"active": true,
"stock": 0.3000000000,
"productNumber": "1"
},
{
"_links": {
"self": {
"href": "https://.../url-18"
}
},
"name": "Testprodukt #2",
"unitPrice": 2674,
"incomeAccount": "3000",
"vatType": "HIGH",
"active": true,
"stock": -9.4000000000,
"productNumber": "2"
},
{
"_links": {
"self": {
"href": "https://.../url-19"
}
},
"name": "Testprodukt #3",
"unitPrice": 4011,
"incomeAccount": "3030",
"vatType": "MEDIUM",
"active": true,
"stock": -16.1000000000,
"productNumber": "3"
},
{
"_links": {
"self": {
"href": "https://.../url-20"
}
},
"name": "Testprodukt #4",
"unitPrice": 5348,
"incomeAccount": "3000",
"vatType": "HIGH",
"active": true,
"stock": -12.8000000000,
"productNumber": "4"
},
{
"_links": {
"self": {
"href": "https://.../url-21"
}
},
"name": "Testprodukt #5",
"incomeAccount": "3030",
"vatType": "MEDIUM",
"active": true,
"stock": 5.5000000000,
"productNumber": "5"
},
{
"_links": {
"self": {
"href": "https://.../url-22"
}
},
"name": "Testprodukt #6",
"unitPrice": 8022,
"incomeAccount": "3000",
"vatType": "HIGH",
"active": true,
"stock": -36.2000000000,
"productNumber": "6"
},
{
"_links": {
"self": {
"href": "https://.../url-23"
}
},
"name": "Testprodukt #7",
"unitPrice": 9359,
"incomeAccount": "3030",
"vatType": "MEDIUM",
"active": true,
"stock": 8.1000000000,
"productNumber": "7"
},
{
"_links": {
"self": {
"href": "https://.../url-24"
}
},
"name": "Testprodukt #8",
"unitPrice": 10696,
"incomeAccount": "3000",
"vatType": "HIGH",
"active": true,
"stock": 9.4000000000,
"productNumber": "8"
},
{
"_links": {
"self": {
"href": "https://.../url-25"
}
},
"name": "Testprodukt #9",
"unitPrice": 12033,
"incomeAccount": "3030",
"vatType": "MEDIUM",
"active": true,
"stock": -40.3000000000,
"productNumber": "9"
}
]
}
}
Find Customer
The procedure here is similar to finding the bank account, follow the https://fiken.no/api/v1/rel/contacts relation to
download all contacts and find the location of the contact you are after.
Exchange #5
Request
GET https://.../url-5
Accept: application/hal+json, application/vnd.error+json
Response
200 OK
Content-Length: ...
Content-Type: application/hal+json;charset=utf-8
Date: ...
Expires: Thu, 01 Jan 1970 00:00:00 GMT
X-Request-ID: <random UUID>
{
"_links": {
"self": {
"href": "https://.../url-5"
}
},
"_embedded": {
"https://fiken.no/api/v1/rel/contacts": [
{
"_links": {
"self": {
"href": "https://.../url-26"
}
},
"name": "Walmart",
"email": "foo@example.org",
"address": {
"address1": "Lang lang gate 117258",
"postalPlace": "Sandvika",
"postalCode": "5854",
"country": "Norge"
},
"supplierNumber": 20001
},
{
"_links": {
"self": {
"href": "https://.../url-27"
}
},
"name": "ExxonMobil",
"email": "foo@example.org",
"address": {
"address1": "Lang lang gate 504381",
"postalPlace": "Sandvika",
"postalCode": "4034",
"country": "Norge"
},
"customerNumber": 10001
},
{
"_links": {
"self": {
"href": "https://.../url-28"
}
},
"name": "Royal Dutch Shell",
"email": "foo@example.org",
"address": {
"address1": "Lang lang gate 67159",
"postalPlace": "Sandvika",
"postalCode": "6584",
"country": "Norge"
},
"customerNumber": 10002
},
{
"_links": {
"self": {
"href": "https://.../url-29"
}
},
"name": "BP",
"email": "foo@example.org",
"address": {
"address1": "Lang lang gate 655647",
"postalPlace": "Sandvika",
"postalCode": "5926",
"country": "Norge"
},
"supplierNumber": 20002
},
{
"_links": {
"self": {
"href": "https://.../url-30"
}
},
"name": "Sinopec",
"email": "foo@example.org",
"organizationIdentifier": "983431224",
"address": {
"address1": "Lang lang gate 443473",
"postalPlace": "Sandvika",
"postalCode": "2875",
"country": "Norge"
},
"supplierNumber": 20003
},
{
"_links": {
"self": {
"href": "https://.../url-31"
}
},
"name": "State Grid Corporation of China",
"email": "foo@example.org",
"address": {
"address1": "Lang lang gate 641700",
"postalPlace": "Sandvika",
"postalCode": "6689",
"country": "Norge"
},
"customerNumber": 10003,
"supplierNumber": 20004
},
{
"_links": {
"self": {
"href": "https://.../url-32"
}
},
"name": "Toyota Motors",
"email": "foo@example.org",
"organizationIdentifier": "890475638",
"address": {
"address1": "Lang lang gate 794672",
"postalPlace": "Sandvika",
"postalCode": "5832",
"country": "Norge"
},
"customerNumber": 10004,
"supplierNumber": 20005
},
{
"_links": {
"self": {
"href": "https://.../url-33"
}
},
"name": "PetroChina",
"email": "foo@example.org",
"organizationIdentifier": "922294443",
"address": {
"address1": "Lang lang gate 795342",
"postalPlace": "Sandvika",
"postalCode": "9435",
"country": "Norge"
},
"supplierNumber": 20006
},
{
"_links": {
"self": {
"href": "https://.../url-34"
}
},
"name": "Total S.A.",
"email": "foo@example.org",
"address": {
"address1": "Lang lang gate 120749",
"postalPlace": "Sandvika",
"postalCode": "2784",
"country": "Norge"
},
"customerNumber": 10005,
"supplierNumber": 20007
},
{
"_links": {
"self": {
"href": "https://.../url-35"
}
},
"name": "Japan Post Holdings",
"email": "foo@example.org",
"organizationIdentifier": "913895545",
"address": {
"address1": "Lang lang gate 769742",
"postalPlace": "Sandvika",
"postalCode": "9014",
"country": "Norge"
},
"customerNumber": 10006,
"supplierNumber": 20008
},
{
"_links": {
"self": {
"href": "https://.../url-36"
}
},
"name": "Chevron",
"email": "foo@example.org",
"organizationIdentifier": "914653137",
"address": {
"address1": "Lang lang gate 1656",
"postalPlace": "Sandvika",
"postalCode": "4992",
"country": "Norge"
},
"customerNumber": 10007,
"supplierNumber": 20009
},
{
"_links": {
"self": {
"href": "https://.../url-37"
}
},
"name": "ConocoPhillips",
"email": "foo@example.org",
"organizationIdentifier": "968170855",
"address": {
"address1": "Lang lang gate 115465",
"postalPlace": "Sandvika",
"postalCode": "3984",
"country": "Norge"
},
"supplierNumber": 20010
},
{
"_links": {
"self": {
"href": "https://.../url-38"
}
},
"name": "Vitol",
"email": "foo@example.org",
"address": {
"address1": "Lang lang gate 474512",
"postalPlace": "Sandvika",
"postalCode": "8242",
"country": "Norge"
},
"customerNumber": 10008,
"supplierNumber": 20011
},
{
"_links": {
"self": {
"href": "https://.../url-39"
}
},
"name": "Saudi Aramco",
"email": "foo@example.org",
"address": {
"address1": "Lang lang gate 607884",
"postalPlace": "Sandvika",
"postalCode": "4881",
"country": "Norge"
},
"customerNumber": 10009,
"supplierNumber": 20012
},
{
"_links": {
"self": {
"href": "https://.../url-40"
}
},
"name": "Volkswagen Group",
"email": "foo@example.org",
"address": {
"address1": "Lang lang gate 473828",
"postalPlace": "Sandvika",
"postalCode": "1697",
"country": "Norge"
},
"customerNumber": 10010,
"supplierNumber": 20013
},
{
"_links": {
"self": {
"href": "https://.../url-41"
}
},
"name": "Fannie Mae",
"email": "foo@example.org",
"organizationIdentifier": "888969976",
"address": {
"address1": "Lang lang gate 450793",
"postalPlace": "Sandvika",
"postalCode": "4352",
"country": "Norge"
},
"customerNumber": 10011,
"supplierNumber": 20014
},
{
"_links": {
"self": {
"href": "https://.../url-42"
}
},
"name": "General Electric",
"email": "foo@example.org",
"address": {
"address1": "Lang lang gate 583818",
"postalPlace": "Sandvika",
"postalCode": "4360",
"country": "Norge"
},
"supplierNumber": 20015
},
{
"_links": {
"self": {
"href": "https://.../url-43"
}
},
"name": "Glencore",
"email": "foo@example.org",
"address": {
"address1": "Lang lang gate 341180",
"postalPlace": "Sandvika",
"postalCode": "735",
"country": "Norge"
},
"customerNumber": 10012
},
{
"_links": {
"self": {
"href": "https://.../url-44"
}
},
"name": "Allianz",
"email": "foo@example.org",
"organizationIdentifier": "895459322",
"address": {
"address1": "Lang lang gate 268151",
"postalPlace": "Sandvika",
"postalCode": "2555",
"country": "Norge"
},
"customerNumber": 10013,
"supplierNumber": 20016
},
{
"_links": {
"self": {
"href": "https://.../url-45"
}
},
"name": "ING Group",
"email": "foo@example.org",
"organizationIdentifier": "892118171",
"address": {
"address1": "Lang lang gate 661808",
"postalPlace": "Sandvika",
"postalCode": "5225",
"country": "Norge"
},
"supplierNumber": 20017
},
{
"_links": {
"self": {
"href": "https://.../url-46"
}
},
"name": "Berkshire Hathaway",
"email": "foo@example.org",
"organizationIdentifier": "949060206",
"address": {
"address1": "Lang lang gate 336270",
"postalPlace": "Sandvika",
"postalCode": "8578",
"country": "Norge"
},
"supplierNumber": 20018
},
{
"_links": {
"self": {
"href": "https://.../url-47"
}
},
"name": "Samsung Electronics",
"email": "foo@example.org",
"organizationIdentifier": "905170839",
"address": {
"address1": "Lang lang gate 498480",
"postalPlace": "Sandvika",
"postalCode": "2561",
"country": "Norge"
},
"customerNumber": 10014
},
{
"_links": {
"self": {
"href": "https://.../url-48"
}
},
"name": "General Motors",
"email": "foo@example.org",
"organizationIdentifier": "986846675",
"address": {
"address1": "Lang lang gate 511545",
"postalPlace": "Sandvika",
"postalCode": "4793",
"country": "Norge"
},
"customerNumber": 10015
},
{
"_links": {
"self": {
"href": "https://.../url-49"
}
},
"name": "Eni",
"email": "foo@example.org",
"address": {
"address1": "Lang lang gate 269514",
"postalPlace": "Sandvika",
"postalCode": "2935",
"country": "Norge"
},
"supplierNumber": 20019
},
{
"_links": {
"self": {
"href": "https://.../url-50"
}
},
"name": "Daimler AG",
"email": "foo@example.org",
"address": {
"address1": "Lang lang gate 366626",
"postalPlace": "Sandvika",
"postalCode": "7965",
"country": "Norge"
},
"customerNumber": 10016
},
{
"_links": {
"self": {
"href": "https://.../url-51"
}
},
"name": "Ford Motor Foretak",
"email": "foo@example.org",
"address": {
"address1": "Lang lang gate 421501",
"postalPlace": "Sandvika",
"postalCode": "1974",
"country": "Norge"
},
"customerNumber": 10017,
"supplierNumber": 20020
},
{
"_links": {
"self": {
"href": "https://.../url-52"
}
},
"name": "Hewlett-Packard",
"email": "foo@example.org",
"address": {
"address1": "Lang lang gate 940312",
"postalPlace": "Sandvika",
"postalCode": "1123",
"country": "Norge"
},
"customerNumber": 10018,
"supplierNumber": 20021
},
{
"_links": {
"self": {
"href": "https://.../url-53"
}
},
"name": "Nippon Telegraph and Telephone",
"email": "foo@example.org",
"address": {
"address1": "Lang lang gate 100921",
"postalPlace": "Sandvika",
"postalCode": "1617",
"country": "Norge"
},
"supplierNumber": 20022
},
{
"_links": {
"self": {
"href": "https://.../url-54"
}
},
"name": "AT&T",
"email": "foo@example.org",
"organizationIdentifier": "947617118",
"address": {
"address1": "Lang lang gate 732019",
"postalPlace": "Sandvika",
"postalCode": "4405",
"country": "Norge"
},
"customerNumber": 10019
},
{
"_links": {
"self": {
"href": "https://.../url-55"
}
},
"name": "E.ON",
"email": "foo@example.org",
"address": {
"address1": "Lang lang gate 352084",
"postalPlace": "Sandvika",
"postalCode": "8303",
"country": "Norge"
},
"supplierNumber": 20023
},
{
"_links": {
"self": {
"href": "https://.../url-56"
}
},
"name": "Carrefour",
"email": "foo@example.org",
"organizationIdentifier": "922228150",
"address": {
"address1": "Lang lang gate 861428",
"postalPlace": "Sandvika",
"postalCode": "2036",
"country": "Norge"
},
"customerNumber": 10020,
"supplierNumber": 20024
},
{
"_links": {
"self": {
"href": "https://.../url-57"
}
},
"name": "AXA",
"email": "foo@example.org",
"address": {
"address1": "Lang lang gate 955336",
"postalPlace": "Sandvika",
"postalCode": "3519",
"country": "Norge"
},
"supplierNumber": 20025
},
{
"_links": {
"self": {
"href": "https://.../url-58"
}
},
"name": "Assicurazioni Generali",
"email": "foo@example.org",
"organizationIdentifier": "962521058",
"address": {
"address1": "Lang lang gate 451425",
"postalPlace": "Sandvika",
"postalCode": "2365",
"country": "Norge"
},
"customerNumber": 10021,
"supplierNumber": 20026
},
{
"_links": {
"self": {
"href": "https://.../url-59"
}
},
"name": "Petrobras",
"email": "foo@example.org",
"address": {
"address1": "Lang lang gate 929919",
"postalPlace": "Sandvika",
"postalCode": "3414",
"country": "Norge"
},
"customerNumber": 10022,
"supplierNumber": 20027
},
{
"_links": {
"self": {
"href": "https://.../url-60"
}
},
"name": "Cargill",
"email": "foo@example.org",
"organizationIdentifier": "997772089",
"address": {
"address1": "Lang lang gate 421086",
"postalPlace": "Sandvika",
"postalCode": "5018",
"country": "Norge"
},
"customerNumber": 10023,
"supplierNumber": 20028
},
{
"_links": {
"self": {
"href": "https://.../url-61"
}
},
"name": "JX Holdings",
"email": "foo@example.org",
"organizationIdentifier": "935520348",
"address": {
"address1": "Lang lang gate 959317",
"postalPlace": "Sandvika",
"postalCode": "1008",
"country": "Norge"
},
"supplierNumber": 20029
},
{
"_links": {
"self": {
"href": "https://.../url-62"
}
},
"name": "Blåbærsyltetøyfabrikken AS",
"email": "foo@example.org",
"address": {
"address1": "Lang lang gate 925200",
"postalPlace": "Sandvika",
"postalCode": "4787",
"country": "Norge"
},
"customerNumber": 10024,
"supplierNumber": 20030
},
{
"_links": {
"self": {
"href": "https://.../url-63"
}
},
"name": "Hitachi, Ltd.",
"email": "foo@example.org",
"address": {
"address1": "Lang lang gate 983062",
"postalPlace": "Sandvika",
"postalCode": "245",
"country": "Norge"
},
"customerNumber": 10025,
"supplierNumber": 20031
},
{
"_links": {
"self": {
"href": "https://.../url-64"
}
},
"name": "McKesson Corporation",
"email": "foo@example.org",
"address": {
"address1": "Lang lang gate 205728",
"postalPlace": "Sandvika",
"postalCode": "944",
"country": "Norge"
},
"supplierNumber": 20032
},
{
"_links": {
"self": {
"href": "https://.../url-65"
}
},
"name": "Gazprom",
"email": "foo@example.org",
"organizationIdentifier": "927633718",
"address": {
"address1": "Lang lang gate 268308",
"postalPlace": "Sandvika",
"postalCode": "5544",
"country": "Norge"
},
"customerNumber": 10026
}
]
}
}
Exchange #6
Request
POST https://.../url-5
Accept: application/hal+json, application/vnd.error+json
Content-Type: application/hal+json
{
"name": "Fakturakunde AS",
"organizationIdentifier": "1234565",
"customer": true
}
Response
201 Created
Content-Length: ...
Date: ...
Expires: Thu, 01 Jan 1970 00:00:00 GMT
Location: https://.../url-66
X-Request-ID: <random UUID>
Exchange #7
Request
GET https://.../url-66
Accept: application/hal+json, application/vnd.error+json
Response
200 OK
Content-Length: ...
Content-Type: application/hal+json;charset=utf-8
Date: ...
Expires: Thu, 01 Jan 1970 00:00:00 GMT
X-Request-ID: <random UUID>
{
"_links": {
"self": {
"href": "https://.../url-66"
}
},
"name": "Fakturakunde AS",
"organizationIdentifier": "1234565",
"address": {
"country": "Norge"
},
"customerNumber": 10027
}
Create the invoice
Now that all the base data has been found the invoice can be created. To create the invoice you have to do send POST
request to the location found by following the https://fiken.no/api/v1/rel/create-invoice-service relation from the
company resource.
Please see the reference documentation for the details on all the fields in the request.
Exchange #8
Request
POST https://.../url-11
Accept: application/hal+json, application/vnd.error+json
Content-Type: application/hal+json
{
"issueDate": "2015-01-02",
"dueDate": "2015-01-16",
"uuid": "....",
"invoiceText": "woot",
"bankAccountUrl": "https://.../url-16",
"ourReference": "external-system-identifier",
"yourReference": "Deres ref",
"customer": {
"url": "https://.../url-66"
},
"lines": [
{
"unitNetAmount": 200,
"netAmount": 200,
"vatAmount": 50,
"discountPercent": 10,
"vatType": "HIGH",
"grossAmount": 250,
"description": "Description",
"productUrl": "https://.../url-17"
}
]
}
Response
201 Created
Content-Length: ...
Date: ...
Expires: Thu, 01 Jan 1970 00:00:00 GMT
Location: https://.../url-67
X-Request-ID: <random UUID>
Now Fiken has created the invoice. The Location header will point to the invoice resource. By downloading the invoice
from https://.../url-67 you will get the extra fields that Fiken generated.
This URL is the unique identifier of the created invoice. You can store this in your database for later reference.
The Generated Invoice Resource
Exchange #9
Request
GET https://.../url-67
Response
200 OK
Content-Length: ...
Content-Type: application/hal+json;charset=utf-8
Date: ...
Expires: Thu, 01 Jan 1970 00:00:00 GMT
X-Request-ID: <random UUID>
{
"_links": {
"self": {
"href": "https://.../url-67"
},
"alternate": {
"href": "https://.../url-68",
"type": "text/html"
}
},
"invoiceNumber": 11,
"issueDate": "2015-01-02",
"dueDate": "2015-01-16",
"netInNok": 180,
"vatInNok": 45,
"grossInNok": 225,
"net": 180,
"vat": 45,
"gross": 225,
"cash": false,
"invoiceText": "woot",
"yourReference": "Deres ref",
"ourReference": "external-system-identifier",
"address": {
"country": "Norge"
},
"lines": [
{
"netInNok": 180,
"vatInNok": 45,
"grossInNok": 225,
"net": 180,
"vat": 45,
"gross": 225,
"vatInPercent": 25,
"unitPrice": 200,
"quantity": 1.0000000000,
"description": "Description",
"discount": "10",
"product": "https://.../url-17",
"incomeAccount": "3030"
}
],
"sale": "https://.../url-69",
"customer": "https://.../url-66",
"bankAccountNumber": "12345678970"
}
For example, the generated invoice number was: 11.