openapi: 3.1.0 info: title: Global Reseller version: "1.0" description: |- 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. servers: - url: https://globalreseller.nl/webservices components: securitySchemes: {} security: - {} paths: /getAvailableUsers: post: summary: /getAvailableUsers description: |- 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)` operationId: getavailableusers requestBody: content: application/json: schema: type: object required: - apiKey - environment - HMACKey properties: apiKey: type: string description: public apiKey environment: type: string description: '"test" or "production"' enum: - production - test HMACKey: type: string description: "The HMACKey is calculated based on the input fields. Base64 encode - SHA256(apiKey + environment)." examples: Example input: value: apiKey: PUT-YOUR-PUBLIC-API-KEY-HERE environment: test HMACKey: PUT-YOUR-CALCULATED-HMAC-KEY-HERE responses: "200": description: "200" content: application/json: examples: Success: value: 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/" schema: type: object properties: success: type: boolean example: true default: true users: type: array items: type: object properties: userId: type: string example: 1 userName: type: string example: Van Gogh Museum userAddress: type: object properties: streetName: type: string example: Museumplein houseNumber: type: string example: 6 postalCode: type: string example: 1071 DJ cityName: type: string example: Amsterdam country: type: string example: NL userCoordinates: type: object properties: latitude: type: string example: 52.3584088 longitude: type: string example: 4.8815176 userPhoneNumber: type: string example: 020 570 5200 userWebsite: type: string example: http://www.vangoghmuseum.nl/ userImages: type: object properties: logo: type: string example: https://globalreseller.nl/web/image.php?path=clientsavatars/594c9b23bee5674a6.png userTerms: type: string example: https://www.artis.nl/nl/footer/algemene-voorwaarden/online-kaartverkoop/ 4XX: description: 4XX content: application/json: examples: Error: value: success: false "error message": "text" schema: type: object properties: success: type: boolean example: false default: true error message: type: string example: text deprecated: false /getTicketTypes: post: summary: /getTicketTypes description: |- 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. operationId: gettickettypes-1 requestBody: content: application/json: schema: type: object required: - apiKey - environment - userId - HMACKey properties: apiKey: type: string description: Your public apiKey needs to be included in every request. environment: type: string description: '"test" or "production"' enum: - test - production userId: type: integer description: The userId is a reference to the user (museum / attraction). The userId can be requested via getAvailableUsers and can be cached in your application. format: int32 language: type: string description: Language code by the ISO 639-1 (most users only supply "nl" and "en") ticketDate: type: string description: it is advisable to implement this to correctly display any adjusted prices after a specific date. HMACKey: type: string description: "The HMACKey is calculated based on the input fields. Base64 encode - SHA256(apiKey + environment + language + ticketDate + userId)." responses: "200": description: "200" content: application/json: examples: Result: value: 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 schema: type: object properties: success: type: boolean example: true default: true ticketTypes: type: array items: type: object properties: ticketTypeId: type: integer example: 1 default: 0 ticketTypeName: type: string example: Volwassene ticketTypePrice: type: integer example: 19 default: 0 cancelationPolicy: type: object properties: cancelCompleteReservationMinutesBeforeTicketDate: type: integer example: 1440 default: 0 cancelCompleteReservationMinutesAfterReservationDate: type: integer example: 0 default: 0 "400": description: "400" content: application/json: examples: Result: value: success: false errorMessage: "Invalid HMAC Key." schema: type: object properties: success: type: boolean example: false default: true errorMessage: type: string example: Invalid HMAC Key. deprecated: false /getAvailability: post: summary: /getAvailability description: |- 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 operationId: getavailability requestBody: content: application/json: schema: type: object required: - apiKey - environment - userId - startDate - endDate - showTicketsAllocation - HMACKey properties: apiKey: type: string description: Your public apiKey needs to be included in every request. environment: type: string description: '"test" or "production"' enum: - test - production userId: type: integer description: The userId is a reference to the user (museum / attraction). The userId can be requested via getAvailableUsers and can be cached in your application. format: int32 startDate: type: string description: 'Date format: yyyy-mm-dd.' format: date endDate: type: string description: 'Date format: yyyy-mm-dd.' format: date showTicketsAllocation: type: integer description: When set to 1 the response will include the amount of available tickets instead of a boolean. format: int32 HMACKey: type: string description: "The HMACKey is calculated based on the input fields. Base64 encode - SHA256(apiKey + endDate + environment + showTicketsAllocation + startDate + userId)." responses: "200": description: "200" content: application/json: examples: Success: value: success: true availability: - "2018-05-16" availabilityType: "date" schema: type: object properties: success: type: boolean example: true default: true availability: type: array items: type: string example: 2018-05-16 availabilityType: type: string example: date "400": description: "400" content: application/json: examples: Result: value: {} schema: type: object properties: {} deprecated: false /createReservation: post: summary: /createReservation description: |- 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. operationId: createreservation requestBody: content: application/json: schema: type: object required: - apiKey - environment - userId - tickets - ticketDate - HMACKey properties: apiKey: type: string description: Your public apiKey needs to be included in every request. environment: type: string description: '"test" or "production"' enum: - test - production userId: type: integer description: The userId is a reference to the user (museum / attraction). The userId can be requested via getAvailableUsers and can be cached in your application. format: int32 tickets: type: array description: '{"ticketTypeId":1001,"ticketNumber":2}' items: type: integer format: int32 ticketTypeid: type: integer description: '"ticketTypeid":123' format: int32 ticketNumber: type: string description: '"ticketNumber":2' ticketDate: type: string description: The ticket date must comply with the yyyy-mm-dd format. format: date ticketTime: type: string description: (optional) 24 hours format (hh:mm), this field is optional based on the user. format: date-time HMACKey: type: string description: "The HMACKey is calculated based on the input fields. Base64 encode - SHA256(apiKey + environment + ticketDate + ticketTime + tickets + userId)." examples: Input: value: 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 responses: "200": description: "200" content: application/json: examples: Result: value: success: true reservationId: 687073 reservationValidUntil: "2018-11-16 21:06:14" schema: type: object properties: success: type: boolean example: true default: true reservationId: type: integer example: 687073 default: 0 reservationValidUntil: type: string example: 2018-11-16 21:06:14 "400": description: "400" content: application/json: examples: Result: value: success: false "error message": "text" schema: type: object properties: success: type: boolean example: false default: true error message: type: string example: text deprecated: false /createCompleteReservation: post: summary: /createCompleteReservation description: |- 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. operationId: createcompletereservation requestBody: content: application/json: schema: type: object required: - apiKey - environment - userId - tickets - ticketTypeId - ticketNumber - HMACKey properties: apiKey: type: string description: Your public apiKey needs to be included in every request. environment: type: string description: '"test" or "production"' enum: - production - test userId: type: integer description: The userId is a reference to the user (museum / attraction). The userId can be requested via getAvailableUsers and can be cached in your application. format: int32 tickets: type: array items: type: integer format: int32 ticketTypeId: type: integer format: int32 ticketNumber: type: integer format: int32 TicketDate: type: string description: 24 hours format (hh:mm), this field is optional based on the user. format: date customerFirstName: type: string description: Firstname of the customer (Please read "Contactinfo required" below) customerSurname: type: string description: Surname of the customer (Please read "Contactinfo required" below) customerEmailAddress: type: string description: Email address of the customer (Please read "Contactinfo required" below) HMACKey: type: string description: "The HMACKey is calculated based on the input fields. Base64 encode - SHA256(apiKey + customerEmailAddress + customerFirstName + customerSurname + environment + ticketDate + ticketTime + tickets + userId)." responses: "200": description: "200" content: application/json: examples: Result: value: success: false "error message": "text" schema: type: object properties: success: type: boolean example: false default: true error message: type: string example: text "400": description: "400" content: application/json: examples: Result: value: {} schema: type: object properties: {} deprecated: false /completeReservation: post: summary: /completeReservation description: |- 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. operationId: completereservation requestBody: content: application/json: schema: type: object required: - apiKey - environment - userId - reservationId - HMACKey properties: apiKey: type: string description: Your public apiKey needs to be included in every request. environment: type: string description: '"test" or "production"' enum: - test - production userId: type: integer description: The userId is a reference to the user (museum / attraction). The userId can be requested via getAvailableUsers and can be cached in your application. format: int32 reservationId: type: integer description: Include the reservationId from the createReservation request. format: int32 customerFirstName: type: string description: Firstname of the customer. (please read "Contactinfo required" below) customerSurname: type: string description: Surname of the customer. (please read "Contactinfo required" below) customerEmailAddress: type: string description: Emailaddress of the customer. (please read "Contactinfo required" below) externalBarcodes: type: array description: Add your own barcodes with which tickets can also be scanned (one per ticket) items: type: string HMACKey: type: string description: "The HMACKey is calculated based on the input fields. Base64 encode - SHA256(apiKey + customerEmailAddress + customerFirstName + customerSurname + environment + reservationId + userId)." responses: "200": description: "200" content: application/json: examples: Result: value: 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" schema: type: object properties: success: type: boolean example: true default: true ticketBarcodes: type: array items: type: object properties: barcode: type: integer example: 1231231928311 default: 0 ticketTypeId: type: integer example: 1001 default: 0 barcodeType: type: string example: QR "400": description: "400" content: application/json: examples: Result: value: success: false "error message": "text" schema: type: object properties: success: type: boolean example: false default: true error message: type: string example: text deprecated: false /cancelReservation: post: summary: /cancelReservation description: |- With this function you can cancel a reservation. This is only possible with a valid reservationId. **HMACKey:** `Base64 encode - SHA256(apiKey + environment + reservationId + userId)` operationId: cancelreservation requestBody: content: application/json: schema: type: object required: - apiKey - environment - userId - reservationId - HMACKey properties: apiKey: type: string description: Your public apiKey needs to be included in every request. environment: type: string description: '"test" or "production"' enum: - test - production userId: type: integer description: The userId is a reference to the user (museum / attraction). The userId can be requested via getAvailableUsers and can be cached in your application. format: int32 reservationId: type: integer description: Include the reservationId from the createReservation request. format: int32 HMACKey: type: string description: "The HMACKey is calculated based on the input fields. Base64 encode - SHA256(apiKey + environment + reservationId + userId)." responses: "200": description: "200" content: application/json: examples: Result: value: success: true message: "contactInfo add was successfully." schema: type: object properties: success: type: boolean example: true default: true message: type: string example: contactInfo add was successfully. "400": description: "400" content: application/json: examples: Result: value: success: false message: "contactInfo add failed." schema: type: object properties: success: type: boolean example: false default: true message: type: string example: contactInfo add failed. deprecated: false /cancelCompleteReservation: post: summary: /cancelCompleteReservation description: |- 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)` operationId: cancelcompletereservation requestBody: content: application/json: schema: type: object required: - apiKey - environment - userId - reservationId - HMACKey properties: apiKey: type: string description: Your public apiKey needs to be included in every request. environment: type: string description: '"test" or "production"' enum: - production - test userId: type: integer description: The userId is a reference to the user (museum / attraction). The userId can be requested via getAvailableUsers and can be cached in your application. format: int32 reservationId: type: integer description: Include the reservationId from the /completeReservation request. format: int32 HMACKey: type: string description: "The HMACKey is calculated based on the input fields. Base64 encode - SHA256(apiKey + environment + reservationId + userId)." responses: "200": description: "200" content: application/json: examples: Result: value: success: true message: "contactInfo add was successfully." schema: type: object properties: success: type: boolean example: true default: true message: type: string example: contactInfo add was successfully. "400": description: "400" content: application/json: examples: Result: value: success: false message: "contactInfo add failed." schema: type: object properties: success: type: boolean example: false default: true message: type: string example: contactInfo add failed. deprecated: false /addContact: post: summary: /addContact description: |- 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)` operationId: addcontact requestBody: content: application/json: schema: type: object required: - apiKey - environment - userId - reservationId - customerFirstName - customerSurname - customerEmailAddress - HMACKey properties: apiKey: type: string description: Your public apiKey needs to be included in every request environment: type: string description: '"test" or "production"' enum: - production - test userId: type: integer description: The userId is a reference to the user (museum / attraction). The userId can be requested via getAvailableUsers and can be cached in your application format: int32 reservationId: type: integer description: Include the reservationId from the createReservation request format: int32 customerFirstName: type: string description: First name of the customer customerMiddleName: type: string description: 'Mostly used in Dutch names. For example: Vincent van Gogh' customerSurname: type: string description: Surname of the customer customerEmailAddress: type: string description: Email address of the customer customerPhoneNumber: type: string description: Telephonenumber of the customer customerAddressStreet: type: string description: Street address of the customer customerAddressNumber: type: string description: Housenumber of the customer customerAddressPostalCode: type: string description: Postal code of the customer customerAddressCity: type: string description: City of the customer customerCountry: type: string description: Country of the customer according to the ISO 3166-1 (2 letter country code) HMACKey: type: string description: "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: "200": description: "200" content: application/json: examples: Result: value: success: true message: "contactInfo add was successfully." schema: type: object properties: success: type: boolean example: true default: true message: type: string example: contactInfo add was successfully. "400": description: "400" content: application/json: examples: Result: value: success: false message: "contactInfo add failed." schema: type: object properties: success: type: boolean example: false default: true message: type: string example: contactInfo add failed. deprecated: false /checkContact: post: summary: /checkContact description: |- This functionality is used to check if "addContact" was successful. **HMACKey:** `Base64 encode - SHA256(apiKey + reservationId)` operationId: checkcontact requestBody: content: application/json: schema: type: object required: - apiKey - reservationId properties: apiKey: type: string description: Your public apiKey needs to be included in every request reservationId: type: integer description: Include the reservationId from the createReservation request. format: int32 responses: "200": description: "200" content: application/json: examples: Result: value: success: true message: "contactInfo add was successfully." schema: type: object properties: success: type: boolean example: true default: true message: type: string example: contactInfo add was successfully. "400": description: "400" content: application/json: examples: Result: value: success: false message: "contactInfo add failed." schema: type: object properties: success: type: boolean example: false default: true message: type: string example: contactInfo add failed. deprecated: false x-readme: headers: - key: Cache-Control value: no-cache explorer-enabled: true proxy-enabled: true x-readme-fauxas: true