Versionv1

Global Reseller (1.0)

Download OpenAPI specification:Download

The Global Reseller API allows API users to pull availability and ticket types for connected clients. This information can then be used to create reservations and receive a barcode for sold tickets.

Environments

For this API there is both a test and production and environment available. Use the "environment" parameter in every request. You can select "test" or "production". By default we are selecting the "test" environment.

Please note: you'll be billed for completed ticket reservations in the production environment.

SSL connection

Please use for every request the HTTPS protocol. Requests via HTTP are not working and will result in an error message.

apiKey / apiSecret

The apiKey and apiSecret are generated and provided per Reseller. The apiKey is a public key and needs to be included in every request.

The apiSecret is a private key and never needs to be exchanged or included in the requests. Please use the apiSecret to sign the data with Base64 encode - SHA256 and include this value as "HMACKey".

The calculation is listed on each operation as Base64 encode - SHA256(...), where the fields between the brackets are concatenated. Sort the sign data alphabetical ascending. Only include optional parameters in the HMAC if you are using those parameters.

/getAvailableUsers

This functionality allows you to get all available users within the system.

Note

Best practise is to cache this information and reload the availableUsers periodically (for example: once a day).

HMACKey: Base64 encode - SHA256(apiKey + environment)

Authorizations:

None

Request Body schema: application/json

apiKey required	string public apiKey
environment required	string Enum: "production" "test" "test" or "production"
HMACKey required	string The HMACKey is calculated based on the input fields. Base64 encode - SHA256(apiKey + environment).

Responses

Request samples

Payload

Content type

application/json

{"apiKey": "PUT-YOUR-PUBLIC-API-KEY-HERE",
"environment": "test",
"HMACKey": "PUT-YOUR-CALCULATED-HMAC-KEY-HERE"
}

Response samples

Content type

application/json

{"success": true,
"users": [{"userId": "1",
"userName": "Van Gogh Museum",
"userAddress": {"streetName": "Museumplein",
"houseNumber": "6",
"postalCode": "1071 DJ",
"cityName": "Amsterdam",
"country": "NL"
},
"userCoordinates": {"latitude": "52.3584088",
"longitude": "4.8815176"
},
"userPhoneNumber": "020 570 5200",
"userWebsite": "http://www.vangoghmuseum.nl/",
"userImages": {"logo": "https://globalreseller.nl/web/image.php?path=clientsavatars/594c9b23bee5674a6.png"
},
"userTerms": "https://www.artis.nl/nl/footer/algemene-voorwaarden/online-kaartverkoop/"
}
]
}

/getTicketTypes

This functionality allows you to get all available tickettypes of a selected user (museum).

HMACKey: Base64 encode - SHA256(apiKey + environment + language + ticketDate + userId)

Note

Please note: optional fields only needs to be included when an optional field is used.

Authorizations:

None

Request Body schema: application/json

apiKey required	string Your public apiKey needs to be included in every request.
environment required	string Enum: "test" "production" "test" or "production"
userId required	integer <int32> The userId is a reference to the user (museum / attraction). The userId can be requested via getAvailableUsers and can be cached in your application.
language	string Language code by the ISO 639-1 (most users only supply "nl" and "en")
ticketDate	string it is advisable to implement this to correctly display any adjusted prices after a specific date.
HMACKey required	string The HMACKey is calculated based on the input fields. Base64 encode - SHA256(apiKey + environment + language + ticketDate + userId).

Responses

Request samples

Payload

Content type

application/json

{"apiKey": "string",
"environment": "test",
"userId": 0,
"language": "string",
"ticketDate": "string",
"HMACKey": "string"
}

Response samples

Content type

application/json

{"success": true,
"ticketTypes": [{"ticketTypeId": 1,
"ticketTypeName": "Volwassene",
"ticketTypePrice": 19,
"cancelationPolicy": {"cancelCompleteReservationMinutesBeforeTicketDate": 1440,
"cancelCompleteReservationMinutesAfterReservationDate": 0
}
},
{"ticketTypeId": 2,
"ticketTypeName": "Kind",
"ticketTypePrice": 0,
"cancelationPolicy": {"cancelCompleteReservationMinutesBeforeTicketDate": 1440,
"cancelCompleteReservationMinutesAfterReservationDate": 0
}
},
{"ticketTypeId": 85,
"ticketTypeName": "Volwassene Multimediatour",
"ticketTypePrice": 22,
"cancelationPolicy": {"cancelCompleteReservationMinutesBeforeTicketDate": 1440,
"cancelCompleteReservationMinutesAfterReservationDate": 0
}
},
{"ticketTypeId": 88,
"ticketTypeName": "Kind Multimediatour",
"ticketTypePrice": 0,
"cancelationPolicy": {"cancelCompleteReservationMinutesBeforeTicketDate": 1440,
"cancelCompleteReservationMinutesAfterReservationDate": 0
}
}
]
}

