XX (Development)

ct.soa-gw.canadapost.ca

XX (Production)

soa-gw.canadapost.ca

{mailed by customer}

your customer number

{mobo}

the mailed on behalf of customer number or repeat your customer number

Accept

application/vnd.cpc.authreturn-v2+xml (Note: */* in place of the header value will return an error)

Content-Type

application/vnd.cpc.authreturn-v2+xml (Note: */* in place of the header value will return an error)

Authorization

Basic {Base64 encoding of userid:password}

Accept-language

en-CA or fr-CA

authorized-return

Complex

Required

This is the overall XML structure for the request input information. This structure provides a description of the return request details, including receiver, service-code, returner, parcel-characteristics and references.

create-public-key

Simple

Optional

{true}
If flag is present and set to “true”, it will enable a generation of public URL to retrieve a PDF version of shipping label and inclusion of this URL along with expiry date in service response. That functionality can be leveraged if shipper prefers to send customer a link to the label rather than a label as attachment. Also, shipper can send to customer QR code encoding public URL, that would allow customer to use QR code for printing out label in any CPC retail location. Expiry date indicates when such link to retrieve the label will no longer be accessible.

create-qr-code

Simple

(true|false)
If flag is present and set to “true”, AND create-public-key is also true, the QR code encoding of the public URL is automatically generated and returned in the response.

customer-barcode

Simple

Optional

(16 alphanumeric)
Value of the barcode.
If present, the barcode will be rendered in the customer info area of the authorized return label (usually at the bottom).

customer-barcode-type

Simple

Optional

(LINEAR|2D)
Type of the barcode. Mandatory if customer-barcode is specified.

service-code

Simple

Required

(Character string – up to 32 alphanumeric)

Return labels can only be created if the shipment originates in Canada and is destined for delivery in Canada.

This is the Canada Post delivery service used for shipping the item.

returner

Complex

Required

This structure contains data about the sender that will appear in the “From” address of the label. Blank fields will be removed in the address formatting.

name

Simple

Required

(44 alphanumeric)
Contact name of the corresponding returner.

company

Simple

Optional

(44 alphanumeric)
Company name of the corresponding returner.

domestic-address

Complex

Required

This structure contains the address data about the returner of the shipment. Blank fields will be removed in address fields for formatting the labels.

address-line-1

Simple

Required

(44 alphanumeric)

address-line-2

Simple

Optional

(44 alphanumeric)

city

Simple

Required

(40 alphanumeric)

province

Simple

Required

(2 characters)

postal-code

Simple

Required

(6-digit code in Canadian Postal Code pattern: A9A9A9)

receiver

Complex

Required

This structure contains data about the destination and will appear in the “To” address of the label. Blank fields will be removed in the address formatting.

name

Simple

Required

(44 alphanumeric)
Contact name of the corresponding receiver.

company

Simple

Optional

(44 alphanumeric)
Company name of the corresponding receiver.

email

Simple

Optional

(60 characters - must be a valid email pattern)
For future use.

receiver-voice-number

Simple

Optional

(Character String – up to 25 characters)
Phone number of the receiver.
Will not appear on shipping label.

domestic-address

Complex

Required

Required if the corresponding parent XML element “receiver” exists.
This structure contains the address data about the receiver of the shipment. Blank fields will be removed in address fields for formatting the labels.

address-line-1

Simple

Required

(44 alphanumeric).

address-line-2

Simple

Optional

(44 alphanumeric)

city

Simple

Required

(40 alphanumeric)

province

Simple

Required

(2 characters)

postal-code

Simple

Required

(6-digit code in Canadian Postal Code pattern: A9A9A9)

parcel-characteristics

Complex

Optional

This structure contains the information about the physical characteristics of the parcel.

weight

Simple

Optional

(Numeric field of pattern 3.3 e.g. 999.999)
Total package weight in kg.

dimensions

Complex

Optional

This structure contains information specifying the dimensions of a parcel.

length

Simple

Conditionally
Required

(Numeric field of pattern 3.1 e.g. 999.9 pattern)
Required if the corresponding parent XML element “dimensions” exists.
Length of parcel in cm.
If length is specified, a more accurate price can be derived.

width

Simple

Conditionally
Required

(Numeric field of pattern 3.1 e.g. 999.9 pattern)
Required if the corresponding parent XML element “dimensions” exists.
Width of parcel in cm.
If width is specified, a more accurate price can be derived.

height

Simple

Conditionally
Required

(Numeric field of pattern 3.1 e.g. 999.9 pattern)
Required if the corresponding parent XML element “dimensions” exists.
Height of parcel in cm.
If height is specified, a more accurate price can be derived.

print-preferences

Complex

Optional

This structure contains print preferences for the labels.

output-format

Simple

Optional

(7 alphanumeric)
Valid values are:
- 8.5x11
- 4x6
If this element is not present, 8.5x11 is the default.

encoding

Simple

Optional

{PDF, ZPL}

Use this field to specify the output format for your return label: PDF or ZPL II. If not provided, PDF will be selected by default.

