//[[restapi:start|RESTful API]]// ===== Overview ===== The digital passes are becoming incresingly common use around the world to substitute paper passes, reach wider audiences and speed deliveries up. The API described in this documentation allows you to create a single template to deliver multiple passes and bind information with any data server to write on them specific data. Once your end-users have accepted the passes you sent, you can update each single pass or all the passes delivered simultaneously according to your needs. {{:restapi:apple_wallet_ios_9_icon.png?100,nolink |}} {{:restapi:logomark.png?100,nolink |}} The two main digital wallets in the market are supported: [[https://developer.apple.com/wallet/| Apple Wallet]] and [[https://pay.google.com/about/ | Google Pay.]] You can use the same single template to reach both platforms and their respective protocols. This API allows you to manipulate in many ways your wallet campaigns: you can create a template and, later on, retrive it, modify it or delete it; you order the creation of the passes by building their delivery URLs and matching their variable fields with the external source data origin of your preference. The delivery endpoint checks the platform of your end-users with your directives to know what kind of pass it will deliver. Apple Wallet format file .pkpass can be also read by several Android Apps; this platform has support for Attido Passwallet Push update service if you order Android to get that format instead of Google Pay. The server sets up the proper endpoints to accomplish with [[https://developer.apple.com/library/content/documentation/UserExperience/Conceptual/PassKit_PG/Updating.html#//apple_ref/doc/uid/TP40012195-CH5-SW1|Apple Wallet Push update protocol]]. You only have to order the updates and the platform will do the rest backstage. In Google Pay the passes are updated in the cloud and the devices synchronize to the last information stored. This API follows the RESTful principles, therefore the endpoints have noun names, they have to be called with the proper HTTP verb (GET, POST, PUT or DELETE) and the larger information is sent via payload. The transactional results are sent in XML while the objects can be defined in XML or JSON. The endpoints where you interact to the server directly are signed, while those called by devices are not, due to Apple's protocol path structure. ===== Lifecycle of Wallet campaigns in API ===== To start a Wallet campaign you need to be registered in Messangi platform. If you are not registered, please conntact with our support team. When registered you can check your company name using [[#Get organization name]], used inside passes' metadata. The campaign requires the following resources and steps: - Create a Wallet template: call the [[#Create Wallet Template]] endpoint and send on payload the Wallet Template object in JSON format. - Upload passes images: you have to provide from 2 up to 6 images to fill in the template. These images will be used in all the passes delivered from the server. Call the [[#Store image file for Wallet]] to upload one by one. - Querying: If you want to check the information you stored in the Wallet template use [[#Get Wallet Template]]. Also, if you want to check the images you uploaded to support that template, use [[#Get Wallet image file]]. And if you want to get a list of all the templates you created use [[#Get Wallet Templates list]]. - If you want to add custom data inside the passes, you must set the matches between your source data origin fields and the template fields using [[#Set template-to-data attribute matches]]. Your source data origin server has to provide an endpoint to query the custom data everytime. - To create and enable the final passes in the server just call [[#Get Wallet URL list]] with the recipients list (phone number list only or email address list only) and you will get in response a JSON object, mapping the URL for each one of them. With that URLs your end-users will get the passes with the art of the template and the information of the template matched with your data origin according to your commands in the previous step. - The URLs you get in the previous step are shortened URLs to the enpoint [[#Wallet passes Delivery]]. You must **not call it directly**, the valid calls are just made by the previous endpoint. - In order to track your campaign broadcasts you can use the [[#Register Wallet Campaign]]. There you can store important metadata of each broadcast you made. To retrieve the previous information use [[#Get Wallet broadcast]]. - When you need to make changes to the template itself use [[#Update Wallet template]] and send in the payload the Wallet Template object in JSON format. - Apple requires from Wallet developers set up several endpoints to manage the protocol to register and unregister devices and passes in order to enable Apple Push Notification Service. All that work is already made inside this server with the endpoints in [[#Register Device for Wallet updates]], [[#Register Device for PassWallet updates]], [[#Send New Pass to Wallet apps]], [[#Get changed passes list]], [[#Remove Wallet Registration]] and [[#Logging errors from device to server]]. You only have to provide the information of your template fields, images and recipients and the server will manage all the protocol process. - To send dynamic updates to your end-users' passes, use [[#Send massive push updates for passes]] when changes has been made in template. But if you just want to reach a single end-user use [[#Send single pass push update]] instead. - Once you consider your campaign is over and you don't want your customers to get new passes from that campaign, use [[#Delete Wallet Template]] to delete all the information in the server. ===== Get organization name ===== ==== Overview ==== Given a client identificator code, returns the Organization name used as parameter in some endpoints in this API ==== URL ==== GET https://api.messangi.com/messangi-staging/rest/message/Passbook/organization/{clientId}/{timeStamp}/{signature} ==== Parameters ==== ^ Parameter Name ^ Description ^ | clientId | Your client Id assigned to access the platform | | timeStamp | The number of milliseconds since January 1, 1970. You can easly produce it in Java with getTime() method on a Date object | | signature | The unique [[restapi:appx_ciphering#SHA256 - Cipher|SHA256]] signature for this call, it involves all input parameters. To learn about generating the correct signature please visit our [[restapi:appx_call_ex|Java Example]] | ==== Response ==== A String text with the Organization name related with the clientId ===== Create Wallet Template ===== ==== Overview ==== Stores a Wallet template in the server using a JSON object data. ==== URL ==== POST https://api.messangi.com/messangi-staging/rest/message/Passbook/templates/{templateName}/{clientId}/{timeStamp}/{signature} If you want to use special characters in template name just encode it using base64 and call this endpoint instead of the previous one: POST https://api.messangi.com/messangi-staging/rest/message/Passbook64/templates/{templateNameEncoded}/{clientId}/{timeStamp}/{signature} ==== Parameters ==== ^ Parameter Name ^ Description ^ | templateName | The name for the new template | | templateNameEncoded | The name for the new template encoded using base64 | | clientId | Your client Id assigned to access the platform | | timeStamp | The number of milliseconds since January 1, 1970. You can easly produce it in Java with getTime() method on a Date object | | signature | The unique [[restapi:appx_ciphering#SHA256 - Cipher|SHA256]] signature for this call, it involves all input parameters. To learn about generating the correct signature please visit our [[restapi:appx_call_ex|Java Example]] | ==== Payload ==== A json object with proper structure of a Wallet template object. You can build this object using our java beans available here{{ :restapi:passbookbeans.rar |}} { "transitType":null, "thumbnail":null, "thumbnailFixed":null, "footer":null, "footerFixed":null, "templateName":Demo Passes for customers", "organization":"Company Name", "iBeacons":[{"major":100,"minor":10,"fixed":"f","text":"This is a beacon","status":"","uuid":"E2C56DB5-DFFB-48D2-B060-D0F5A71096E0"}], "logo":"31345fa5b31a87c0590eb50d77add0975649139a", "logoFixed":"f", "passTypeId":"pass.com.messangi.passbook", "templateSHA1":"90c382c79b7534a58c87f27e97ef1ce541831197", "strip":null, "stripFixed":null, "background":null, "backgroundFixed":null, "lastUpdated":"30-08-2015 12:11:25", "expirationDate":"2017-02-07T12:10:00-05:00", "description":"Test wallet", "serial":"LYWcpB3nzMX1Cpmx6OFcfK1GlZNtm_FnnOeFY7CONvlZuBpcL5BWHoa3xKAd7bxqKBhD1OM2Hh45TGnEb6MFi6pIu58wp-cIzzeAx3BQboQ*", "relevantDate":"2017-01-04T12:10:00-05:00", "barcodeContent":"https://www.google.com/", "barcodeLabel":"Google Official Web Page", "backgroundColor":"#2255ff", "labelColor":"#ab45b0", "foreColor":"#38aab1", "descriptionFixed":"f", "logoTextFixed":"f", "relevantDateFixed":"f", "expirationDateFixed":"f", "barcodeContentFixed":"f", "barcodeLabelFixed":"f", "icon":"31345fa5b31a87c0590eb50d77add0975649139a", "iconFixed":"f", "maximumDistance":100, "barcodeType":"QR", "locations":[{"latitude":37.43900253544606,"longitude":-122.1458918105788,"status":"","label":"Boulevard Arturo Uslar Pietri, Caracas, Miranda, Venezuela"}], "logoText":"testqa", "passbookType":"storecard", "fields":[{"fixed":"f","status":"","label":"Label Auxiliary","place":"AUXILIARY","value":"Content Auxiliary"},{"fixed":"f","status":"","label":"Label Back Side","place":"BACK","value":"Content Back Side"},{"fixed":"f","status":"","label":"Label Header","place":"HEADER","value":"Content Header"},{"fixed":"f","status":"","label":"Label Primary","place":"PRIMARY","value":"Ogangi"},{"fixed":"f","status":"","label":"Label Secondary","place":"SECONDARY","value":"Content Secondary"}] } \\ === Simple attributes === ^ Attribute Name ^ Description ^ Possible Values ^ | organization | Your company name string as registered in the server | Can be empty, written by server| | templateName | Name of the template you assigned | Any non-null string lesser than 150 characters | | serial | The serial identificator of the template. Assigned by the server | Can be empty, this field is written only by server | | passbookType | The Apple Wallet format used in the template | One of the following: "boarding", "storecard", "coupon", "event", "generic" | | transitType | Applies only if passbookType is "boarding" | One of the following: "air", "boat", "bus", "train", "generic" | | logo | SHA1 of the logo image | Hexadecimal string of 40 chars | | logoFixed | Defines if logo image is fixed (all passes) or variable (specific per pass) | One of the following: "f", "v"| | icon | SHA1 of the thumbnail image | Hexadecimal string of 40 chars | | iconFixed | Defines if icon image is fixed (all passes) or variable (specific per pass) | One of the following: "f", "v"| | strip | SHA1 of the thumbnail image | Hexadecimal string of 40 chars or null if not present| | stripFixed | Defines if strip image is fixed (all passes) or variable (specific per pass) | One of the following: "f", "v"| | background | SHA1 of the thumbnail image | Hexadecimal string of 40 chars or null if not present| | backgroundFixed | Defines if background image is fixed (all passes) or variable (specific per pass) | One of the following: "f", "v"| | thumbnail | SHA1 of the thumbnail image | Hexadecimal string of 40 chars or null if not present| | thumbnailFixed | Defines if thumbnail image is fixed (all passes) or variable (specific per pass) | One of the following: "f", "v"| | footer | SHA1 of the footer image | Hexadecimal string of 40 chars or null if not present | | footerFixed | Defines if footer image is fixed (all passes) or variable (specific per pass) | One of the following: "f", "v"| | labelColor | RGB for labels color (the captions of fields) | Hexadecimal color string of 6 chars with character # at the beggining | | foreColor | RGB for texts color (the content of fields) | Hexadecimal color string of 6 chars with character # at the beggining | | backgroundColor | RGB for background color of the pass (if no background image available) | Hexadecimal color string of 6 chars with character # at the beginning | | description | Brief text that describes the purpose of the passes | Any non-null string lesses than 1000 characters | | descriptionFixed | Defines if description text is fixed (all passes) or variable (specific per pass) | One of the following: "f", "v"| | logoText | The title text in the upper center of the passes | Any string lesser than 20 characters | | logoTextFixed | Defines if description text is fixed (all passes) or variable (specific per pass) | One of the following: "f", "v"| | barcodeType | Passes barcode format | One of the following: "QR", "PDF-417", "Aztec" | | barcodeContent | The text codified on barcode | Any string lesser than 500 characters | | barcodeContentFixed | Defines if barcode content is fixed (all passes) or variable (specific per pass) | One of the following: "f", "v"| | barcodeLabel | Label below barcode | Any string lesser than 50 characters | | barcodeLabelFixed | Defines if barcode label is fixed (all passes) or variable (specific per pass) | One of the following: "f", "v"| | maximumDistance | The maximum distance to show notifications of geolocation | A non-negative integer number | | relevantDate | The metadata relevant date to store in passes. Used to show notifications. | W3C date format "YYYY-MM-DD'T'hh:mm:ss(+/-)hh:mm" | | relevantDateFixed | Defines if relevant date is fixed (all passes) or variable (specific per pass) | One of the following: "f", "v"| | expirationDate | The metadata expiration date to store in passes. When a pass is expired, the barcode is blurred | W3C date format "YYYY-MM-DD'T'hh:mm:ss(+/-)hh:mm" | | expirationDateFixed | Defines if expiration date is fixed (all passes) or variable (specific per pass) | One of the following: "f", "v"| | templateSHA1 | A control SHA1 checksum of the template. Written by server | Can be empty | | passTypeId | Apple Developer Certificate Wallet Type. Written by server | Can be empty | | lastUpdated | Timestamp of the last moment when the template was edited. Written by server | Can be empty. Format used "DD-MM-YYYY hh:mm:ss" | === Array attributes === ^ Attribute Name ^ Description ^ Possible Values ^ | fields | JSON array of template text fields, with keys: **label** (caption), **place** (place name in the layout), **value** (content of field), **fixed** (fixed of variable), **status** (empty)| label: non-null string lesser than 50 chars; place: one of the following: "HEADER", "PRIMARY", "SECONDARY", "AUXILIARY", "BACK"; value: non-null string lesser than 1000 chars; fixed: one of the following: "f", "v; status: must always be empty (used for internal control only)| | iBeacons | JSON array of iBeacons ids for indoor notifications, with keys: uuid(string), major (numeric), minor (numeric), fixed (string) and text (string), status (empty) | **uuid** uses only valid strings used on iBeacons identification; **major and minor** must be integer values between 0 and 65535; fixed indicates if the notification for the beacon will be a fixed text or variable (using source data origin) use literal "f" for fixed and "v" for variable; status must always be empty (used for internal control only)| | locations | JSON array of geolocation places for notifications with keys: latitude (long), longitude (long), label (string), status(empty) | latitude: a long number between -90 and 90; longitude: a long number between -180 and 180; label: a non-null string lesser than 100 chars; status must always be empty (used for internal control only)| ==== Response ==== true Template: Successful operation - Fields: Successful operation - Locations: Successful operation - iBeacons: Successful operation The response XML above will have as many repetitions as fields, locations and / or iBeacons the template had ===== Get wallet image file ===== ==== Overview ==== Sends a specific image of a Wallet template stored on server. It's useful to verify if an image is available and check the image art itself. ==== URL ==== GET https://api.messangi.com/messangi-staging/rest/message/Passbook/templates/image/{templateName}/{filename}/{clientId}/{timeStamp}/{signature} If you want to use special characters in template name just encode it using base64 and call this endpoint instead of the previous one: GET https://api.messangi.com/messangi-staging/rest/message/Passbook64/templates/image/{templateNameEncoded}/{filename}/{clientId}/{timeStamp}/{signature} ==== Parameters ==== ^ Parameter Name ^ Description ^ | templateName | The name of the Wallet template | | templateNameEncoded | The name of the Wallet template encoded using base64 | | filename | Role name for the file according to Wallet specification (must include file extension .png) | | clientId | Your client Id assigned to access the platform | | timeStamp | The number of milliseconds since January 1, 1970. You can easly produce it in Java with getTime() method on a Date object | | signature | The unique [[restapi:appx_ciphering#SHA256 - Cipher|SHA256]] signature for this call, it involves all input parameters. To learn about generating the correct signature please visit our [[restapi:appx_call_ex|Java Example]] | ==== Response ==== The requested PNG image file. ===== Store image file for Wallet ===== ==== Overview ==== Creates a new file for a support Wallet image. It stores the image in three different sizes automatically, to comply Apple Wallet standard (non-retina, retina and retina HD). ==== URL ==== POST https://api.messangi.com/messangi-staging/rest/message/Passbook/templates/image/{templateName}/{filename}/{clientId}/{timeStamp}/{signature} If you want to use special characters in template name just encode it using base64 and call this endpoint instead of the previous one: POST https://api.messangi.com/messangi-staging/rest/message/Passbook64/templates/image/{templateNameEncoded}/{filename}/{clientId}/{timeStamp}/{signature} ==== Parameters ==== ^ Parameter Name ^ Description ^ | templateName | The name of the Wallet template | | templateNameEncoded | The name of the Wallet template encoded using base64 | | filename | Name for the file according to Wallet specification (without file extension) | | clientId | Your client Id assigned to access the platform | | timeStamp | The number of milliseconds since January 1, 1970. You can easly produce it in Java with getTime() method on a Date object | | signature | The unique [[restapi:appx_ciphering#SHA256 - Cipher|SHA256]] signature for this call, it involves all input parameters. To learn about generating the correct signature please visit our [[restapi:appx_call_ex|Java Example]] | The Apple Wallet specification has only this 6 names allowed: logo, icon, strip, background, thumbnail and footer. The first 2 are mandatory, while the others are optional and their use depends on Wallet type ==== Payload ==== The Input Stream of Multipart data from the original file. ==== Response ==== Returns HTTP Status 200 if the file is successfully stored, HTTP Status 500 otherwise ===== Get Wallet Templates list ===== ==== Overview ==== Lists the main information about all templates related to a specific organization. ==== URL ==== GET https://api.messangi.com/messangi-staging/rest/message/Passbook/templates/{filter}/{initialRow}/{finalRow}/{clientId}/{timeStamp}/{signature} ==== Parameters ==== ^ Parameter Name ^ Description ^ | initialRow | First row number in the list | | finalRow | Last row number in the list | | filter | The expression to filter list names | | clientId | Your client Id assigned to access the platform | | timeStamp | The number of milliseconds since January 1, 1970. You can easly produce it in Java with getTime() method on a Date object | | signature | The unique [[restapi:appx_ciphering#SHA256 - Cipher|SHA256]] signature for this call, it involves all input parameters. To learn about generating the correct signature please visit our [[restapi:appx_call_ex|Java Example]] | ==== Response ==== A list with data of the tenmplates: template name, Wallet type, number of images uploaded, barcode type, number of locations associated and number of iBeacons associated. All other properties are ignored and presented as null Example response XML: 16 Demo pass for customers storecard 31345fa5b31a87c0590eb50d77add0975649139a 31345fa5b31a87c0590eb50d77add0975649139a