This version of the API will be shut down starting from December 31, 2022. We will no longer accept new users after this date. APIv2 is available at https://api.fiken.no/

Table of Contents

Introduction

This scenario shows how to take send an invoice through email and EHF.

It is assumed that there exists an invoice that the client want to send. For details on how to create the invoice see Create Invoice Scenario.

Find the company and its send invoice service

Start at the start endpoint and find the company whose invoice that should be sent.

Exchange #1

Request
GET https://fiken.no/api/v1
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://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
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-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/create-invoice-service": {
            "href": "https://.../url-10"
          },
          "https://fiken.no/api/v1/rel/create-general-journal-entry-service": {
            "href": "https://.../url-11"
          },
          "https://fiken.no/api/v1/rel/document-sending-service": {
            "href": "https://.../url-12"
          },
          "https://fiken.no/api/v1/rel/search": {
            "href": "https://.../url-13"
          }
        },
        "name": "Test1",
        "slug": "test1",
        "organizationNumber": "893186352"
      }
    ]
  }
}

In this response we find the link with the https://fiken.no/api/v1/rel/document-sending-service relation and that it resolves to https://.../url-13.

Now it is possible to send the invoice. This example assumes that the invoice is available at https://.../url-15.

Sending by auto

Exchange #3

Request
POST https://.../url-13
Accept: application/hal+json, application/vnd.error+json
Content-Type: application/hal+json

{
  "resource": "https://.../url-15",
  "method": "auto",
  "recipientEmail": "foo@example.org",
  "recipientName": "Foo Bar"
  "mobileNumber": "12345678"
}
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": {}
}

Sending by email

Exchange #4

Request
POST https://.../url-13
Accept: application/hal+json, application/vnd.error+json
Content-Type: application/hal+json

{
  "resource": "https://.../url-15",
  "method": "email",
  "recipientEmail": "foo@example.org",
  "recipientName": "Foo Bar"
}
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": {}
}

Sending by EHF

Exchange #5

Request
POST https://.../url-13
Accept: application/hal+json, application/vnd.error+json
Content-Type: application/hal+json

{
  "resource": "https://.../url-15",
  "method": "ehf",
  "organizationNumber": "913312465"
}
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": {}
}

Sending by SMS

Exchange #6

Request
POST https://.../url-13
Accept: application/hal+json, application/vnd.error+json
Content-Type: application/hal+json

{
  "resource": "https://.../url-15",
  "method": "sms",
  "mobileNumber": "90123456"
}
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": {}
}