Passcreator API Documentation

Transcription

1 Passcreator API Documentation Version December 2014 USt-IdNr.: DE Seite 1 von 9

2 About this Document 3 Obtaining an API key 3 Authentication 3 Testing 3 Get list of pass-templates 4 Get information about a pass-template 4 Get all passes of a pass-template 5 Check if a pass is known to a given ID 6 Get information about a specific pass 7 Create a new pass 7 Update a pass 8 Mark a pass as voided 9 USt-IdNr.: DE Seite 2 von 9

3 About this Document This document describes the REST API that can be used if you or one of your customers has a valid account for the online app that is available at In general a REST API means that you always have to provide a authentication token in the authorization header of every HTTP-Request. The API provides functions to create, read, update and delete Passbook passes. Additionally there are functions to get a list of pass-templates and existing passes. In order to use the API features a pass-template must be created using the Passcreator online app. Creating and updating pass-templates is currently not supported via the API. This documentation is provided as is without any warranty. If you notice that any of the functions or methods don t work as expected or find something that is not described clearly enough please send us an to support@passcreator.de. Also this document might be subject to change as we are constantly adding new features to Passcreator. If you want to get notified about changes to the API please also write us an E- Mail to support@passcreator.de and we ll add you to a recipient list that is notified as soon as a new version of the documentation is available. Obtaining an API key The API key must be submitted in the HTTP Authorization header on every request. It is used to check if the caller is authorized to execute the function. To get the API key log in to Passcreator ( and go to Account Options. You can find the API key at the bottom of the page. Authentication To authorize your request you must always submit the API key in the HTTP Authorization header. Testing If you want to test the API or learn how it works a good way to get used to it without having to code much is installing a browser plugin like Postman ( for Google Chrome. It allows you to test all Passcreator API functions so you can get an idea of how it works. If API functions need complex data this data must be submitted as JSON payload. Also the API functions will return information about the executed steps like IDs of created passes or error messages as JSON arrays. In general the Passcreator API will always return the appropriate HTTP-statuses e.g.: Request was valid and the results are being returned Created - the action you wanted to execute was successful and the information about the created object is returned No Content an error occurred and the request could therefore not be processed. Details about the error is specified in the response Unauthorized - you have specified an invalid or no Authorization header Not found - the given UID could not be found or is invalid. USt-IdNr.: DE Seite 3 von 9

4 Get list of pass-templates URL: Purpose: Returns a list of all pass-templates that have been created for your account. Returned values: JSON-Array containing the UID and the name of your pass-templates. Get information about a pass-template URL: Purpose: Get information about the given pass-template. This information is e.g. needed if you want to create passes for this pass-template. UID of the pass-template that must be specified in the URI. If you don t have a UID you can obtain it by using the function explained in the section Get list of pass-templates. Returned values: JSON-Array containing the following values: identifier: the UID of the pass-template name: the name of the pass-template numberofcreatedpasses: the number of created passes for this pass-template. Pay attention that this is the overall number of passes that have been created, not the number of passes created this month. createpassurl: the API url including the pass-template UID that must be used to create new passes. dynamicfields: JSON-Array that specifies the array that must be submitted when passes are created or updated. For more details see Create a new pass in this document. USt-IdNr.: DE Seite 4 von 9

5 Get all passes of a pass-template URL: Purpose: Returns a list of all passes for the given pass-template. pass-template UID as GET parameter with the parameter name passid. Returned values: JSON-Array containing an array for every pass. The array for the passes contain these fields: identifier: the UID of the pass that can be used e.g. for updates. uri: the URI of the pass that can be used to update or delete it. generatedid: the unique ID that is created for every pass and can e.g. be used for admittance tools to check if a given ID is valid. This ID is usually encoded in the Barcode on the pass if you re not using own IDs. voided: false, if the pass is not voided, means it has not been used. true, if the pass is voided, means it has been used already. searchstring: contains all data on the pass separated by pipe symbols USt-IdNr.: DE Seite 5 von 9

6 Check if a pass is known to a given ID URL: Purpose: Checks if a pass is found for the given ID. This function can e.g. be used to check if a pass that is shown on admittance of a event is valid. To use this it is required that the ID is encoded in the passes barcode. Currently only IDs that are automatically generated by Passcreator can be checked. ID that should be checked for Returned values: JSON-Array containing the following information: error: if an error occurred it is specified here. If the field is empty, no error occurred. identifier: the UID of the pass that has the given ID. uri: the URI you can use to update or delete the pass. generatedid: the ID (this is the one that was given in the request) searchstring: all data that is shown on the pass front or back. Fields are separated by pipe symbols. voided: if true, the pass is voided. This means it has already been used. passtemplateguid: the GUID of the pass-template that was used to create the pass. USt-IdNr.: DE Seite 6 von 9

7 Get information about a specific pass URL: Purpose: If the given pass UID is known information about the pass is returned. UID of the pass you want information about Returned values: JSON-Array containing the following information: identifier: the UID of the pass that has the given ID. uri: the URI you can use to update or delete the pass. generatedid: the generated ID that is used e.g. in the barcode. searchstring: all data that is shown on the pass front or back. Fields are separated by pipe symbols. voided: if true, the pass is voided. This means it has already been used. passtemplateguid: the GUID of the pass-template that was used to create the pass. Create a new pass URL: HTTP-Method: POST Purpose: Create a new pass using the given pass template. ID of the pass template as parameter in the URI. USt-IdNr.: DE Seite 7 von 9

8 An array containing the values that should be shown on the pass as specified by the method that describes a pass template. See Get information about a pass-template in this document. The JSON-Array must be submitted as payload of the request. An example JSON array looks like this: Returned values: JSON-Array containing the following information: identifier: the unique identifier of the created pass uri: the URI that can be used to update or delete the pass linktopassfile: the link where the pkpass-file can be downloaded. The pkpass-file is the actual pass that can be opened on iphones directly. linktopasspage: link to the download page for this pass that detects the operating system of the Smartphone that is used and provides device specific help. ErrorMessage: if an error occurs it is shown here. Update a pass URL: HTTP-Method: PUT Purpose: Update an existing pass. ID of the pass that must be updated in the URI. An array containing the values that should be shown on the pass as specified by the method that describes a pass template. See Get information about a pass-template in this document. The JSON-Array must be submitted as payload of the request. An example JSON array looks like this: USt-IdNr.: DE Seite 8 von 9

9 Returned values: If the pass has been updated successfully HTTP Status 204 is returned. Mark a pass as voided URL: HTTP-Method: PUT Purpose: Mark a pass voided or not. This is e.g. useful, if an event ticket has been used. If a pass is voided the barcode that is shown on the pass will be greyed out on the users device. ID of the pass that must be voided in the URI. Boolean (true or false) that indicates if the pass should be voided or not. If the pass should be voided, the boolean must be true, if it should not be voided the boolean parameter must be false. The passinstance[voided] parameter is also specified in the URI. Returned values: If the pass has been updated successfully HTTP Status 204 is returned. USt-IdNr.: DE Seite 9 von 9