SOAP Fundamentals of Canada Post Web Services

Canada Post services allow e-commerce solution providers and online merchants to integrate Canada Post services, such as shipping, rating and tracking data, into a platform or website. Once integrated, your application will access Canada Post servers over SOAP 1.1 protocol.

View typical use case scenarios.

Before beginning integration work

1. Read Getting Started to find out how to sign up and get your API keys.
2. Review the information included here in SOAP Fundamentals of Canada Post Services. It details essential information common to all our services.
3. Run our sample application to test your access to our services and observe the data sent to (and returned by) our web services.
4. Read the detailed functional and technical descriptions for each of our web services in the Service Directory.

Using SOAP to interact with web services

The general format for any Canada Post SOAP web service interface is illustrated below. For details by call see the Service Directory.

Namespaces

A SOAP envelope always specifies:

• the namespace of the SOAP message definition itself
• the namespace of the particular interface being invoked

The namespace of the interfaces are different for different service categories and will be unique to the particular version of the interface you’re invoking. Please note the following about the namespace:

• The namespace attributes of the envelope are of the form xmlns:prefix="URI"
• "prefix" is used subsequently in the message as a reference to the namespace
• "URI" is not necessarily an addressable URL. Retrieve the WSDL resources rather than attempting to use the URI.
• When a namespace has been explicitly referenced, all child elements of the tag that declares the namespace are assumed to be in the same namespace. Frequently the top level tag will specify the namespace prefix and subsequent tags will not have a namespace reference.

Example

Header (Security)

Canada Post web service requests require Web Services security with UsernameToken in which your username and password are specified. Many utilities including soapUI will construct the XML header for you if you provide the username and password attributes. The header is empty in the SOAP response.

Body

The first tag after the envelope body element is the top level XML element of the request or response. See the detailed call reference pages for details on how to format the elements for each request and how to interpret the elements for each response.

Asynchronous multi-part calls

Many of the web services are asynchronous and return some information immediately while a background task is being completed. For example:

1. You make a shipping label request.
2. Information related to the PDF label is returned before the label rendering is complete.
3. The shipping label id from the response is used as input to a second request to retrieve the PDF label.
4. The second request returns a message error structure until the PDF label is available.

Call patterns

Calls can either be executed in repeating pairs or triples or there can be repetition of one call with results stored in your application followed by repetition of the second part. See Ad hoc and batch call patterns. There are a series of searches or synchronization/recovery calls available if a thin client is being developed. These calls are always in a plural form such as Get Shipments.

Error Handling

An HTTP code 200 will be returned for fully successful transactions or those that were schema valid but with application validation issues.

The response XML must be checked to see which branch of the response has been returned – either the complete success message (response) or the partial success (messages) branch. See the diagram below for a general portrayal of the two branches. In general, if the <messages> element exists, the rest of the message should be processed by your application error message logic. If the <messages> element does not exist, process the response information by your success logic.

Status 200 Errors based on presence of <messages> element at 2nd level of response

HTTP Status Code	Code	Comments
200
	4 digit codes	Application errors are 4 digits long. For details about specific messages, see Error messages and mitigation strategies. System errors are 3 digits long as below.
	202	The requested resource is not yet available. Please try again later. For example, after a Create Non-Contract Shipment request, a delay of approximately one second is required before you can retrieve the shipping label with a Get Artifact call.
	404	Either the requested information is not yet ready (try again later) or no longer available. (New label requests are rendered asynchronously and old requests are deleted after 90 days.)

Serious errors such as authentication failures or schema validation errors will result in HTTP error code 500. A SOAP fault will be returned. The <faultcode> for authentication issues will be unique for the type of error. Schema validation errors will have a generic <faultcode> of "Server". In both cases the <faultstring> will provide diagnostic information for you, the developer, to be able to correct the problem before your application goes live.

Status 500 Errors based on <SOAP-ENV:Fault> element immediately after <SOAP-ENV:Body>

HTTP Status Code	faultcode	Comments
500
	AA001	The user id for the request has been deactivated. If you withdrew from the Developer Program, rejoin the program.
	AA002	The user id and password of the request does not match the end-point. E.g. development key against production endpoint or vice versa.
	AA003	The API key in the "Authorization" header does not match the mailed-by customer number in the request.
	AA004	You cannot mail on behalf of the requested customer.
	Server	Details of the schema error are described in the faultstring.
	env:Client	The endpoint is incorrectly specified – correct and resubmit.

Web service environments

Two web service environments are available to you:

• Sandbox (development) – used for testing your code.
• Production – used in your production environment.

Select the web service environment by using:

