Web Service Requirements for Return Authorization Numbers – REST
Introduction
When creating a parcel return policy, you have the option to request that your customers enter a return authorization number to retrieve a label. You can use one static number, or provide us with a URL address to a web service that you host where your list of unique authorization numbers is housed.
When you create your parcel return policy in My Returns on the Canada Post website, if you select the web service option, you will be prompted to enter the URL, username and password for your web service. This document describes the requirements for the web service.
Implementation
Your web service should be implemented using standard REST-style architecture.
We will call your web service to validate the return authorization number entered by your customers before we allow them to retrieve a return label. The web service must return either a pass or fail. If the authorization fails, we will not allow your customers to retrieve a return label.
The username and password required to access your endpoint will be included in the HTTP authorization header. Your web service will use this information to authenticate our call to your service.
Please note that your web service must include the authorization number 99999999999999 (i.e., 14 9s), which should always return an indication of a valid number. This will allow Canada Post to ping your web service to determine that it is operational.
Successful Completion
If your web service completes its actions successfully for the input data provided, you will return a 200-level HTTP code and respond with the output data contained within a top-level XML element.
Web Service Summary
Name: | Validate RSA |
Reason to Call: | To validate the return authorization number provided by a consumer. The service must also include a “ping” capability to indicate it is up and running. |
Input: | The authorization number to be validated. Optional parameters are the date the return authorization number was issued and additional information specified in the policy. |
Output: | A validity flag indicating whether the authorization number is valid. |
Request Details
Endpoint
POST https://<your endpoint>/ValidateRsaNumber
HTTP Headers
HTTP Header Variable | Value |
---|---|
Accept | application/vnd.canadapost.rest+xml |
Content-Type | application/vnd.canadapost.rest+xml |
Authorization | Basic {Base64 encoding of userid:password} |
Accept-language | en-CA |
Body
The body should have a top-level XML element “ValidateRsa” as described below.
Request Elements
Element Name | Usage | Description |
---|---|---|
ValidateRsa | Required | The top level XML element for the request input information. |
RsaNumber | Required | Contained within ValidateRsa Return shipping authorization number that the customer provided to retrieve a return label 1-15 alphanumeric or special characters Special ping value “99999999999999” must always return ValidationStatus = true |
RsaNumberIssueDate | Optional | Contained within ValidateRsa (For future use) Date on which the RSA number was issued to the customer Format: YYYY-MM-DD |
AdditionalInfo | Optional | Contained within ValidateRsa (For future use) Up to 20 characters Additional information specified in the policy that the customer needs to provide (e.g., invoice number, item number, reference number etc.) |
Response Elements
Element Name | Usage | Description |
---|---|---|
ValidateRsaResponse | Required | The top level XML element for the request input information. |
ValidationStatus | Required | Contained within ValidateRsaResponse Boolean false – RsaNumber not valid true – RsaNumber valid |
Error Condition
An error condition occurs when a user is not authorized to call your web service or your service is not able to complete successfully.
In case of an error condition, your web service should return an HTTP 400-level or 500-level status code. Depending on the HTTP status code, you can also provide a top-level XML element and associated structure for error codes and messages in the response body.
Please note that you will return either the normal output data (under a top level XML element, as appropriate) or the error XML structure, or neither (depending on the nature of the error).
Examples
Sample REST Request
GET https://<yourendpoint>/ValidateRsa/99999999999999?
AdditionalInfo=PO123-45678-XY&RsaNumberIssueDate=2012-09-22 HTTP/1.1
Sample REST - XML Response
HTTP/1.1 200 Good
Content-Type: application/canadapost.rsa+xml
<?xml version=”1.0” encoding=”UTF-8”?>
<ns1:ValidateRsaResponse xmlns:ns1=”http://www.canadapost.ca/webservices/validatersa”>
<ValidationStatus>true</ValidationStatus>
</ns1:ValidateRsaResponse>
Sample REST - XML Response to an error condition
HTTP/1.1 500 Error
Content-Type: application/canadapost.rsa+xml
<?xml version=”1.0” encoding=”UTF-8”?>
<ns2:Messages xmlns:ns2=”http://www.canadapost.ca/webservices/messages”>
<Message>
<Code>8304</Code>
<Description>Sample error</Description>
</Message>
</ns2:Messages>
Sample REST - JSON Response
HTTP/1.1 200 Good
Content-Type: application/candapost.rsa+json
{
"ValidateRsaResponse":{
"ValidationStatus":true
}
}
Sample REST - JSON Response to an error condition
HTTP/1.1 500 Error
Content-Type: application/canadapost.rsa+json
{
"Messages":[
{
"Code":"8304",
"Description":"Sampleerror"
}
]
}