3. Endpoints (Production)

Hypermedia

We use Hypermedia to expose application state. All REST resources and collections will have a link-collection. Each link contains a the following attributes:

rel	The rel-attribute identifies the relation with a constant name which we garantie will not change. You can code and bind your application to this name.
href	The href-attribute holds an absolute URL to the resource. Any filtering and/or pagination is already applied to the URL
method	[OPTIONAL] Defines the HTTP verb associated to the URL. If this attribute is not available it is implicitly GET.
template	[OPTIONAL] If the method-attribute is a POST, the URL will have a template-attribute holding a URL to the acceptable request-body JSON template.

Base url

The base (prefix) url for the API is: https://dataloen-api.bluegarden.dk/api

Salary (Root endpoint)

GET /input/salary
Description: When you call the root endpoint you will receive a list of available resources.
Request headers

Key Value Description

Authorization Bearer accessToken

Content-Type application/json

Response body 200

{
    "employerId": "[employer from accessToken]",
    "name": "[employer name]",
    "_links": [
        {
            "rel": "self",
            "href": "https://dataloen-api.bluegarden.dk/api/input/salary/[employerId]"
        },
        {
            "rel": "employees",
            "href": "https://dataloen-api.bluegarden.dk/api/input/salary/[employerId]/employees"
        },
        {
            "rel": "payTypes",
            "href": "https://dataloen-api.bluegarden.dk/api/input/salary/[employerId]/paytypes"
        },
        {
            "rel": "forms",
            "href": "https://dataloen-api.bluegarden.dk/api/input/salary/[employerId]/forms?from=2016-12-07&to=2016-12-07"
        },
        {
            "rel": "commit",
            "href": "https://dataloen-api.bluegarden.dk/api/input/salary/[employerId]/forms/commit",
            "method": "POST",
            "template": "https://dataloen-api.bluegarden.dk/api/templates/commitsalaryforms"
        }
    ]
}

Employees

Employee properties are described in the table below.

employeeId	A unique key for employees. Since DataLøn does not have unique keys for employees across salary periods, we have made this composite key, containing the employerId, salary period code, employee number and the date on which the employee was created.
employeeNumber	The number associated with an employee in DataLøn. This is NOT a unique identifier.
salaryPeriodGroup	The salary period group of the employee. The salaryPeriodGroup should be used when matching which customizedPayTypeTexts should be displayed for the employee. The possible values are '2425', '3435' and '4151': '2425' means that the employee is biweekly paid on even numbered weeks. '3435' means that the employee is biweekly paid on odd numbered weeks. '4151' means that the employee is monthly paid.
salaryPeriodCode	The salary period code of the employee. The options are '24', '25', '34', '35', '41' and '51'.
name	The name of the employee.
isTerminated	Tells if the employee has been terminated.
dateOfTermination	The end date for the employment of the employee. Is 'null' if the employee is not being terminated.
pinnedPayTypes	A list of pinned pay types for the employee (DK: faste løndele).
payTypeCode (property of a pinnedPayType)	A 4-character code matching a payType
defaultText (property of a pinnedPayType)	The default textual name of the paytype.
defaultValue (property of a pinnedPayType)	The default value of the pinned pay type.

GET /input/salary/[employerId]/employees
Description: Returns all employees available for salary processing
Request headers

Key Value Description

Authorization Bearer accessToken

Content-Type application/json

Response body 200

{  
   "collection":[  
      {  
         "employeeId":"36410-1017E2372",
         "employeeNumber":"0043",
         "salaryPeriodGroup":"2425",
         "salaryPeriodCode":"24",
         "name":"Test Employee 1",
         "isTerminated":false,
         "dateOfTermination":null,
         "pinnedPayTypes":[  
            {  
               "payTypeCode":"0001",
               "defaultText":"Arbejdstimer",
               "defaultValue":"16033"
            },
            {  
               "payTypeCode":"0012",
               "defaultText":"Normaltimer 1",
               "defaultValue":"16033"
            },
            {  
               "payTypeCode":"0013",
               "defaultText":"Normaltimer 1 x sats",
               "defaultValue":"15000"
            }
         ]
      },
      {  
         "employeeId":"36410-1312D2B72",
         "employeeNumber":"0051",
         "salaryPeriodGroup":"2425",
         "salaryPeriodCode":"25",
         "name":"Test Employe2 2",
         "pinnedPayTypes":[  

         ]
      }
   ],
   "_links":[  
      {  
         "rel":"self",
         "href":"http://dataloen-api/api/input/salary/[employerId]/employees"
      }
   ]
}

Note: Please notice that the API uses employeeId as a unique key for employees. Since DataLøn does not have unique keys for employees across salary periods, we have made this composite key, containing the employerId, salary period code, employee number and the date on which the employee was created. The salaryPeriodGroup should be used when matching which customizedPayTypeTexts should be displayed for the employee.