• Your development or production username / password credentials, and
• The corresponding development or production endpoint.

Note: faultcode AA002 will be returned if you use the wrong credentials for the endpoint selected.

Sandbox (development) environment

Use your development key against the sandbox environment. The sandbox environment is a replica of production and includes valid test data and responses, with the exception of the following:

Item	Appears in Response From	Response Values in the Sandbox Environment
tracking-pin element	Create Shipment Get Shipment Details	123456789012
return-tracking-pin element	Create Shipment	123456789012
po-number element	Create Shipment Get Shipment Details Get Manifest Details Get Manifest	P123456789
Artifacts, such as shipping labels, return labels and manifests	Get Artifact	Labels and manifests are clearly identified as “for testing purposes only” and therefore cannot be used for actual shipping.
Tracking web services	Get Tracking Summary Get Tracking Details Get Signature Image Get Delivery Confirmation Certificate	Regardless of the tracking number you submit in the request to tracking web services, the response “No Pin History” is returned. To test a full set of tracking scenarios, use production tracking PINs in the production environment. (To test “not found” use an invalid PIN.)
public-key-info url element	Create Authorized Return	Viewing the label in the browser requires a set of valid API keys. Google Chrome might not display the label full-screen, due to a known bug with the browser.

Sandbox endpoints

The endpoints for the sandbox environment are in the code samples, and the example soapUI project maps to the sandbox environment by default: "https://ct.soa-gw.canadapost.ca"

Test values for contract shipping, rating and returns

If you are not a commercial customer of Canada Post with a contract, but you are developing a third-party shipping solution intended for commercial customers, use the numbers below for testing contract shipping, rating, and returns web services. Please note the following:

• These numbers are only valid in the sandbox environment.
• You must be a Solutions for Small Business™ customer to use these test numbers. Join now.
• Several Canada Post customers will be using the same test numbers. To avoid confusion, make sure you create your own group-ids when you create your shipments. Read more about group-ids.
• We have set up a default test credit card under this test customer to allow you to test credit card transactions.
• To obtain commercial test rates, in your request to Get Rates, you must include both the customer-number and the contract-id.
• Rates returned are for test purposes only.

Element name/key	Text values for sandbox environment
Customer-number	2004381
Contract-id	42708517
API key	6e93d53968881714:0bfa9fcb9853d1f51ee57a

Test value for promo codes

Promotion Code DEVPROTEST can be used to test promo code functionality in the sandbox environment. This promo code is only valid in the sandbox environment and for the following products:

• Xpresspost (DOM.XP)
• Xpresspost International (INT.XP)

Production environment

After your application has been tested successfully against the sandbox environment, you can change your API key to the production key and change the endpoints to production endpoints.

Test the endpoints that do not incur a charge first, such as those in Rating, Tracking and Find a Post Office. If you create shipments as a test, to avoid incurring a charge, call Void Shipment for these test shipments before calling Transmit Shipments.

Production endpoints

The endpoints for the production environment are the same as for the sandbox but without the "ct." – "https://soa-gw.canadapost.ca"

ZPL II thermal labels – truncation requirement

If you are printing thermal shipping labels in ZPL II format, your printer must have the ability to truncate text. Without this ability, you risk printing over top of important information on Canada Post shipping labels. Check your printer to make sure it can truncate text. Citizen printers, for example, as well as Zebra printers with older firmware, do not support truncation. You can test your printer using our sample code below.

Sample code to stream to your thermal printer

Copy and paste the code below into the utility provided by your printer manufacturer and print this to a thermal label.

^XA
^CI13
^MMT
^PW812
^LL1218
^LS0
^FO63,63^A0N,25,20^FDThe text below should not spill out of the box^FS
^FO127,127^A0N,25,20^TBN,190,25^FDthistextshouldnotspilloutofthebox^FS
^FO121,121^GB197,32,1^FS
^PQ1,0,1,Y
^XZ

Printer results

If your printer supports truncation, the printout will be a box with the truncated text appearing within the box, as shown below:

If your printer does not support truncation, the text will spill outside the box as shown below:

If your printer does not support truncation, we recommend you use PDF format for labels instead. See the encoding element for more details: REST | SOAP.

Versioning

Please refer to our Versioning Strategy page.

Using WSDL 1.1 files

Many tools take WSDL 1.1 files as input. The WSDL files were input into code generation utilities as a starting point for the Java and .NET code samples. The PHP utility SoapClient uses WSDL files at runtime. The soapUI examples were generated based on the WSDLs as a starting point.

The Canada Post web service functionality is captured in 11 different WSDL files. Each WSDL file contains one or more web service operations.

How WSDL files are used