Accessing the Canada Post Sell Online API using curl

Accessing the Canada Post Sell Online API using curl

By devin, 23 September, 2014

I've been trying to access the Canada Post Sell Online API (if it's even still called that, in 2014) and I'm having lots of trouble. I'm using an Ubercart module (uc_canadapost) and it doesn't seem to work or something. It looks like you used to get a Merchant ID when you used Sell Online, and with Canada Post's new APIs you get a username and password as your API key.

It took me a good 2 hours to figure out how to successfully use curl to access the REST API. I'm now going to document the examples of successful curl commands that have actually worked.

First, go to https://www.canadapost.ca/cpotools/apps/drc/registered?execution=e4s1 and get your API Key. I'm using my development API key, which is broken into a username field and a password field, separated by a colon. I tried using the -H flag to curl to send the Basic Authorization header, which didn't work. I must have done it wrong. It was much easier (and more successful) to use the -u flag for the authentication bit.

This page https://www.canadapost.ca/cpo/mc/business/productsservices/developers/s… was a bunch of helpful information sandwiched between useless information. The relevant bit was that you can't just find a URL and send an HTTP GET and get your response. There are mandatory and optional HTTP headers, which I'm reproducing here:

HTTP Header Variable Applicable Methods Mandatory / Optional Value Description

Authorization

GET, POST, DELETE

Mandatory

Basic userid:password

  • The word "Basic" is a literal value that must be present.
  • A single space follows the word Basic.
  • The API key follows the space as a single Base64-encoded string (52 characters).
  • The encoded string is generated from the API key (a concatenation of the userid, a colon and the password)
  • For an example of a utility that can generate the Base64-encoded string from your userid and password parts, see Test Tools .

Content-Type

POST

Mandatory

Unique per service group. See service documentation for details.

This is the XML version of the body you are sending in the POST.

( Note: */* in place of the header value will return an error)

Accept

GET

Mandatory

Unique per service group. See service documentation for details or use "media-type" from the provided link.

This is the XML version of the response that you are expecting to receive.

( Note: */* in place of the header value will return an error)

Accept-Language

GET, POST

Optional

"fr-CA" or "en-CA"

This indicates the preferred language of the human readable error message (if error is generated).

If-None-Match

GET

Optional

As per Etag value from original response.

May be included in request if a prior "GET" was cached. Either "304 – not changed" will be returned or the new version of the resource will be returned.

So for a HTTP GET, you need the Authorization header and the Accept header.

Let's try this for a simple query. There is a list of queries here: http://www.canadapost.ca/cpo/mc/business/productsservices/developers/se…

Here's how I did that for a simple query to GET a list of services (documentation for this call is here: http://www.canadapost.ca/cpo/mc/business/productsservices/developers/se…).

curl -u "edc2833333333335:dc167444444444444444a3" -H "Accept: application/vnd.cpc.ship.rate-v3+xml" 'https://ct.soa-gw.canadapost.ca/rs/ship/service?country=CA'

This was the magic. I used my development API Key (you can see I've obscured most of it with 3s and 4s) and I sent the request to the development version of the URL (ct.soa-gw.canadapost.ca instead of just soa-gw.canadapost.ca). I got this response back:

 

<?xml version="1.0" encoding="UTF-8"?>

	<services xmlns="http://www.canadapost.ca/ws/ship/rate-v3">

	<service><service-code>DOM.EP</service-code><service-name>Expedited Parcel</service-name><link rel="service" href="https://ct.soa-gw.canadapost.ca/rs/ship/service/DOM.EP?country=CA" media-type="application/vnd.cpc.ship.rate-v3+xml"/></service>

	<service><service-code>DOM.RP</service-code><service-name>Regular Parcel</service-name><link rel="service" href="https://ct.soa-gw.canadapost.ca/rs/ship/service/DOM.RP?country=CA" media-type="application/vnd.cpc.ship.rate-v3+xml"/></service>

	<service><service-code>DOM.PC</service-code><service-name>Priority</service-name><link rel="service" href="https://ct.soa-gw.canadapost.ca/rs/ship/service/DOM.PC?country=CA" media-type="application/vnd.cpc.ship.rate-v3+xml"/></service>

	<service><service-code>DOM.XP</service-code><service-name>Xpresspost</service-name><link rel="service" href="https://ct.soa-gw.canadapost.ca/rs/ship/service/DOM.XP?country=CA" media-type="application/vnd.cpc.ship.rate-v3+xml"/></service>

	</services>

Plain text

  • No HTML tags allowed.
  • Web page addresses and email addresses turn into links automatically.
  • Lines and paragraphs break automatically.