/getAvailability

This functionality allow you to get the availability of a specified period. Some clients allow to make a reservation for a day, others require you to also select a time (for example het Van Gogh Museum). This depends on what availability type is set within the system for this client.

HMACKey: Base64 encode - SHA256(apiKey + endDate + environment + showTicketsAllocation + startDate + userId)

Please note

There are three types of availability:

Timeslots
Date
Period

Authorizations:

None

Request Body schema: application/json

apiKey required	string Your public apiKey needs to be included in every request.
environment required	string Enum: "test" "production" "test" or "production"
userId required	integer <int32> The userId is a reference to the user (museum / attraction). The userId can be requested via getAvailableUsers and can be cached in your application.
startDate required	string <date> Date format: yyyy-mm-dd.
endDate required	string <date> Date format: yyyy-mm-dd.
showTicketsAllocation required	integer <int32> When set to 1 the response will include the amount of available tickets instead of a boolean.
HMACKey required	string The HMACKey is calculated based on the input fields. Base64 encode - SHA256(apiKey + endDate + environment + showTicketsAllocation + startDate + userId).

Responses

Request samples

Payload

Content type

application/json

{"apiKey": "string",
"environment": "test",
"userId": 0,
"startDate": "2019-08-24",
"endDate": "2019-08-24",
"showTicketsAllocation": 0,
"HMACKey": "string"
}

Response samples

Content type

application/json

{"success": true,
"availability": ["2018-05-16"
],
"availabilityType": "date"
}

/createReservation

This functionality allows you to start a ticket reservation. It's possible to reserve multiple tickets in one call / reservation.

HMACKey: Base64 encode - SHA256(apiKey + environment + ticketDate + ticketTime + tickets + userId)

Please note: optional fields only needs to be included when an optional field is used.

Authorizations:

None

Request Body schema: application/json

apiKey required	string Your public apiKey needs to be included in every request.
environment required	string Enum: "test" "production" "test" or "production"
userId required	integer <int32> The userId is a reference to the user (museum / attraction). The userId can be requested via getAvailableUsers and can be cached in your application.
tickets required	Array of integers <int32> [ items <int32 > ] {"ticketTypeId":1001,"ticketNumber":2}
ticketTypeid	integer <int32> "ticketTypeid":123
ticketNumber	string "ticketNumber":2
ticketDate required	string <date> The ticket date must comply with the yyyy-mm-dd format.
ticketTime	string <date-time> (optional) 24 hours format (hh:mm), this field is optional based on the user.
HMACKey required	string The HMACKey is calculated based on the input fields. Base64 encode - SHA256(apiKey + environment + ticketDate + ticketTime + tickets + userId).

Responses

Request samples

Payload

Content type

application/json

{"apiKey": "PUT-YOUR-PUBLIC-API-KEY-HERE",
"environment": "test",
"userId": 1,
"tickets": [{"ticketTypeId": 1001,
"ticketNumber": 2
},
{"ticketTypeId": 1002,
"ticketNumber": 1
}
],
"ticketDate": "2017-01-02",
"HMACKey": "PUT-YOUR-CALCULATED-HMAC-KEY-HERE"
}

Response samples

Content type

application/json

{"success": true,
"reservationId": 687073,
"reservationValidUntil": "2018-11-16 21:06:14"
}

/createCompleteReservation

This request bundles the functionality of createReservation and completeReservation together. It's advisable to use this end-point when your application create & completes in the same second.

Contactinfo required

For some clients it is mandatory to add contact info to this request. Below is the list of clients where this information is required.

Museum name:	Requested as of:
Maddame Taussade Amsterdam	01-01-2023
Amstedam Dungeon	01-01-2023

HMACKey: Base64 encode - SHA256(apiKey + customerEmailAddress + customerFirstName + customerSurname + environment + ticketDate + ticketTime + tickets + userId)

