Returns
Get Open Return Template Details – REST
Summary
| Name: | Get Open Return Template Details |
|---|---|
| Reason to Call: | To retrieve an XML representation of all of the initial information related to an existing open return template. This includes the final return destination address details. This service would not typically be called during normal operations as it is not required to retrieve or print labels. It is provided for situations such as a recovery from a communications or other error. |
| Input: | None – the endpoint href is a direct link to calling this service for a specific open return template. |
| Output: | The details that were input at the time that the open return template was created including:
|
| Version history: | Release notes |
Get Open Return Template Details – Summary of Service
Request Details
Request – Structure for Get Open Return Template Details
Endpoint
Invoke the link returned from a prior call to Create Open Return Template or Get Open Return Template where the value of the attribute “rel” is “details”.
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 Template Details does not require any input XML data.
Response Details
The following table describes the XML fields in the response. For a detailed view of the hierarchy of the response, see the XML diagram.
| Get Open Return Template Details – Response Elements | ||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|
| Element Name | Type | Description | ||||||||||
template-details |
Simple |
This is the top level XML structure for the response. |
||||||||||
max-number-of-artifacts |
Simple |
Indicates the maximum number of artifacts (return labels) you can generate and retrieve using this template. Must be numeric in the range of 1 - 100,000. |
||||||||||
artifacts-remaining |
Simple |
Indicates the current remaining number of artifacts (return labels) allowed to be generated and retrieved using this template. |
||||||||||
service-code |
Simple |
The returns service is appropriate for domestic returns only.
|
||||||||||
receiver |
Complex |
This structure contains data about the final destination. This data appears in the “To” address of the return label. Blank fields will have been removed during address formatting. |
||||||||||
name |
Simple |
The name of the receiver |
||||||||||
company |
Simple |
The company of the receiver |
||||||||||
domestic-address |
Complex |
This structure contains the address data about the final receiver of the return shipment. |
||||||||||
address-line-1 |
Simple |
Address line 1 of the receiver. |
||||||||||
address-line-2 |
Simple |
Address line 2 of the receiver. |
||||||||||
city |
Simple |
City of receiver. |
||||||||||
prov |
Simple |
Province of the receiver. |
||||||||||
postal-code |
Simple |
Postal Code of the receiver |
||||||||||
print-preferences |
Complex |
This structure contains print preferences for the labels, such as output format. |
||||||||||
output-format |
Simple |
Valid values are: |
||||||||||
encoding |
Simple |
{PDF} |
||||||||||
show-packing-instructions |
Simple |
{true, false} |
||||||||||
settlement-info |
Complex |
This structure contains the elements that indicate how the delivery will be settled (paid for). |
||||||||||
contract-id |
Simple |
Required to use the Open Returns service. Only Canada Post commercial customers with a volume-based agreement can use the service. |
||||||||||
Response – XML Diagram
The following diagram shows the XML structure of the response from Get Open Return Template Details.
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 MXL Request – Get Open Return Template Details
GET https://XX/PROVIDED LINK
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 or Get Open Return Template.
Sample REST XML Response – Get Open Return Template Details
<open-return-details>
<artifacts-remaining>10</artifacts-remaining>
<open-return>
<max-number-of-artifacts>10</max-number-of-artifacts>
<service-code>DOM.EP</service-code>
<receiver>
<domestic-address>
<address-line-1>23 jardin private</address-line-1>
<city>Ottawa</city>
<province>ON</province>
<postal-code>K1K4T3</postal-code>
</domestic-address>
</receiver>
<print-preferences>
<output-format>8.5x11</output-format>
<encoding>PDF</encoding>
<show-packing-instructions>false</show-packing-instructions>
</print-preferences>
<settlement-info>
<contract-id>0012345678</contract-id>
</settlement-info>
</open-return>
</open-return-details>
