Voucher Structure

Voucher structure is not an API call, but it’s included as a part of APITUDE for Activities documentation to help understanding how to build a voucher including barcodes, specific images or any other requirement needed to build a voucher that enables the final customer to enjoy an activity. 

Some api calls can return a voucher list in their response (confirm and modify calls) and some of that vouchers can contain the voucher structure additionally or instead of the vouchers in PDF or HTML. 

When a voucher URL in XML or JSON is provided, you have the choice to;-

  • Build your own voucher with the information included in the XML or JSON message returned by the provided URL*
  • Directly download/forward the voucher URL to final customers;

*In case we send you in the response a voucher URL, it is mandatory to show that voucher. Also you can send the client your own, so they'll end up with 2.

 

The following table (also shown in the booking detail specifications) explains when it’s possible to build your own voucher and when you must deliver the generated voucher to your final customer:

Format

Deliver to the final customer

Build your own voucher

Both PDF/HTML and XML/JSON

Yes

No

Only XML and/or JSON

No

Yes

Here is the sample of voucher URL which will be returned in Booking Confirm response.  

"vouchers": [
                    {
                        "dateFrom": "2017-11-20",
                        "dateTo": "2017-11-20",
                        "code": "PQFY9R0W3Q",
                        "language": "CAS",
                        "url": "https://integrations.activitiesbank.com/vouser/rest/voucher/get/PQFY9R0W3Q",
                        "mimeType": "text/html"
                    },
                    {
                        "dateFrom": "2017-11-20",
                        "dateTo": "2017-11-20",
                        "code": "CIQOL4XH8X",
                        "language": "CAS",
                        "url": "https://integrations.activitiesbank.com/vouser/rest/voucher/get/CIQOL4XH8X",
                        "mimeType": "application/pdf"
                    },
                    {
                        "dateFrom": "2017-11-20",
                        "dateTo": "2017-11-20",
                        "code": "CJ8SE11GTF",
                        "language": "ENG",
                        "url": "https://integrations.activitiesbank.com/vouser/rest/voucher/get/CJ8SE11GTF",
                        "mimeType": "text/html"
                    },
                    {
                        "dateFrom": "2017-11-20",
                        "dateTo": "2017-11-20",
                        "code": "T32NJMIKQF",
                        "language": "ENG",
                        "url": "https://integrations.activitiesbank.com/vouser/rest/voucher/get/T32NJMIKQF",
                        "mimeType": "application/pdf"
                    }
                ],

The following is an example of a voucher structure returned in API response by using provided URL to call in API with GET method: 

{
  "numberOfItemsPerPage": 1,
  "itemsPerPax": true,
  "pageSize": "A4",
  "distribution": "VERTICAL",
  "creationDate": "Wed Mar 23 17:36:11 CET 2016",
  "pages": [{
    "id": 0,
    "vouchers": [{
      "id": 0,
      "paxId": "1",
      "barcodes": [{
        "height": 150,
        "heightUnits": "PX",
        "barWidth": 1.0,
        "orientation": 90,
        "position": "TOP,RIGHT",
        "pageId": 0,
        "encodedMessage": "",
        "encoding": "EAN13",
        "url": "http://tab.test.service/barser/rest/generateBarcode//BARCODE/4/1.0/150/PIXEL/72/P/PNG",
        "mandatory": true,
        "orderId": 0
      }, {
        "height": 150,
        "heightUnits": "PX",
        "barWidth": 1.0,
        "orientation": 90,
        "position": "BOTTOM,RIGHT",
        "pageId": 0,
        "encodedMessage": "",
        "encoding": "EAN13",
        "url": "http://vouchers.com/barser/rest/generateBarcode//BARCODE/4/1.0/150/PIXEL/72/P/PNG",
        "mandatory": true,
        "orderId": 0
      }],
      "images": [],
      "fields": [{
        "label": "Booking_Reference",
        "value": "43-1929660",
        "pageId": 0,
        "orderId": 1,
        "type": "STRING"
      }, {
        "label": "Name",
        "value": "John Smith",
        "pageId": 0,
        "orderId": 2,
        "type": "STRING"
      }, {
        "label": "Date From",
        "value": "16/02/2016",
        "pageId": 0,
        "orderId": 3,
        "type": "DATETIME"
      }, {
        "label": "Modality",
        "value": "General admission",
        "pageId": 0,
        "orderId": 4,
        "type": "STRING"
      }, {
        "label": "Adults",
        "value": "1",
        "pageId": 0,
        "orderId": 5,
        "type": "STRING"
      }, {
        "label": "Chilren",
        "value": "0",
        "pageId": 0,
        "orderId": 6,
        "type": "STRING"
      }]
    }]
  }]
}

The example below describes a vouchers in a single page containing:

  • Two barcodes of 150 pixels height and the already build image for the barcodes (provided in a URL for each one). They need to be placed at the top, right and bottom, right in the voucher.
  • 6 fields that are mandatory to be shown and their values including the booking reference, holder name and number of adults and children.
  • No specific images or logos are required by the supplier. 

The structure of a voucher in XML or JSON is explained below: 

Voucher Structure

NODE/ATTRIBUTE

TYPE

DESCRIPTION

numberOfItemsPerPage

Integer

Number of vouchers that can be present on each printed page

itemsPerPax

Boolean

  • True: Each passenger in the activity has to have an individual voucher.
  • False: Only one voucher is needed for all the paxes in the booking.