Please note: optional fields only needs to be included when an optional field is used.

Authorizations:

None

Request Body schema: application/json

apiKey required	string Your public apiKey needs to be included in every request.
environment required	string Enum: "production" "test" "test" or "production"
userId required	integer <int32> The userId is a reference to the user (museum / attraction). The userId can be requested via getAvailableUsers and can be cached in your application.
tickets required	Array of integers <int32> [ items <int32 > ]
ticketTypeId required	integer <int32>
ticketNumber required	integer <int32>
TicketDate	string <date> 24 hours format (hh:mm), this field is optional based on the user.
customerFirstName	string Firstname of the customer (Please read "Contactinfo required" below)
customerSurname	string Surname of the customer (Please read "Contactinfo required" below)
customerEmailAddress	string Email address of the customer (Please read "Contactinfo required" below)
HMACKey required	string The HMACKey is calculated based on the input fields. Base64 encode - SHA256(apiKey + customerEmailAddress + customerFirstName + customerSurname + environment + ticketDate + ticketTime + tickets + userId).

Responses

Request samples

Payload

Content type

application/json

{"apiKey": "string",
"environment": "production",
"userId": 0,
"tickets": [0
],
"ticketTypeId": 0,
"ticketNumber": 0,
"TicketDate": "2019-08-24",
"customerFirstName": "string",
"customerSurname": "string",
"customerEmailAddress": "string",
"HMACKey": "string"
}

Response samples

Content type

application/json

{"success": false,
"error message": "text"
}

/completeReservation

With this functionality you will be able to complete a reservation.

Please note: By calling this function you have confirmed the purchase of the tickets. The tickets will be billed by the relevant user (museum) in the production environment.

Tickets from the TEST environment are not valid at the museum.

Contactinfo required

For some clients it is mandatory to add contact info to this request. Below is the list of clients where this information is required.

Museum name:	Required as of:
Van Gogh Museum	01-01-2019
Madame Tussaud Amsterdam	01-01-2023
Amsterdam Dungeon	01-01-2023

HMACKey: Base64 encode - SHA256(apiKey + customerEmailAddress + customerFirstName + customerSurname + environment + reservationId + userId)

Please note: optional fields only needs to be included when an optional field is used.

Authorizations:

None

Request Body schema: application/json

apiKey required	string Your public apiKey needs to be included in every request.
environment required	string Enum: "test" "production" "test" or "production"
userId required	integer <int32> The userId is a reference to the user (museum / attraction). The userId can be requested via getAvailableUsers and can be cached in your application.
reservationId required	integer <int32> Include the reservationId from the createReservation request.
customerFirstName	string Firstname of the customer. (please read "Contactinfo required" below)
customerSurname	string Surname of the customer. (please read "Contactinfo required" below)
customerEmailAddress	string Emailaddress of the customer. (please read "Contactinfo required" below)
externalBarcodes	Array of strings Add your own barcodes with which tickets can also be scanned (one per ticket)
HMACKey required	string The HMACKey is calculated based on the input fields. Base64 encode - SHA256(apiKey + customerEmailAddress + customerFirstName + customerSurname + environment + reservationId + userId).

Responses

Request samples

Payload

Content type

application/json

{"apiKey": "string",
"environment": "test",
"userId": 0,
"reservationId": 0,
"customerFirstName": "string",
"customerSurname": "string",
"customerEmailAddress": "string",
"externalBarcodes": ["string"
],
"HMACKey": "string"
}

Response samples

Content type

application/json

{"success": true,
"ticketBarcodes": [{"barcode": 1231231928311,
"ticketTypeId": 1001,
"barcodeType": "QR"
},
{"barcode": 1287192831231,
"ticketTypeId": 1001,
"barcodeType": "QR"
},
{"barcode": 7172313127312,
"ticketTypeId": 1002,
"barcodeType": "QR"
},
{"barcode": 5181237123612312,
"ticketTypeId": 1002,
"barcodeType": "QR"
}
]
}

/cancelReservation

With this function you can cancel a reservation. This is only possible with a valid reservationId.

HMACKey: Base64 encode - SHA256(apiKey + environment + reservationId + userId)

Authorizations:

None

Request Body schema: application/json