PayTypes

Paytype properties are described in the table below.

payTypeCode	A 4-character code matching a paytype.
defaultPayTypeText	The default textual name of the paytype.
customizedPayTypeTexts	A list of all customized text descriptions for the paytype, each of which are linked to a certain salary period group.

GET /input/salary/[employerId]/paytypes
Description:
Request headers

Key Value Description

Authorization Bearer accessToken

Content-Type application/json

Response body 200

{
    "collection": [
        {
            "payTypeCode": "0001",
            "defaultPayTypeText": "Arbejdstimer",
            "customizedPayTypeTexts": [
                {
                    "salaryPeriodGroup": "4151",
                    "customPayTypeText": "Arb. timer 41-1"
                },
                {
                    "salaryPeriodGroup": "2425",
                    "customPayTypeText": "Arb. timer 24-1"
                }
            ]
        },
        {
            "payTypeCode": "0002",
            "defaultPayTypeText": "Ferieberettiget løn",
            "customizedPayTypeTexts": []
        },
        {
            "payTypeCode": "0003",
            "defaultPayTypeText": "Ferieberettiget tillæg",
            "customizedPayTypeTexts": []
        },
        {
            "payTypeCode": "0012",
            "defaultPayTypeText": "Normaltimer 1",
            "customizedPayTypeTexts": []
        },
        {
            "payTypeCode": "0013",
            "defaultPayTypeText": "Normaltimer 1 x sats",
            "customizedPayTypeTexts": []
        },
    ],
    "_links": [
        {
            "rel": "self",
            "href": "https://dataloen-api.bluegarden.dk/api/input/salary/[employerId]/paytypes"
        }
    ]
}

Forms

The salary form and salary form entries are described in the tables below.

Salary Form

formId	A GUID generated by the API when the form is created.
date	Date of the form which is used when importing entries in DataLøn. The date is required and must be in the format yyyy-MM-dd, otherwise an errorCode `001` is returned.
state	The state of form, which is either 'committed' or 'archived'. Forms are initially in the 'committed' state. When the state is changed to 'archived', the form can no longer be imported into DataLøn, and is effectively soft deleted.
reference	This field can be used by you as a placeholder for your internal reference. The reference-value must not exceed 50 characters, otherwise an errorCode `002` is returned.
entries	A collection of associated salary form entries.
_links	This field is generated by the API, and contains the hypermedia link needed to change the state of the form, either from committed to archived or from archived to committed. Only the relevant link will be provided, based on the current state of the form.

Salary Form Entry

entryId	A GUID generated by the API when the entry is created.
employeeId	A unique ID for the employee. The ID is a composite key consiting of employerId, salary period code, employee number and the date on which the employee was created in DataLøn. The employeeId is required and must not exceed 150 characters, otherwise an errorCode `006` is returned. If the employeeId does not match an existing employee, an errorCode `007` is returned.
payTypeCode	A 4-digit code matching a payType. The payTypeCode must match a valid payType, otherwise an errorCode `008` is returned. The field is required, otherwise an errorCode `005` is returned.
value	Is used to store the value of paytypes. It can hold an integer value between [-99999999;99999999]. If the value is outside this interval, an errorCode 003 is returned. If it is a monetary value, it must be applied in 1/100th - so 100,25 DKK is applied as 10025. If the value is time, then 4:30 (4 hours 30 minutes) should be applied as 450.
comment	The comment will be visible when importing the form to a salary in DataLøn. The field is not required but must not exceed 150 characters, otherwise an errorCode `004` is returned.

GET /input/salary/[employerId]/forms?from=2016-11-07&to=2016-12-07
Description: Get salary forms dated in a defined interval. Please note that the to and from dates in the query string must be set
Request headers

Key Value Description

Authorization Bearer accessToken

Content-Type application/json

Response body 200