If you choose ZPL, the response from a Get Artifact call will include a file containing ZPL II printer commands. You will then need to either code a solution or use an application to stream the commands directly to a thermal printer.

For ZPL II labels, your printer must support truncation. Use our sample code to test your printer’s ability to truncate text.

ZPL is only available on thermal paper. The <output-format> must therefore be 4x6.

show-packing-instructions

Simple

Optional

{true, false} Defaults to True
This element indicates whether packing instructions are to be rendered on the label.

settlement-info

Complex

Required

This structure is analogous to the structure from Create Shipment; however, here the contents are optional and recommended to be omitted.

paid-by-customer

Simple

Optional

(10-digit numeric)

For future use.

contract-id

Simple

Optional

(10-digit numeric)

For future use.

references

Complex

Optional

This structure contains reference fields that you can assign. These alternate (possibly unique) identification numbers are assigned to the return, and can be used for tracking or for any other purpose you deem useful.

customer-ref-1

Simple

Optional

(Character string – up to 35 characters)
This is a user-defined value available for use by your applications. The value you enter here will appear on the shipping label, in Track and – for customers who subscribe to our Automated Parcel Tracking service – in your APT file.

customer-ref-2

Simple

Optional

(Character string- up to 35 characters)
This is a user-defined value available for use by your applications. The value you enter here will appear on the shipping label, in Track and – for customers who subscribe to our Automated Parcel Tracking service – in your APT file.

notifications

Complex

Optional

This structure holds email notification settings for receiving parcel tracking information.

notification

Complex

Mandatory

If the notifications structure is present, at least one notification instance is required and up to 4 are allowed. This structure holds one email address and the kinds of notifications to be sent to the email address.

email

Simple

Mandatory

(Email string up to 60 characters)

Email address to receive automatic tracking updates.

Must be a valid email address, i.e., pattern of (['_A-Za-z0-9\-\+])(\.['_A-Za-z0-9\-\+])@([A-Za-z0-9-])(\.[A-Za-z0-9-])(\.[A-Za-z]{2,})

If the notification structure is present, the email address element must be provided.

on-shipment

Simple

Mandatory

{true, false}

If the notification structure is present, this element must be provided. If set to “true”, all shipment related tracking updates will be sent to the email addressed.

on-exception

Simple

Mandatory

{true, false}

If the notification structure is present, this element must be provided. If set to “true”, all exception related tracking updates will be sent to the email addressed.

on-delivery

Simple

Mandatory

{true, false}

If the notification structure is present, this element must be provided. If set to “true”, all delivery related tracking updates will be sent to the email addressed.

email-subject

Simple

Optional

{tracking,customer-ref-1,customer-ref-2}

Email subject lines have the following general forms depending on type of notification:

• Ship Notification for Item / Avis d’expédition pour l’article :
• Exception Notification for Item / Avis d’exception pour l’article :
• Delivery Notification for Item / Avis de livraison pour l’article :

The value following the colon defaults to “TRACKING” and the Canada Post tracking number. Or you can set it to “REFERENCE” and one of the customer reference numbers.

authorized-return

Complex

This is the top level XML element for the response.
This is the XML structure that contains the information about the created authorized return.

public-key-info

Complex

This structure represents data pertaining to label public URL – the URL to retrieve a PDF version of shipping label along with expiry date of the URL.

expiry-date

Simple

The expiry date of label public URL.

url

Simple

Actual URL to retrieve PDF version of the label in format
http://est.canadapost.ca/esto/app/bypass/label?key={generated_key}

qr-code

Simple

The Base64 encoding of the actual image of the QR code that represents the public URL (if create-qr-code and create-public-key are both present in the request and set to true).

tracking-pin

Simple

This is the tracking PIN for the shipment. The tracking PIN can be used as input to other web service calls such as Get Tracking Details.

customer-barcode

Simple

The barcode value that is specified in the request (if provided).

links

Complex

This structure represents a list of links to information relating to the shipment that was created.

return-link

Complex

The links structure contains a single return-link element.
e.g.

<link href=”https://XX/ers/artifact/12346789/9876554/01
rel=”returnLabel" index=”1”
media-type=”application/png”/>

This link contains no sub-elements and has three attributes as follows:

1. href. String. This is the endpoint that can be used to call the Get Artifact service to retrieve the label for the authorized return just created.

2. rel. String. In the generic use of the link element, this indicates the purpose of the link and the type of information that will be retrieved. In the case of this service, there will only be a single return-link element, and it will have a rel=“returnLabel” value indicating that href can be used to call Get Artifact to retrieve the return label. There are no other types of links associated with this service.

3. media-type. The media-type attribute indicates the format of the graphics file (e.g. PDF or ZPL).

Note: After you create an authorized return, you have five calendar days to retrieve the return label before the link expires.

9191

ZPL is a language for thermal printers. You can therefore only use it with 4x6 thermal paper.

9192

3x5 return labels are not available anymore. Please use 4x6 on thermal printers.

9208

Public labels are only available in 8.5x11 PDF format.