Print

Returns

Code Samples for Returns: Java (.zip) | PHP (.zip) | C# (.zip)

Get Open Return Templates – REST

Summary

Name: Get Open Return Templates
Reason to Call:

Used to retrieve a list of all active open return templates associated with your application (by mailed-by and mailed-on-behalf of (MOBO) customer numbers).

Note: As your application should maintain the list of active open return templates, this service is not typically called during routine operation. Rather, it is used to recover from a communications or other error.
Input:

There is no XML input to this service.
However, the mailed by and mailed-on-behalf-of customer numbers are required and must be embedded in the href endpoint of this service. This must be done by your application when invoking this service. For more information, see Request Details.
Output: A list of links that point to the active open return templates associated with the mailed by / mailed-on-behalf-of customer.
Typical Next Call: Get Open Return Template to access a specific open return template on the list.
Version history: Release notes
Get Open Return Templates – Summary of Service

Get Open Return Templates – Summary of Service

Request Details

Request – Structure for Get Open Return Templates

Endpoint

GET https://XX/rs/{mailed by customer}/{mobo}/openreturn?from=YYYYMMDD&to=YYYYMMDD
Replace... With...

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

YYYYMMDD

the from and to dates (year, month, day)
Note: If the "from" date is missing, all active open return templates prior to the "to" date are returned. If the "to" date is missing, the end date is assumed to be the current date. If both dates are missing, all open return templates are returned.

HTTP Headers

HTTP Header Variable

Value

Accept

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

Content-Type

application/vnd.cpc.openreturn+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

Body

None

Request – Elements

Get Open Return Templates does not require any input XML data.

Response Details

Response – Elements

The following table describes the XML fields in the response. For a detailed view of the hierarchy of the response, see the XML diagram.

Element Name Type Description
templates Complex

This is the top level XML element for the response.
This structure contains a set of return elements.
link Complex

The link structure contains one template link for each active template.
e.g. <link
href="https://XX/rs/123456/24680/openreturn/3434343434
rel="template"
media-type="application/vnd.cpc.openreturn"/>

Each link has three attributes as follows.

  1. href. String. This is the endpoint that can be called using an https GET to retrieve the information.

  1. rel. String. This indicates the purpose of the link and the type of information that will be retrieved – in this case all of the links will have rel="template".

  1. media-type. The media-type attribute indicates the format of the graphics file (PDF).

Response – XML Diagram

The following diagram shows the XML structure of the response from the Get Open Return Templates service.

Get Open Return Templates – Structure of the XML Response

Get Open Return Templates – Structure of the XML Response

Response – Possible Error Responses

In the case of an application error, an HTTP 400 level status code error response will be generated and the XML body will have an error message structure rather than the success response. For more information, see HTTP status codes.

Possible error messages for this service include the following:

HTTP Status Code Application Error Message
500 N/A Detailed schema validation error is provided.
412 9999

Examples

Sample REST XML Request – Get Open Return Templates

GET https://XX/rs/12345678/3434343434343/openreturn/
from=20110623&to=20110719
Accept:application/vnd.cpc.openreturn+xml
Authorization:Basic s7HD7gwsennesc==

Note: Do not hard-code the HTTP endpoint link. The link is provided as an output from Create Open Return Template.

Sample REST XML Response – Get Open Return Templates

<templates>
<linkrel="template"href="https://ct.soa-gw.canadapost.ca/rs/0007023211/0007023211/openreturn/349641323786705649"media-type="application/vnd.cpc.openreturn+xml"></link>
</templates>