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
}