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

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

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>

Sign in

Resources