Preparation

Before you can use the go~mus Entry API you will have to register an API account with an API key. Please talk to your contact person in order to get access.

See detailed documentation on Public API for information on how to request the basic data for events, tours and tickets.

Barcodes

We track tickets, events and tours by using barcodes. The barcodes encode unique codes. These codes can be used track entry and exit events.

Barcodes may be encoded as Code128 or Code39. Additionally barcodes may also be encoded in 2D as a QR-Code.

Status API

The status of a barcode can be queried as follows:

GET https://demo.gomus.de/api/v3/barcodes/:barcode

curl -H "Authorization: Bearer meowmeowmeow" "https://demo.gomus.de/api/v3/barcodes/:barcode"

If everything is ok and the barcode is still valid a 200 OK is returned.

Additionally the JSON may contain a message:

{
    "message": "Eintritte: 1"
}

If the barcode was already used or is for some other reason invalid then an error gets returned. The HTTP status code will be 422 Unprocessable Entity.

The JSON if an error occured:

{
    "error": "Barcode wurde schon eingelöst am 13.03.2017"
}

Entry API - Voiding the barcode

To do an actual entry and possibly void the barcode an PUT needs to be sent.

PUT https://demo.gomus.de/api/v3/barcodes/:barcode

curl -XPUT -H "Authorization: Bearer meowmeowmeow" "https://demo.gomus.de/api/v3/barcodes/:barcode"

This will return the same responses as the Status API above. HTTP 200 OK for success and HTTP 422 Unprocessable Entity in case of error.

The barcode will be voided in the process.

In practice it is common to call the Status API first and then void the barcode.

Entry API - Scans

This API is for tracking entry.

Showing the scan event

GET https://demo.gomus.de/api/v4/entry/scans/:scan

Updating the scan event

PUT https://demo.gomus.de/api/v4/entry/scans/:scan

curl "https://demo.gomus.de/api/v4/entry/scans/3"
    -XPUT --data "scan[people_count]=3"
    -H "Authorization: Bearer meowmeowmeow"

The above command returns JSON structured like this:

{
  "scan": {
    "id": 3,
    "barcode": "111yxqgyxGWWVmXEg",
    "entry_at": "2019-09-03T12:55:53+02:00",
    "position": null,
    "device": "3",
    "people_count": 3,
    "is_valid": true,
    "is_entry": true,
    "updated_at": "2019-09-03T21:53:20+02:00",
    "created_at": "2019-09-03T12:55:53+02:00"
  }
}

Response

The JSON response contains a serialized scan event.

Entry API - Config

This API provides a basic configuration of a scanner devise with colors and texts for each entry zone.

Showing a configuration of a scanner devise

GET https://demo.gomus.de/api/v4/entry/config

Required parameters:

id of the entry zone (string), the unique database id of the entry zone

curl "https://demo.gomus.de/api/v4/entry/config?entry_zone=RW50cnlab25lLTAyUmhtWP=="

The above command returns JSON structured like this:

{
  "config": {
    "id": "RW50cnlab25lLTAyUmhtWP==",
    "name": "B7D",
    "settings": {
      "primary_color": "#1AB394",
      "headline": "go~mus",
      "background_color": "#F5F5F5",
      "background_color_valid": "#1CAC26",
      "background_color_warning": "#F8C81C",
      "default_panel_color": "#FFFFFF",
      "warning_panel_color": "#AE0015",
      "warning_text_color": "#FFFFFF",
      "text_color": "#4A4A4A",
      "button_default_color": "#4A4A4A",
      "button_default_filling": "#F5F5F5",
      "button_info_color": "#00608",
      "button_info_filling": "#F5F5F5",
      "button_warning_color": "#AE0015",
      "button_warning_filling": "#F5F5F5"
    }
  }
}

Response

The JSON response contains a basic config of a scanner devise depending on the provided entry zone.

id (string), the unique database id of the entry zone
name (string), the name of the entry zone
settings, basic settings of colors and texts

Note: The color codes of settings should be wrapped with quotes (“”)

Exit API - Tracking exits

This API is for tracking exits

PUT https://demo.gomus.de/api/v3/barcodes/:barcode/exit

curl -XPUT -H "Authorization: Bearer meowmeowmeow" "https://demo.gomus.de/api/v3/barcodes/:barcode/exit"

This will return responses in the same structure as the Status API above. HTTP 200 OK for success and HTTP 422 Unprocessable Entity in case of error.

Additional Parameters

The following parameters can be used to set additional infos:

location : string - where did the entry or exit happen

You can transmit these parameters in the URL. For example:

https://demo.gomus.de/api/v3/barcodes/:barcode/exit?location=Haupthaus

Best practices

Turnstiles

When using turnstiles it is best practice to only void the barcode if the visitor actually goes through. In some cases the visitor may scan his ticket barcode but then not walk through. He should be able to re-scan his ticket barcode and then walk through.

Errors

The go~mus API uses the following error codes:

Error Code	Meaning
401	Unauthorized – Your API key is wrong
403	Forbidden – The API endpoint requested is for administrators only
404	Not Found – The specified record could not be found
405	Method Not Allowed – You tried to access an API endpoint with an invalid method
422	Unprocessable Entity – The data you have passed cannot be processed
429	Too Many Requests – You’re requesting too much! Slow down!
500	Internal Server Error – We had a problem with our server. Try again later.
503	Service Unavailable – We’re temporarially offline for maintanance. Please try again later.