Skip to content

Retrieving data from Personalkollen

Introduction

We currently provide API:s that allows you to retrieve data for the following data models:

  • Logged times - these objects represents shifts that staff has worked
  • Work periods (scheduled shifts) - these objects represents a scheduled shift for a staff
  • Staff - these objects represents physical persons/employees
  • Sales - these objects represents sales made by a cash register
  • Sale forecast - forecasted sale sums per day
  • Workplaces - these objects represents physical locations within a company

The API:s follows RESTful principles and you can interact with it via HTTPS. The result is provided in JSON format.

If you have any questions, feedback or ideas for improvement, please reach out to us at teknik@personalkollen.se.

These API:s are currently available by invitation only, subject to change without prior notice and not covered by any backward compatibility guarantees. Some URL:s returned by the API are currently not available for requests. However, the URL:s themselves are useful as unique identifiers.

Authentication

You need an authentication token to interact with the API. You can generate your own token on the integration settings page. The authentication token should be passed in the HTTP Authorization header as Token <your token>. See the example request below for more information.

Note: The authentication token for retrieving data is different from the authentication token/secret that is used to send cash register data.

Making requests and getting the response

Requests are made to the URL listed in the documentation for each data model above. Filters can be applied as query string parameters. The result is returned in JSON format. Using HTTPS is mandatory.

Handling errors

If you send an invalid token or malformed query parameters with the request, the server will respond with an appropriate HTTP error status code, and a detailed error response will be returned in the HTTP response body. The HTTP status code will be 200 OK for successful responses.

Pagination

If the requested data cannot fit in a single response, it must be fetched in multiple requests. The response contains an attribute called next that will be the URL of the next page. When there are no more results next will be null.

The actual data can be found as a list of objects in the results field.

Example request

Here is a basic example using using httpie client which shows the basic structure of the request and response. The actual result objects has been omitted below, but more examples are available on the documentation page for each API.

$ http https://personalkollen.se/api/logged-times/ "Authorization: Token demo"

GET /api/logged-times/ HTTP/1.1
Accept: */*
Accept-Encoding: gzip, deflate
Authorization: Token demo
Connection: keep-alive
Host: personalkollen.se
User-Agent: HTTPie/0.9.8

HTTP/1.0 200 OK
Allow: GET, HEAD, OPTIONS
Cache-Control: no-cache, no-store, must-revalidate, max-age=0
Content-Type: application/json
Date: Fri, 10 Mar 2017 13:53:25 GMT
Expires: Fri, 10 Mar 2017 13:53:25 GMT
Sync-Cursor: 2017-03-10T13:53:25.795943+00:00
Last-Modified: Fri, 10 Mar 2017 13:53:25 GMT
Vary: Cookie
X-Frame-Options: SAMEORIGIN

{
    "next": "https://personalkollen.se/api/logged-times/?cursor=cD0xMjcxMjQ%3D",
    "previous": null,
    "results": [
    ...
    ]
}