Table of Contents
Introduction
We can also create invoices in foreign currencies. This shows an example of how that can be done. We need to perform a lot of the same setup as for creating invoices in NOK, so we will skip some of that here in this example.
We have now found the company, resolved a bankaccount, a product and a customer. We will now create an invoice using EUR as the currency. When we do that, all amounts are in EUR Cents, which is similar to how we treat amounts elsewhere in the API.
Exchange #1
Request
POST https://.../url-1
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-2",
"ourReference": "external-system-identifier",
"yourReference": "Deres ref",
"currency": "EUR",
"customer": {
"url": "https://.../url-3"
},
"lines": [
{
"unitNetAmount": 200,
"netAmount": 200,
"vatAmount": 50,
"discountPercent": 10,
"vatType": "HIGH",
"grossAmount": 250,
"description": "Description",
"productUrl": "https://.../url-4"
}
]
}
Response
201 Created
Cache-Control: no-cache, no-store, max-age=0, must-revalidate
Content-Length: ...
Date: ...
Expires: Thu, 01 Jan 1970 00:00:00 GMT
Location: https://.../url-5
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-5
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 #2
Request
GET https://.../url-5
Response
200 OK
Cache-Control: no-cache, no-store, max-age=0, must-revalidate
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"
},
"alternate": {
"href": "https://.../url-6",
"type": "text/html"
}
},
"invoiceNumber": 45,
"issueDate": "2015-01-02",
"dueDate": "2015-01-16",
"netInNok": 1627,
"vatInNok": 407,
"grossInNok": 2034,
"net": 180,
"vat": 45,
"gross": 225,
"cash": false,
"invoiceText": "woot",
"yourReference": "Deres ref",
"ourReference": "external-system-identifier",
"address": {
"country": "Norge"
},
"lines": [
{
"netInNok": 1627,
"vatInNok": 407,
"grossInNok": 2034,
"net": 180,
"vat": 45,
"gross": 225,
"vatInPercent": 25,
"unitPrice": 200,
"quantity": 1.0000000000,
"incomeAccount": "3000"
}
],
"sale": "https://.../url-7",
"customer": "https://.../url-3",
"currency": "EUR",
"bankAccountNumber": "12345678970"
}
For example, the generated invoice number was: 45
.
Adding payments
We can also register payments in foreign currencies, but to do that we need to provide a lot of the data via the API
call. You need to include the amount in NOK (the actual amount that appeared in your bank account), as well as the
amount in the foreign currency (EUR in this example), what currency was used for the transfer. You can also optionally
specify a fee
that your bank has charged you, but you should then later attach documentation on the fee cost to the
Sale.
To add payments, we need to look up the Sale of the invoice, since that is what we register payments on, and thus the
link to our payments
resource is available on the Sale
resource.
Exchange #3
Request
GET https://.../url-7
Accept: application/hal+json, application/vnd.error+json
Response
200 OK
Cache-Control: no-cache, no-store, max-age=0, must-revalidate
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-7"
},
"https://fiken.no/api/v1/rel/payments": {
"href": "https://.../url-8"
},
"https://fiken.no/api/v1/rel/attachments": {
"href": "https://.../url-9"
},
"alternate": {
"href": "https://.../url-6",
"type": "text/html"
}
},
"date": "2015-01-02",
"kind": "INVOICE",
"identifier": "45",
"paid": false,
"lines": [
{
"description": "Description",
"netPrice": 1627,
"vat": 407,
"account": "3000",
"vatType": "HIGH",
"netPriceInCurrency": 180,
"vatInCurrency": 45
}
],
"customer": "https://.../url-3",
"currency": "EUR"
}
In this case, the url for our payments on this sale is
https://.../url-8
Exchange #4
Request
POST https://.../url-8
Accept: application/hal+json, application/vnd.error+json
Content-Type: application/hal+json
{
"currency": "EUR",
"account": "1920:10001",
"amount": 1440,
"currencyAmount": 180,
"date": "2015-01-23"
}
Response
201 Created
Cache-Control: no-cache, no-store, max-age=0, must-revalidate
Content-Length: ...
Date: ...
Expires: Thu, 01 Jan 1970 00:00:00 GMT
Location: https://.../url-10
X-Request-ID: <random UUID>
And in the same way as we got a location for the invoice, which lead us to the Sale, we also get a Location
header for
the payment as well, but it won't return anything new compared to what we sent in.
Exchange #5
Request
GET https://.../url-10
Accept: application/hal+json, application/vnd.error+json
Response
200 OK
Cache-Control: no-cache, no-store, max-age=0, must-revalidate
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-10"
}
},
"amount": 1440,
"account": "1920:10001",
"currency": "EUR",
"currencyAmount": 180
}