Skip to content

Latest commit

 

History

History
812 lines (684 loc) · 22.3 KB

boarding_pass.md

File metadata and controls

812 lines (684 loc) · 22.3 KB

Boarding Passes

Attention: This pass is not yet supported by Android Pay, please check the Android Pay documentation for more details.

Boarding passes can be airplane, bus, train, or boat tickets. You also can create generic boarding passes.

Examples of Boarding Passes

img1 img2
Generic Boarding Schematic Skyport Airways (Flight 815)

Creating a Airplane Boarding Pass Campaign for "Skyport Airways" flight 815

POST /v2/boarding_passes/

Payload:

{
  "boarding_pass": {
    "name": "Skyport Airways flight 815",
    "icon_id": "ffe0d88f-916d-4a12-8244-9ecd0178ca45",
    "logo_id": "a8d93197-3a26-4b91-9551-6091f42a5be4",
    "barcode": {
    	"format": "pdf417"
    },
    "logo_text": "Skyport Airways",
    "foreground_color": "#6e3716",
    "background_color": "#325bb9",
    "transit_type": "air",
    "header_fields": [
      {
        "label": "GATE",
        "key": "gate",
        "value": "23"
      }
    ],
    "primary_fields": [
      {
        "key": "depart",
        "label": "SAN FRANCISCO",
        "value": "SFO"
      },
      {
        "key": "arrive",
        "label": "NEW YORK",
        "value": "JFK"
      }
    ],
    "secondary_fields": [
      {
        "key": "passenger",
        "label": "PASSENGER"
      }
    ],
    "auxiliary_fields": [
      {
        "label": "DEPART",
        "key": "boardingTime"
      },
      {
        "label": "FLIGHT",
        "key": "flightNewName",
        "value": "815"
      },
      {
        "key": "class",
        "label": "DESIG."
      },
      {
        "key": "date",
        "label": "DATE",
        "value": "7/22"
      }
    ]
  }
}

Response:

{
  "id": "485d2a26-efc5-4f85-8855-fa2f4b6cd2e2",
  "name": "Skyport Airways flight 815",
  "template_id": "492d648f-559b-482f-a3c2-2a43aa194aed",
  "organization_name": "foobar",
  "barcode": {
    "format": "pdf417",
    "message": "",
    "alt_text": ""
  },
  "allow_multiple_redeems": false,
  "header_fields": [
    {
      "key": "gate",
      "value": "23",
      "label": "GATE"
    }
  ],
  "primary_fields": [
    {
      "key": "depart",
      "value": "SFO",
      "label": "SAN FRANCISCO"
    },
    {
      "key": "arrive",
      "value": "JFK",
      "label": "NEW YORK"
    }
  ],
  "secondary_fields": [
    {
      "key": "passenger",
      "value": null,
      "label": "PASSENGER"
    }
  ],
  "auxiliary_fields": [
    {
      "key": "boardingTime",
      "value": null,
      "label": "DEPART"
    },
    {
      "key": "flightNewName",
      "value": "815",
      "label": "FLIGHT"
    },
    {
      "key": "class",
      "value": null,
      "label": "DESIG."
    },
    {
      "key": "date",
      "value": "7/22",
      "label": "DATE"
    }
  ],
  "back_fields": [],
  "locations": [],
  "beacons": [],
  "user_info": {},
  "page_url": "http://get.passworks.io/G1mbmsPWkw",
  "gwallet_usage": false,
  "gwallet_status": nil,
  "gwallet_message": nil,
  "created_at": "2015-04-01T10:06:33Z",
  "updated_at": "2015-04-01T10:06:33Z"
}

Presentation fields (when template_id is not supplied)

Field name Type Description
icon_id uuid Required. Icon id (the id of a icon type asset)
logo_id uuid Optional. Logo image id (the id of a logo type asset)
strip_id uuid Optional. Strip image id (the id of a logo type asset)
background_id uuid Optional. Strip image id (the id of a background type asset)
thumbnail_id uuid Optional. Strip image id (the id of a logo type asset)
logo_text string Optional. Top card text
background_color rgb string Optional. Color defining the pass background color ranging from #00000 to #ffffff
text_color rgb string Optional. The text color for all the value fields except primary_fields, ranging from #00000 to #ffffff
label_color rgb string Optional. The text color for all label fields except primary_fields, ranging from #00000 to #ffffff
barcode hash Optional. A single hash of barcode hash object.

