Main Concepts

est. reading time: 4 minutes.

Hostnames

Live environment:

https://api.pos.zmyle.de

Sandbox environment:

https://posapi.zmyledemo.de

Authentication

The zmyle API uses HTTP Basic Authentications via API keys to authenticate requests. You can view and manage your API keys in your zmyle backoffice under "Developer" / "Entwickler". Keep your API Keys secure! They allow access to your account and your giftcard transactions. Do not share your API keys in any publicly available place such as GitHub or client-side code.

Data Format: JSON

Our API uses JSON as data format. All responses from our API will carry the HTTP Response Header Content-Type: application/json. Data sent to our API in a request body must be in JSON format and your request must include the HTTP Request header Content-Type: application/json.

Errors

The zmyle API uses common HTTP response codes to outline the outcome of API requests. Response codes in the 2xx range indicate success. Response codes in the 4xx range indicate errors that are caused by the information provided in the request (outside influences). For example, you'll get a 4xx response when providing a wrongly formatted money amount or looking for a giftcard that does not exist.

Response codes in the 5xx range indicate an internal error that occurred on zmyle's servers. This would be our fault, and we hope that you will never encounter any 🤖.

Error Handling

All erroneous responses contain an error code that briefly explains the error. You can handle lots of those errors programmatically. Most error codes are mentioned directly in the endpoint descriptions. Here's an example error payload:

{
    "errorId": "api:io:missingRequiredParam",
    "errorMsg": "giftcardId",
    "status": 400,
    "occuredAt": "20171126T060137Z"
}

Dates

Dates are strings in ISO-8601 format yyyyMMdd'T'hhmmss'Z' and are always in UTC. For example 20201008T033240Z.

Money

Money amounts are always given in the smallest unit of a currency (100 cents instead of 1 EUR). Money amounts are always positive integer numbers.

Metadata

Some objects, notably giftcard transactions, have a metadata field. You can use this field to store any key-value data along with those objects. You can specify up to 20 keys, with key names up to 24 characters long and values up to 240 characters long. You can use metadata to store any supporting structured data with zmyle objects. We do not use your metadata for anything internally. This data is solely for you to make sense of.

Idempotency

The zmyle API provides idempotency for select endpoints. This allows you to safely retry those requests while only executing the same function once. This is helpful when API calls get interrupted, for example b/c of connection issues, and you were not able to receive a response. You can simply retry such requests.

Provide an additional body parameter idempotencyKey together with your other body parameters to enable idempotency on those select endpoints.

The endpoints that support idempotency are marked as such, but you will never find this for any GET requests as they are idempotent by nature.

An idempotency key is a string generated by you and it should be unique; we suggest you use V4 UUIDs. We limit the length of your key to a maximum of 40 characters. If your key is more than 40 characters long we will simply use the first 40 characters. We will not show any errors for keys that are too long.

We keep your idempotency keys for 12 hours. If you reuse the same key after 12 hours we will assume this is a new request.

QR-Codes

All zmyle giftcards carry a QR-Code. The QR-Code contains a url that uniquely identifies a giftcard. The URLs follow a specific format. To test if a QR-Code contains a zmyle giftcard url, you can use a regular expression, a hostnames-list, or both.

Example urls:

• https://www.smartcity-gutschein.de/g/20ad4j13mnj16k3fgrhq/redeem?rt=kqmn20ad4j13nijlha3mux

• https://www.smartcity-gutschein.de/g/1k2ed6hg8096mficfqih/redeem?rt=u9df1k2ed6hg8fem9jbuni

Detect zmyle QR-Codes by Regular Expression

You can use the following regular expression to test if the QR-Code contains a zmyle giftcard url:

(https:\/\/.*)\/g\/([a-z0-9]{12,})(\/.*)?\?r?t=([a-z0-9]{15,})$

Detect zmyle QR-Codes by Hostname

You can download a list of hostnames from the zmyle API by using this request.

You can use this list to test if the QR-Code contains a zmyle giftcard url. Simply find the url's hostname in the list:

hostnames = <hostnames cache, i.e. ["https://www.smartcity-gutschein.de", "https://www.zmyledemo.de", ...]>

def starts_with_zmyle_hostname(input_value):
  for hostname in hostnames:
    if input_value.startswith(hostname):
      return True
  return False

qrcode_contents = "https://www.smartcity-gutschein.de/g/20ad4j13mnj16k3fgrhq/redeem?rt=kqmn20ad4j13nijlha3mux"
is_zmyle_giftcard = starts_with_zmyle_hostname(qrcode_contents)

The list only changes when you leave or join giftcard-networks, which is rare. It is generally ok to cache this list, but it might make sense to re-download every now and then. We recommend to re-download this list at least once a week. Lists are short and usually contain less than 5 entries.