{  
   "page":1,
   "pageSize":20,
   "availablePages":2,
   "totalCount":23,
   "collection":[  
      {  
         "formId":"05836b1d-1904-4ef6-bec8-28232e345ab7",
         "date":"2016-11-29T00:00:00+01:00",
         "state":"committed",
         "reference":"Test reference",
         "entries":[  
            {  
               "entryId":"f6e05636-2ffa-4132-8218-91ad69fcdc98",
               "employeeId":"3641A-4C718577D",
               "payTypeCode":"001F",
               "value":"770",
               "comment":"Test comment"
            },
            {  
               "entryId":"9cccc557-7c1b-446c-b1ea-ad8c95cb4f9f",
               "employeeId":"3641A-4C718577D",
               "payTypeCode":"0001",
               "value":"20",
               "comment":""
            }
         ],
         "_links":[  
            {  
               "rel":"archive",
               "href":"https://dataloen-api.bluegarden.dk/api/input/salary/[employerId]/forms/archive/05836b1d-1904-4ef6-bec8-28232e345ab7",
               "method":"POST"
            }
         ]
      },
      {  
         "formId":"28bdd4cc-df9b-4ca6-bb6a-433c182dd162",
         "date":"2016-11-29T00:00:00+01:00",
         "state":"archived",
         "reference":"Test reference",
         "entries":[  
            {  
               "entryId":"31c75d9c-8178-434b-99a9-300807587066",
               "employeeId":"3641A-4C718577D",
               "payTypeCode":"0001",
               "value":"20",
               "comment":""
            },
            {  
               "entryId":"4922221a-c7cf-4540-b151-dffbebd7c83c",
               "employeeId":"3641A-4C718577E",
               "payTypeCode":"001F",
               "value":"770",
               "comment":"Test comment"
            }
         ],
         "_links":[  
            {  
               "rel":"unarchive",
               "href":"https://dataloen-api.bluegarden.dk/api/input/salary/[employerId]/forms/unarchive/28bdd4cc-df9b-4ca6-bb6a-433c182dd162",
               "method":"POST"
            }
         ]
      },
      {  
         "formId":"a41d9ec1-decb-433c-8ef7-b19f743de16f",
         "date":"2016-11-29T00:00:00+01:00",
         "state":"committed",
         "reference":"Test reference",
         "entries":[  
            {  
               "entryId":"8eea16d3-3f2f-431d-b6d7-75fc0ce89867",
               "employeeId":"3641A-4C718577D",
               "payTypeCode":"0001",
               "value":"20",
               "comment":""
            },
            {  
               "entryId":"06a0a55e-3df1-4ef8-aca3-a5da93647b0e",
               "employeeId":"3641A-4C718577E",
               "payTypeCode":"001F",
               "value":"770",
               "comment":"Test comment"
            }
         ],
         "_links":[  
            {  
               "rel":"archive",
               "href":"https://dataloen-api.bluegarden.dk/api/input/salary/[employerId]/forms/archive/a41d9ec1-decb-433c-8ef7-b19f743de16f",
               "method":"POST"
            }
         ]
      }
   ],
   "_links":[  
      {  
         "rel":"next",
         "href":"https://dataloen-api.bluegarden.dk/api/input/salary/[employerId]/forms?from=2016-11-07&to=2016-12-07&pageSize=20&page=2"
      },
      {  
         "rel":"last",
         "href":"https://dataloen-api.bluegarden.dk/api/input/salary/[employerId]/forms?from=2016-11-07&to=2016-12-07&pageSize=20&page=2"
      },
      {  
         "rel":"self",
         "href":"https://dataloen-api.bluegarden.dk/api/input/salary/[employerId]/forms?from=2016-11-07&to=2016-12-07&pageSize=20&page=1"
      }
   ]
}

Commit Forms

POST /input/salary/[employerId]/forms/commit
Description: To create salary forms you must POST a collection of forms
Request headers

Key Value Description

Authorization Bearer accessToken

Content-Type application/json

Request body

{  
   "collection":[  
      {  
         "date":"2016-11-29",
         "reference":"UGE 44",
         "entries":[  
            {  
               "employeeId":"3641A-4C718577D",
               "payTypeCode":"0012",
               "value":"770",
               "comment":"TEST"
            },
            {  
               "employeeId":"3641A-4C718577D",
               "payTypeCode":"0012",
               "value":"200",
               "comment":""
            },
            {  
               "employeeId":"3641A-4C718577D",
               "payTypeCode":"0013",
               "value":"300",
               "comment":""
            }
         ]
      }
   ]
}

Response body 200

{  
   "collection":[  
      {  
         "formId":"8246b711-f051-44f7-92dc-f53e986933e6",
         "date":"2016-11-29T00:00:00+01:00",
         "state":"committed",
         "reference":"UGE 44",
         "entries":[  
            {  
               "entryId":"2ea9debe-ad04-4160-b90b-c3cec85530a5",
               "employeeId":"3641A-4C718577D",
               "payTypeCode":"0012",
               "value":"770",
               "comment":"TEST"
            },
            {  
               "entryId":"f596d395-043f-42b2-aba1-a5c9e31a5ade",
               "employeeId":"3641A-4C718577D",
               "payTypeCode":"0012",
               "value":"200",
               "comment":""
            }, 
            {  
               "entryId":"58777bee-a732-410f-a8bd-8f56625b8df3", 
               "employeeId":"3641A-4C718577D", 
               "payTypeCode":"0013", 
               "value":"300", 
               "comment":"" 
            }
         ],
         "_links":[  
            {  
               "rel":"archive",
               "href":"https://dataloen-api.bluegarden.dk/api/input/salary/[employerId]/forms/archive/8246b711-f051-44f7-92dc-f53e986933e6",
               "method":"POST"
            }
         ]
      }
   ]
}

