Contract Shipping

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

Get Groups – REST

Summary

Name: Get Groups
Reason to Call:

To confirm the full list of groups eligible for use in a Transmit Shipments request.

Input:

Mailed-by customer and behalf-of-customer numbers.

Output:

List of group ids and a link to get links for shipments in each group.

Error Example:

404 – not found if behalf-of customer is incorrect

Typical Next Call: Transmit Shipments, Get Shipments
Version history: Release notes
Get Groups – Summary of Service

Get Groups – Summary of Service

Request Details

Request – Structure for Get Groups

Endpoint

GET https://XX/rs/{mailed by customer}/{mobo}/group

Replace... With...

XX (Development)

ct.soa-gw.canadapost.ca

XX (Production)

soa-gw.canadapost.ca

{mailed by customer}

your customer number

{mobo}

the mailed on behalf of customer number or repeat your customer number

HTTP Headers

HTTP Header Variable

Value

Accept

application/vnd.cpc.shipment-v8+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

The Get Groups service does not require any input XML data.

Response Details

Response – Elements

The following table describes the XML data in the response.

For a detailed view of the hierarchy of the response, see Response – XML Diagram.

Get Groups – Detailed View of Response Elements
Element Name Type Description

groups

Complex

This is the top level of the response structure.

group

Complex

Contained within groups.

May occur 0 … N times.

This element represents a single shipping group within the domain of the mailed-on-behalf-of customer.

group-id

Simple

(Character String – up to 32 characters)

Contained within group.

This is the name of the group specified by your system in a prior Create Shipment call.  Groups may be empty of shipments due to a prior Transmit Shipments call since they can persist for up to 24 hours while empty.

Performance limitations
To avoid a timeout of our servers, please follow these recommendations:

  • Do not include more than 30 groups per manifest (i.e., maximum of 30 group-ids in one Transmit Shipments request.)
  • Do not put more than 5,000 shipments in one group.

System limitations
To avoid an error, please do not exceed the following limits before performing a Transmit Shipments call:

  • Maximum of 50 groups per manifest (error 9109 if exceeded).
  • Maximum of 10,000 shipments in one group (error 9110 if exceeded).
  • Maximum of 10,000 shipments across multiple groups (error 9108 if exceeded).

link

Complex

Contained within group.

For a description of link attributes, see Provided endpoints.

See Get Shipments for information about this link. The group id is automatically provided as a query string in each link.

Response – XML Diagram

The following diagram shows the top level response to the Get Groups service.

Get Groups - Structure of XML Response

Get Groups – Structure of XML Response

Note: the attribute "index" in the link element (in the diagram above) is not used in the Get Groups service.

Response – Possible Error Responses

This response will follow the XML format described in HTTP status codes.

Possible error messages for this service include the following.

Code Message

AA003

The customer number in the URL does not belong to the web service authorization provided in your request.

404

Not found (meaning the behalf-of customer specified is incorrect or has no groups)

Examples

Sample REST XML Request – Get Groups

Call this service using a mailed-by customer number and a mailed-on-behalf-of customer number (mobo). In the following example, customer number=1234567 and mobo=123456789

GET https://XX/rs/1234567/123456789/group
Accept:application/vnd.cpc.shipment-v8+xml
Authorization:Basic 23426ffw34%3fssdf==

Sample REST XML Response – Get Groups

<groups>
<group>
<link rel="group" href="https://XX/rs/111111111/222222222/shipment?groupid=123456" media-type="application/vnd.cpc.shipment-v8+xml"></link>
<group-id>123456</group-id>
</group>
</groups>