Rating

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

Discover Services – REST

Summary

Name: Discover Services
Reason to Call: To discover the list of postal services that can be used for a given destination country, customer, contract, origin and/or destination postal code.
Input: Destination Country
Output: Service links and descriptions
Version history: Release notes
Discover Services – Summary of Service

Discover Services – Summary of Service

Request Details

Request – Structure for Discover Services

Endpoint

GET https://XX/rs/ship/service?country={country code}&contract={contract-id}&origpc={origin-postal-code}&destpc={destination-postal-code}

Replace... With...

XX (Development)

ct.soa-gw.canadapost.ca

XX (Production)

soa-gw.canadapost.ca

{country code}

the desired 2-character country code

{contract-id} The Canada Post contract number

HTTP Headers

HTTP Header Variable

Value

Accept

application/vnd.cpc.ship.rate-v3+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

Query String

If no search parameters are provided, all domestic, U.S. and international services accessible without a contract will be listed. The following parameters can be provided in the request to refine the response.

Query Parameter Optional or required Description

country

optional

If the country-code is provided, only services suitable for sending items to the provided country will be returned.

contract optional If the contract-id is provided, the response will also include restricted services accessible with that contract

Request – Elements

The Discover Services service 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 diagram below.

Element Name Type Description

services

complex

The list of services that can be used for the specified query parameters.

service

complex

Contains details for a service.

service-code

simple

The code used to request the service.

service-name

simple

The name of the service in the requested language.

link

simple

Link for Get Service. (See Provided endpoints)

Response – XML Diagram

The following diagram shows the high level response. Either the services structure (a valid response) or the messages structure (error response) will be returned.

Diagram of XML Response to Discover Services

Diagram of XML Response to Discover Services

Response – Possible Error Responses

The messages below could be returned for incorrect query parameter values.

Code Description

2550

The contract number is not valid.

7266 Postal Code must be in format A9A or A9A9A9.
8534 A valid destination country must be supplied.
9194 origin-postal-code must also be provided when destination-postal-code is provided.

See HTTP status codes for general error handling information.

Examples

Sample REST XML Request – Discover Services

Get https://XX/rs/ship/service?country=JP
Accept: application/vnd.cpc.ship.rate-v3+xml

Sample REST XML Response – Discover Services

HTTP/1.1 200 OK
Content-Type:application/vnd.cpc.ship.rate-v3+xml

<services>
<service>
<service-code>INT.PW.ENV</service-code>
<service-name>Priority Worldwide envelope INT'L</service-name>
<link rel="service" href="https://XX/rs/ship/service/INT.PW.ENV?country=JP" media-type="application/vnd.cpc.ship.rate-v3+xml"></link>
</service>
<service>
<service-code>INT.PW.PAK</service-code>
<service-name>Priority Worldwide pak INT'L</service-name>
<link rel="service" href="https://XX/rs/ship/service/INT.PW.PAK?country=JP" media-type="application/vnd.cpc.ship.rate-v3+xml"></link>
</service>
<service>
<service-code>INT.PW.PARCEL</service-code>
<service-name>Priority Worldwide parcel INT'L</service-name>
<link rel="service" href="https://XX/rs/ship/service/INT.PW.PARCEL?country=JP" media-type="application/vnd.cpc.ship.rate-v3+xml"></link>
</service>
<service>
<service-code>INT.XP</service-code>
<service-name>Xpresspost International</service-name>
<link rel="service" href="https://XX/rs/ship/service/INT.XP?country=JP" media-type="application/vnd.cpc.ship.rate-v3+xml"></link>
</service>
<service>
<service-code>INT.SP.SURF</service-code>
<service-name>Small Packet International Surface</service-name>
<link rel="service" href="https://XX/rs/ship/service/INT.SP.SURF?country=JP" media-type="application/vnd.cpc.ship.rate-v3+xml"></link>
</service>
<service>
<service-code>INT.SP.AIR</service-code>
<service-name>Small Packet International Air</service-name>
<link rel="service" href="https://XX/rs/ship/service/INT.SP.AIR?country=JP" media-type="application/vnd.cpc.ship.rate-v3+xml"></link>
</service>
</services>