pageSize 

String

Size of each page of the voucher, this follows the standard ISO-216 i.e: A4

distribution 

String

A set of pages is returned in the “pages” attribute. The “distribution” attribute explains if the pages are in portrait or landscape.

The following are the valid values:

  • VERTICAL: Portrait
  • HORIZONTAL: Landscape

creationDate

Date

When the voucher was created

pages 

List<Page>

A list of pages, each page should be created as a separate page in the voucher file.

page/@id 

Integer

Page identifier.

This is an auto incremented integer to differentiate one page from the other.

page/vouchers

List<Voucher>

List of vouchers, if voucher has all the information for one passenger in the booking.

If the attribute itemsPerPax is false, you should only receive one voucher in this list.

page/vouchers/@id

Integer

Voucher identifier.

This is an auto incremented integer to differentiate one voucher from the other.

page/vouchers/@paxId

Integer

Passenger identifier in the activity.

  • If the attribute itemsPerPax is true, this will identify for which passenger is this voucher.
  • If the attribute itemsPerPax is false, this should be null.

page/barcodes 

List<Barcode>

List of barcodes that should be present in the voucher.

page/vouchers/barcodes/@height 

Double

Height of the barcode image.

The units in which this height is returned is given in a separate attribute heightUnits

page/vouchers/barcodes/@heightUnits 

String

Units in which the height is returned

page/vouchers/barcodes/@barWidth 

Double

Width of the thinnest bar of the barcode.

This attribute is always returned in pixels.

page/vouchers/barcodes/@orientation 

Integer

Orientation in degrees of the barcode.

  • 0 means the barcode has to be placed horizontally.
  • 90 means the barcode has to be placed vertically.

page/vouchers/barcodes/@position 

String

Each page can contain more than one voucher and in a voucher more than one barcode or QR Code can be returned.

The “position" attribute explains where the code needs to be positioned in the voucher to fulfill the supplier requirements.

The following values can be returned:

 

  • TOP
  • MIDDLE
  • BOTTOM
  • LEFT
  • RIGHT

A combination of those elements is also possible. i.e: “TOP,RIGHT”.

page/vouchers/barcodes/@pageId 

Integer

Page identifier that indicates the page this barcode belongs to.

It will match one of the page/@id values returned in this same response.

page/vouchers/barcodes/@encodedMessage

String

Message encoded in the barcode. The contents of this attribute will be the exact value used to create the barcode. Typically it will be the barcode number, but it can be any value.

This value will be useful if, instead of using the provided url to get the image, you choose to create the barcode in your end.

In that case, the message you will have to use to generate the voucher will be the value of this attribute.

page/vouchers/barcodes/@encoding

String

Encoding type for the barcode.

It can be any of the values detailed in the list you can find here.

You will need this attribute in combination with page/vouchers/barcodes/@encodedMessage in case you prefer to generate the barcode image in your side.

It is mandatory that the generated barcode has this encoding.

page/vouchers/barcodes/@url

String

Image representing this barcode. You can use this image instead of generating your own if you prefer to do so.

page/vouchers/barcodes/@mandatory

Boolean

Indicates if this barcode must be present in the voucher. Normally, if its mandatory it will be because you customer can gain access to the activity by placing this barcode in some reader.

page/vouchers/barcodes/@orderId

Integer

If the barcodes we return must have some kind of order, it will be an incremental order using this attribute.

page/vouchers/fields

List<Field>

List of text, dates or other values that you will need to render a valid voucher

page/vouchers/fields@label

String

Label that must precede this value

page/vouchers/fields@value

String

Value of the field, will be displayed after the label.

page/vouchers/fields@pageId

Integer

Page identifier this field belongs to. It will match the attribute page@id of the page.

page/vouchers/fields@orderId

Integer

If the fields must follow any kind of order, it will be an incremental ordering using the value in this field.

page/vouchers/fields@type

String

Data type of this field. It can be:

  • STRING
  • DATE
  • NUMBER

 

page/vouchers/images

List<Image>

List of images that can be displayed in the voucher.

Aside from the images you choose to display, it could happen that, in order to enjoy the activity, the voucher must show a set of images. If that is the case, you will receive the images in this list.

page/vouchers/images/@width

Integer

Width of the image.

The unit this attribute will be returned in the page/vouchers/images/@widthUnits attribute.

page/vouchers/images/@height

Integer

Height of the image.

The unit this attribute will be returned in the page/vouchers/images/@heightUnits attribute.

page/vouchers/images/@widthUnits

String

Units the attribute page/vouchers/images/@width was returned in.

page/vouchers/images/@heightUnits

String

Units the attribute page/vouchers/images/@height was returned in

page/vouchers/images/@orientation

Integer

Orientation in degrees of this image.

  • 0 means the barcode has to be placed horizontally.
  • 90 means the barcode has to be placed vertically.

page/vouchers/images/@position

String

Phisical position where the image has to be placed in the voucher area.

It can be:

 

  • TOP
  • MIDDLE
  • BOTTOM
  • LEFT
  • RIGHT

Or any combination that makes sense of those elements.

For example: “TOP,RIGHT”.

page/vouchers/images/@pageId

Integer

Page id of the page this image belongs to.

It will match the value of page/@id attribute

page/vouchers/images/@url

String

Fully qualified URL of this image.

page/vouchers/images/@orderId

Integer

If the images returned in this list must have any order, it will be an incremental sorting using the value of this field.

Docs Navigation