Available fields

Field name Type Description
name string Required. Must be unique, it's used to identify the Event Ticket "Campaign"
description string Optional. Brief description of the pass, used by the iOS accessibility technologies. If the description is not provided the name field value is used instead.
transit_type string Required. Must be one of the following values air, boat, train, boat or generic
template_id uuid Optional. If not supplied, you must supply the presentation fields presented in the table above!
header_fields array Optional. Collection of field hash objects
secondary_fields array Optional. Collection of field hash objects
auxiliary_fields array Optional. Collection of field hash objects
back_fields array Optional. Collection of field hash objects used in the rear part of the pass
locations array Optional. Collection of up to 10 location hash objects
beacons array Optional. Collection of up to 10 beacon hash objects
certificate_id uuid Optional. You should provide your own certificate but in none is provided the passworks.io default certificate is used.
organization_name string Optional. Organization name showned in the unlock screen, if none is supplied the registration organization name is used
associated_store_identifiers array Optional. A list of iTunes Store item identifiers for the associated apps. Only one item in the list is used - the first item identifier for an app compatible with the current device. If the app is not installed, the link opens the App Store and shows the app. If the app is already installed, the link launches the app, as specified in passbook's documentation
og Boolean Use Open Graph tags on the download page. Optional, default: true
og_description String Open Graph description. Optional, default: "" (empty string)
javascript String Javascript that will be rendered inside the download page and form, Allows the user to run their own javascript code eg: Google Analytics or Facebook Pixel
stylesheet String CSS that will be rendered inside the download page and form, allows users to override the page css
user_info hash Optional. This field can be used to store user related data. On Apple Wallet this field will be available as a JSON encoded string.
remote_form_url url Optional. Please see advanced features.

Field hash object format

{
  "key": "name",
  "value": "2 weeks",
  "label": "EXPIRES",
  "behaviour": "fixed"
}
Field name Type Description
key string Required. A reference key, it must be unique for a campaign.
value string Required. The field's value
label string Required. The field's label
behaviour string Optional, Options: fixed or dynamic. When not set, use fixed as default

Understanding behaviour fields (fixed vs dynamic content)

The presentation fields (primary_fields, secondary_fields, auxiliary_fields and back_fields) have a behaviour attribute. This attribute can have one of two values: fixed or dynamic (by default the behaviour is set to fixed).

  • fixed

    fixed means that the value is static: every pass will have the same label and value for this field. So when you call the merge method in the Ruby client this field will be added or overriden (if the field with the same key exists) in every pass even if you had previously customized the value per pass. Don't use the type of field for custom fields in your passes eg: name, client id, ticket number ,etc. This type of behaviour is a good fit for fields that are the same across all passes eg: event date, event location, flight number, etc.

  • dynamic

    The dynamic behaviour defines the field as a custom updated field that shouldn't be updated on a bulk update when the merge method is called. This field will only be updated when the user updates that field specifically for that pass. This type of behaviour is a good fit for custom fields like ticket number, user name, boarding number, seat number, etc..

Location hash object format

{
	"altitude": 0.0,
	"latitude": 0.0,
	"longitude": 0.0,
	"relevant_text": "notification to display"
}
Field name Type Description
altitude double Optional. Altitude, in meters, of the location.
latitude double Required. Latitude, in degrees, of the location.
longitude double Required. Longitude, in degrees, of the location.
relevant_text string Optional. Text displayed on the lock screen when the pass is currently relevant. For example, a description of the nearby location such as “Store nearby on 1st and Main.”

Beacon hash object format

{
	"major": 0.0,
	"minor": 0.0,
	"proximity_uuid": "30b5d792-48c9-4f12-80ff-082cae62e80f",
	"relevant_text": "notification to display"
}
Field name Type Description
major 16-bit unsigned integer Optional. Major identifier of a Bluetooth Low Energy location beacon
minor 16-bit unsigned integer Optional. Minor identifier of a Bluetooth Low Energy location beacon
proximity_uuid string Required. Unique identifier of a Bluetooth Low Energy location beacon
relevant_text string Optional. Text displayed on the lock screen when the pass is currently relevant. For example, a description of the nearby