apiKey required	string Your public apiKey needs to be included in every request.
environment required	string Enum: "test" "production" "test" or "production"
userId required	integer <int32> The userId is a reference to the user (museum / attraction). The userId can be requested via getAvailableUsers and can be cached in your application.
reservationId required	integer <int32> Include the reservationId from the createReservation request.
HMACKey required	string The HMACKey is calculated based on the input fields. Base64 encode - SHA256(apiKey + environment + reservationId + userId).

Responses

Request samples

Payload

Content type

application/json

{"apiKey": "string",
"environment": "test",
"userId": 0,
"reservationId": 0,
"HMACKey": "string"
}

Response samples

Content type

application/json

{"success": true,
"message": "contactInfo add was successfully."
}

/cancelCompleteReservation

With this function you can cancel a complete reservation. This is only possible with a valid reservationId and if the user allows to cancel a complete reservation.

HMACKey: Base64 encode - SHA256(apiKey + environment + reservationId + userId)

Authorizations:

None

Request Body schema: application/json

apiKey required	string Your public apiKey needs to be included in every request.
environment required	string Enum: "production" "test" "test" or "production"
userId required	integer <int32> The userId is a reference to the user (museum / attraction). The userId can be requested via getAvailableUsers and can be cached in your application.
reservationId required	integer <int32> Include the reservationId from the /completeReservation request.
HMACKey required	string The HMACKey is calculated based on the input fields. Base64 encode - SHA256(apiKey + environment + reservationId + userId).

Responses

Request samples

Payload

Content type

application/json

{"apiKey": "string",
"environment": "production",
"userId": 0,
"reservationId": 0,
"HMACKey": "string"
}

Response samples

Content type

application/json

{"success": true,
"message": "contactInfo add was successfully."
}

/addContact

This functionality is used to add contact information to a reservation. Please add as many customer information as possible for support and aftersale purposes for the users (museums).

HMACKey: Base64 encode - SHA256(apiKey + customerAddressCity + customerAddressNumber + customerAddressPostalCode + customerAddressStreet + customerCountry + customerEmailAddress + customerFirstName + customerMiddleName + customerPhoneNumber + customerSurname + environment + reservationId + userId)

Authorizations:

None

Request Body schema: application/json

apiKey required	string Your public apiKey needs to be included in every request
environment required	string Enum: "production" "test" "test" or "production"
userId required	integer <int32> The userId is a reference to the user (museum / attraction). The userId can be requested via getAvailableUsers and can be cached in your application
reservationId required	integer <int32> Include the reservationId from the createReservation request
customerFirstName required	string First name of the customer
customerMiddleName	string Mostly used in Dutch names. For example: Vincent van Gogh
customerSurname required	string Surname of the customer
customerEmailAddress required	string Email address of the customer
customerPhoneNumber	string Telephonenumber of the customer
customerAddressStreet	string Street address of the customer
customerAddressNumber	string Housenumber of the customer
customerAddressPostalCode	string Postal code of the customer
customerAddressCity	string City of the customer
customerCountry	string Country of the customer according to the ISO 3166-1 (2 letter country code)
HMACKey required	string The HMACKey is calculated based on the input fields. Base64 encode - SHA256(apiKey + customerAddressCity + customerAddressNumber + customerAddressPostalCode + customerAddressStreet + customerCountry + customerEmailAddress + customerFirstName + customerMiddleName + customerPhoneNumber + customerSurname + environment + reservationId + userId).

Responses

Request samples

Payload

Content type

application/json

{"apiKey": "string",
"environment": "production",
"userId": 0,
"reservationId": 0,
"customerFirstName": "string",
"customerMiddleName": "string",
"customerSurname": "string",
"customerEmailAddress": "string",
"customerPhoneNumber": "string",
"customerAddressStreet": "string",
"customerAddressNumber": "string",
"customerAddressPostalCode": "string",
"customerAddressCity": "string",
"customerCountry": "string",
"HMACKey": "string"
}

Response samples

Content type

application/json

{"success": true,
"message": "contactInfo add was successfully."
}

/checkContact

This functionality is used to check if "addContact" was successful.

HMACKey: Base64 encode - SHA256(apiKey + reservationId)

Authorizations:

None

Request Body schema: application/json

apiKey required	string Your public apiKey needs to be included in every request
reservationId required	integer <int32> Include the reservationId from the createReservation request.

Responses

Request samples

Payload

Content type

application/json

{"apiKey": "string",
"reservationId": 0
}

Response samples

Content type

application/json

{"success": true,
"message": "contactInfo add was successfully."
}