Note: If any form in the collection or any of the entries are invalid, the entire collection will fail. The API will reply with a 400 BadRequest. The response body will contain an echo of the requested collection and each form will be enriched with a collection of validation errors.

Here is an example of an invalid request and the error response

POST /input/salary/[employerId]/forms/commit
Description: To create salary forms you must POST a collection of forms
Request headers

Key Value Description

Authorization Bearer accessToken

Content-Type application/json

Request body

{  
   "collection":[  
      {  
         "date":"",
         "reference":"012345678901234567890123456789012345678901234567890",
         "entries":[  
            {  
               "employeeId":"",
               "payTypeCode":"",
               "value":"",
               "comment":""
            }
         ]
      }
   ]
}

Response body 400

{  
   "collection":[  
      {  
         "errors":[  
            {  
               "code":"001",
               "description":"Date property on salary forms is required and must have format {yyyy-MM-dd}."
            },
            {  
               "code":"002",
               "description":"Reference property on salary forms must not exceed 50 characters."
            }
         ],
         "date":"2017-02-18T00:00:00+01:00",
         "state":null,
         "reference":"012345678901234567890123456789012345678901234567890",
         "entries":[  
            {  
               "errors":[  
                  {  
                     "code":"005",
                     "description":"PayTypeCode property on salary form entries is required and must be 4 characters."
                  },
                  {  
                     "code":"006",
                     "description":"EmployeeId property on salary form entries is required and must not exceed 50 characters."
                  }
               ],
               "employeeId":"",
               "payTypeCode":"",
               "value":"",
               "comment":""
            }
         ],
         "_links":[]
      }
   ]
}

Archive/unarchive forms

An archived form is a form which cannot be imported into DataLøn. Archived forms are still visible through the '/forms' endpoint, and can be unarchived at any time.

To archive or unarchive a salary form you must submit a POST request to the ../forms/archive/[formId] or ../forms/unarchive/[formId] endpoint.

Archive

POST /input/salary/[employerId]/forms/archive/3fa7fce1-d68b-449c-b532-0b6bfbab32d6
Description: Archive
Request headers

Key Value Description

Authorization Bearer accessToken

Content-Type application/json

Response body 200

{  
   "collection":[  
      {  
         "formId":"3fa7fce1-d68b-449c-b532-0b6bfbab32d6",
         "date":"2017-07-18T00:00:00+02:00",
         "state":"committed",
         "reference":"Some reference",
         "entries":[  

         ],
         "_links":[  
            {  
               "rel":"archive",
               "href":"https://dataloen-api.bluegarden.dk/api/input/salary/[employerId]/forms/archive/3fa7fce1-d68b-449c-b532-0b6bfbab32d6",
               "method":"POST"
            }
         ]
      }
   ]
}

Unarchive

POST /input/salary/[employerId]/forms/unarchive/3fa7fce1-d68b-449c-b532-0b6bfbab32d6
Description: Unarchive
Request headers

Key Value Description

Authorization Bearer accessToken

Content-Type application/json

Response body 200

{  
   "collection":[  
      {  
         "formId":"3fa7fce1-d68b-449c-b532-0b6bfbab32d6",
         "date":"2017-07-18T00:00:00+02:00",
         "state":"archived",
         "reference":"Some reference",
         "entries":[  

         ],
         "_links":[  
            {  
               "rel":"unarchive",
               "href":"https://dataloen-api.bluegarden.dk/api/input/salary/[employerId]/forms/unarchive/3fa7fce1-d68b-449c-b532-0b6bfbab32d6",
               "method":"POST"
            }
         ]
      }
   ]
}

All possible form validation errors

`001`	Date property on salary forms is required and must have format {yyyy-MM-dd}.
`002`	Reference property on salary forms must not exceed 50 characters.
`003`	Value property on salary form entries must be in the interval [-99999999;99999999].
`004`	Comment property on salary form entries must not exceed 150 characters.
`005`	PayTypeCode property on salary form entries is required and must be 4 characters.
`006`	EmployeeId property on salary form entries is required and must not exceed 50 characters.
`007`	EmployeeId: [employeeId] does not exist.
`008`	PayTypeCode: [payTypeCode] does not exist.

Artikler i denne sektion

Hypermedia

Base url

Salary (Root endpoint)

Employees

PayTypes

Forms

Commit Forms

Archive/unarchive forms

All possible form validation errors

Kommentarer

Key	Value	Description
Authorization	Bearer `accessToken`
Content-Type	application/json