Barcode hash object format

{
	"alt_text": "Text shown below the barcode.",
	"format": "pdf417",
	"message": "Message encoded in the barcode."
}
Field name Type Description Default
alt_text string Optional. Text shown below the barcode. Pass's redeem code.
format string Optional. Must be one of the following if supplied: qrcode, pdf417, aztec, ean128 or none. qrcode
message string Optional. Message encoded in the barcode. Pass's redeem code.

Updating the "Skyport Airways" flight 815 Campaign

Let's imagine that the gate of the flight changed, and you wish to update all of the campaign's passes. To do so, you will need to issue a PATCH to the following URL with this example payload:

PATCH /v2/boarding_passes/{campaign_id}
{
	"boarding_pass": {
	    "header_fields": [
      {
        "label": "GATE",
        "key": "gate",
        "value": "A3"
      }
    ]
	}
}

Response:

{
  "id": "485d2a26-efc5-4f85-8855-fa2f4b6cd2e2",
  "name": "Skyport Airways flight 815",
  "template_id": "492d648f-559b-482f-a3c2-2a43aa194aed",
  "organization_name": "foobar",
  "barcode": {
    "format": "qrcode",
    "message": "",
    "alt_text": ""
  },
  "allow_multiple_redeems": false,
  "header_fields": [
    {
      "key": "gate",
      "value": "A3",
      "label": "GATE"
    }
  ],
  "primary_fields": [
    {
      "key": "depart",
      "value": "SFO",
      "label": "SAN FRANCISCO"
    },
    {
      "key": "arrive",
      "value": "JFK",
      "label": "NEW YORK"
    }
  ],
  "secondary_fields": [
    {
      "key": "passenger",
      "value": null,
      "label": "PASSENGER"
    }
  ],
  "auxiliary_fields": [
    {
      "key": "boardingTime",
      "value": null,
      "label": "DEPART"
    },
    {
      "key": "flightNewName",
      "value": "815",
      "label": "FLIGHT"
    },
    {
      "key": "class",
      "value": null,
      "label": "DESIG."
    },
    {
      "key": "date",
      "value": "7/22",
      "label": "DATE"
    }
  ],
  "back_fields": [],
  "locations": [],
  "beacons": [],
  "user_info": {},
  "page_url": "http://get.passworks.io/G1mbmsPWkw",
  "created_at": "2015-04-01T10:06:33Z",
  "updated_at": "2015-04-01T10:18:15Z"
}

Now that you've updated your campaign, all the future passes generated from this updated campaign will contain the new changes.

NOTE: The following instructions will reset all the issued passes to the base template, removing the personalization fields from all the issued passes.

The correct way of updating the already issued passes while preserving the custom fields (like the name of the pass owner, for example) is to iterate trough the issued pass collection, by collecting the ids from GET /v2/boarding_passes/{campaign_id}/passes

and then updating each pass with the fields you wish to change.

Please contact [email protected] for advisement on updating a boarding pass campaign.

If, however any old passes that had already been generated and you wish to reset them to the new changes, you must, following a campaign update, issue a push POST request:

POST /v2/boarding_passes/{campaign_id}/push

Along with this push, you may also, optionally, send in a payload with a push message that will be presented to the users when the update is done, shown on the lock screen.

{
	"boarding_pass": {
	    "push_message": "Gate has changed!"
	}
}

Response:

You'll get a contextualized message, informing on the start of the pass updates, or that there are no passes to be updated.

{
	"message": "There are no passes to update for campaing 'Skyport Airways flight 815'."
}
Field name Type Description Default
push_message string Optional. Text shown on the lock screen. No message sent.

This request will push all existing passes once again, guaranteeing that all that have been downloaded will contain the new changes. Otherwise, there's no guarantee that the users will receive the updated pass.

Creating a Boarding Pass for "John Appleseed"

You can create a boilerplate pass simply by POSTing to the passes route:

POST /v2/boarding_passes/{campaign_id}/passes

If you want to personalize the pass you can supply an hash with the parameters you want to override:

POST /v2/boarding_passes/{campaign_id}/passes

Request payload:

{
  "pass": {
    "secondary_fields": [
      {
        "key": "passenger",
        "value": "John Appleseed"
      }
    ],
    "auxiliary_fields": [
      {
        "key": "boardingTime",
        "value": "2:25 PM"
      },
      {
        "key": "class",
        "value": "Coach"
      }
    ]
  }
}

Response:

{
  "id": "7d131a35-66df-4fc2-9d78-b5373558ffd9",
  "campaign_id": "485d2a26-efc5-4f85-8855-fa2f4b6cd2e2",
  "voided": false,
  "serial_number": "51950d75-5d4a-48fc-a187-2f4d5a577ae2",
  "redeem_code": "0000001",
  "redeemed_count": 0,
  "barcode": {
    "format": "qrcode",
    "message": "0000001",
    "alt_text": "0000001"
  },
  "expiration_date": null,
  "max_distance": null,
  "relevant_date": null,
  "header_fields": [
    {
      "key": "gate",
      "value": "A3",
      "label": "GATE"
    }
  ],
  "primary_fields": [
    {
      "key": "depart",
      "value": "SFO",
      "label": "SAN FRANCISCO"
    },
    {
      "key": "arrive",
      "value": "JFK",
      "label": "NEW YORK"
    }
  ],
  "secondary_fields": [
    {
      "key": "passenger",
      "value": "John Appleseed",
      "label": "PASSENGER"
    }
  ],
  "auxiliary_fields": [
    {
      "key": "boardingTime",
      "value": "2:25 PM",
      "label": "DEPART"
    },
    {
      "key": "flightNewName",
      "value": "815",
      "label": "FLIGHT"
    },
    {
      "key": "class",
      "value": "Coach",
      "label": "DESIG."
    },
    {
      "key": "date",
      "value": "7/22",
      "label": "DATE"
    }
  ],
  "back_fields": [],
  "locations": [],
  "beacons": [],
  "user_info": {},
  "page_url": "http://get.passworks.io/G1mbmsPWkw/ajcAj0bCaN4LxN3FjcHn2Q",
  "pkpass_url": "http://get.passworks.io/G1mbmsPWkw/ajcAj0bCaN4LxN3FjcHn2Q.pkpass",
  "created_at": "2015-04-01T10:29:34Z",
  "updated_at": "2015-04-01T10:29:34Z"
}

Updating the Boarding Pass of John Appleseed

As mentioned before, updating a specific pass ensures that the personalization you defined at pass creation, will be preserved, unless, of course, you specifically overwrite those fields.

POST /v2/boarding_passes/{campaign_id}/passes/{pass_id}

Request payload:

{
  "pass": {
    "auxiliary_fields": [
      {
        "key": "boardingTime",
        "value": "3:25 PM"
      }
    ]
  }
}

Response:

{
  "id": "7d131a35-66df-4fc2-9d78-b5373558ffd9",
  "campaign_id": "485d2a26-efc5-4f85-8855-fa2f4b6cd2e2",
  "voided": false,
  "serial_number": "51950d75-5d4a-48fc-a187-2f4d5a577ae2",
  "redeem_code": "0000001",
  "redeemed_count": 0,
  "barcode": {
    "format": "qrcode",
    "message": "0000001",
    "alt_text": "0000001"
  },
  "expiration_date": null,
  "max_distance": null,
  "relevant_date": null,
  "header_fields": [
    {
      "key": "gate",
      "value": "A3",
      "label": "GATE"
    }
  ],
  "primary_fields": [
    {
      "key": "depart",
      "value": "SFO",
      "label": "SAN FRANCISCO"
    },
    {
      "key": "arrive",
      "value": "JFK",
      "label": "NEW YORK"
    }
  ],
  "secondary_fields": [
    {
      "key": "passenger",
      "value": "John Appleseed",
      "label": "PASSENGER"
    }
  ],
  "auxiliary_fields": [
    {
      "key": "boardingTime",
      "value": "3:25 PM",
      "label": "DEPART"
    },
    {
      "key": "flightNewName",
      "value": "815",
      "label": "FLIGHT"
    },
    {
      "key": "class",
      "value": "Coach",
      "label": "DESIG."
    },
    {
      "key": "date",
      "value": "7/22",
      "label": "DATE"
    }
  ],
  "back_fields": [],
  "locations": [],
  "beacons": [],
  "user_info": {},
  "page_url": "http://get.passworks.io/G1mbmsPWkw/ajcAj0bCaN4LxN3FjcHn2Q",
  "pkpass_url": "http://get.passworks.io/G1mbmsPWkw/ajcAj0bCaN4LxN3FjcHn2Q.pkpass",
  "created_at": "2015-04-01T10:29:34Z",
  "updated_at": "2015-04-01T10:30:41Z"
}

Sending a push notification (or forcing a pass update)

You can force the retrieval of a pass via push notification by simply calling the following URL:

POST /v2/event_tickets/{campaign_id}/passes/{pass_id}/push

You can also send a custom message that will be displayed in the lock screen via push notification sending the following content in the above request

{
	"pass": {
		"push_message": "Boarding time changed."
	}
}

Response:

You'll get a contextualized message, informing on the start of the pass update, or that there are no passes to be updated.

{
	"message": "push notifications sent for pass with id: 7d131a35-66df-4fc2-9d78-b5373558ffd9 on campaign 'Skyport Airways flight 815'"
}

Redeeming a pass

There are two ways you can redeem a pass:

  • Redeeming a pass by referencing a redeem code You can redeem a pass by referencing a redeem code (instead of the pass_id) by POSTing to the campaign redeem route

     /v2/boarding_passes/{campaign_id}/redeem

    Issuing a payload with a root element pass and with the redeem code in the payload:

     {
 	"pass": {
 		"redeem_code": "0000001",
 		"comment": "Redeemed in store"
 	}
 }

    The method accepts an optional comment key where you can specify some information you want to be stored for reference.

  • Redeem a pass directly You can redeem a pass directly, by POSTing to the pass redeem route:

     POST /v2/boarding_passes/{campaign_id}/passes/{pass_id}/redeem

    You can supply an optional comment key where you can specify some information you want to be stored for reference:

     {
 	"pass": {
 		"comment": "redeemed in store"
 	}
 }

Reseting a redeem

If your pass was flagged as "void" you can reset the flag calling the "reset_redeem" endpoint

POST /v2/coupons/{campaign_id}/passes/{pass_id}/reset_redeem

Aditional routes available

Get all the Boarding Pass campaigns:

GET /v2/boarding_passes/

Delete a Boarding Pass campaign

DELETE /v2/boarding_passes/{campaign_id}

In case of success a HTTP 200 status code is returned with empty error list. n

{
  "errors": []
}

In case of a error a HTTP 412 (Precondition Failed) status code is returned with a array of errors.

{
  "errors": {
    "campaign": "Campaign not found."
  }
}

Changing campaign state via PAUSE, RESUME, ARCHIVE

You can pause, resume and archive campaigns using the following endpoints:

Pausing a campaign disables the ability to issue more passes and changes the campaign state to "paused".

POST /v2/boarding_passes/{campaign_id}/pause

Resuming a campaign re-enables the issuing of new passes, changes the campaign state to "published" again.

POST /v2/boarding_passes/{campaign_id}/resume

Archiving stops the issuing of new passes and and hides the campaign from the interface without deleting the campaign. It changes the campaign state to "archived".

POST /v2/boarding_passes/{campaign_id}/archive

If the campaign state is changed successfully the endpoints return a 200 HTTP status code.

In case of a error a HTTP 412 (Precondition Failed) is returned with a error message, eg:

{
  "errors": [
    "Can't resume from archived to publish"
  ]
}

Get all the passes for a specific Boarding Pass campaign:

GET /v2/boarding_passes/{campaign_id}/passes

Get a pass's id from its redeem code

GET /v2/boarding_passes/{campaign_id}/redeem/{redeem_code}

Reports

GET /v2/boarding_passes/{campaign_id}/reports
GET /v2/boarding_passes/{campaign_id}/reports/totals

For more information about the reports, please check our Reports Documentation.