BGS Web Services

BRINKS Global Services

Version 4.0

Contents
Purpose and Scope .................................................................................................................................. 4 1.1. 1.2. 2. 3. Purpose.................................................................................................................................... 4 Scope ....................................................................................................................................... 4

Revision History ............................................................................................................................... 5 General Description ......................................................................................................................... 6 3.1. 3.2. What is Web Service?............................................................................................................... 6 WSDL (Web Service Definition Language) ................................................................................. 6

4.

Web Service: ShipService ................................................................................................................. 6 4.1. Ship Service.............................................................................................................................. 6 WSDL................................................................................................................................ 6 Security (Authentication) .................................................................................................. 6 Account Setup .................................................................................................................. 6

4.1.1. 4.1.2. 4.1.3. 4.2.

Methods: createShipment, preadviseShipment............................................................................ 7 4.2.1. 4.2.2. 4.2.3. 4.2.4. createShipment ................................................................................................................ 7 preadviseShipment........................................................................................................... 7 ShipmentRequest Object .................................................................................................. 7 ShipmentRequest - Data Description ................................................................................ 9

4.3. 4.4. 4.5.

Method: updateShipment .......................................................................................................... 17 Method: cancelShipment ........................................................................................................... 18 Method: getHistoryByBarcode ................................................................................................... 18 4.5.1. 4.5.2. ShipmentHistoryActivity Object ...................................................................................... 18 ShipmentHistoryActivity - Data Description .................................................................... 18

4.6.

Method: getHistorySince ........................................................................................................... 19

BGS Web Services 4.0

Page 2 of36

4.7.

Method: getPODDocument ........................................................................................................ 19 4.7.1. PODDocumentRequest - Data Description ...................................................................... 19

4.8. 4.9. 4.9.1. 5.

Method: getPickupManifest ................................................................................................... 20 Method: getDocument ........................................................................................................... 20 DocumentRequest Data Description ................................................................................ 20

Web Service: RateService............................................................................................................... 20 5.1. Rate Service ........................................................................................................................... 20 WSDL.............................................................................................................................. 20

5.1.1. 5.2. 6.

Method: getRateQuote .......................................................................................................... 21

Web Service: InvoiceService........................................................................................................... 21 6.1. Invoice Service ....................................................................................................................... 21 WSDL.............................................................................................................................. 21

6.1.1. 6.2. 6.3. 6.3.1. 7. 8. 9. 10. 11. 11.1. 11.2. 11.3. 12. 13.

Method: getInvoiceNumbersSince ......................................................................................... 21 Method: getInvoiceNumbersSince ......................................................................................... 21 InvoiceRequest Data Description ..................................................................................... 21

Web Service Client : Java ............................................................................................................... 22 Appendix Service Type ................................................................................................................ 27 Appendix LVP Shipment .............................................................................................................. 27 Appendix Commodity List........................................................................................................ 28 Appendix Customs Code List ................................................................................................... 30 United States-US (Pickup Location)......................................................................................... 30 Germany (Pickup Location)..................................................................................................... 30 Russia (Pickup Location) ......................................................................................................... 31 Appendix Package Type Code List ............................................................................................ 32 Appendix Customs Document Type ......................................................................................... 34

BGS Web Services 4.0

Page 3 of36

14. 15.

Appendix Label Print Option.................................................................................................... 35 Appendix Category Code List ................................................................................................... 36

Purpose and Scope

1.1. Purpose
The purpose of this document is to provide overview on Web Services, and detailed documentation on the Brinks Global Services (BGS) Web Services Version 3.0 operations.

1.2.

Scope

This document explains the ShipService of BGS Web Services and its WSDL.

BGS Web Services 4.0

Page 4 of36

2. Revision History
Revision 1.0 1.1 1.2 Updated On 2012/03/31 2012/07/03 2012/09/05 Update By Ramesh Viswanathan Ramesh Viswanathan Ramesh Viswanathan Description Initial release Added RateService to get rate quote for LVP shipments Added InvoiceService

Changes since version: v3

Added following new service methods: getPickupManifest getDocument Added documenTypes: PNG and PDF in getPODDocument Supports new LVP (Low Value Parcel) service types: o BU: Brinks Pickup to UPS Delivery o UU: UPS Pickup to UPS Delivery o BF: Brinks Pickup to FedEx Delivery o FF: FedEx Pickup to FedEx Delviery Added LVP Options object ShipmentLVPOptionsRequest to ShpimentRequest with the following fields: deliveryTypeId, saturdayDeliveryFlag, residentialDeliveryFlag, signatureTypeId. Added modeOfTransport in ShipmentRequest to indicate the transport mode of the shipment. Added BrokerSelectFlag and Broker Location (information) to ShipmentRequest to support Broker Select Option in BF and FF international shipments. Added AES Number to ShipmentRequest to support US outbound international shipments.

Changes since document revision version: 1.0

Added RateService to get shipment rate quote for US-Domestic LVP shipments.

Changes since document revision version: 1.1

Added InvoiceService.

BGS Web Services 4.0

Page 5 of36

3. General Description
3.1. What is Web Service?
W3Cs Definition: A Web Service is a software system designed to support interoperable machineto-machine interaction over a network. It has an interface described in a machine-processable format (specifically WSDL). Other Systems interact with the Web Service in a manner prescribed by its description using SOAP messages, typically using HTTP with an XML serialization in conjunction with other Web-related standards. Web Services today are frequently just Application Programming Interface (API) or Web API that can be accessed over a network, such as the Internet, and executed on a remote system hosting the requested services.

3.2.

WSDL (Web Service Definition Language)

The mechanics of the message exchange are document in a Web Service Description (WSD). The WSD is a machine-processable specification of the Web Services interface, writing in WSDL (Web Service Definition Language). It defines the message formats, data types, transport protocols, and transport serialization formats that should be used between the request agent and the provider agent. It also specifies one or more network locations at which a provider agent can be invoked. In essence, the service description represents an agreement governing the mechanics of interacting with that service.

4. Web Service: ShipService

4.1. Ship Service

4.1.1. WSDL
Test Environment WSDL of ShipService Web Service is located at:
https://bgs01.brinksglobal.com/wstest3_v4-webservices/ShipServiceBean?wsdl

4.1.2. Security (Authentication)

BGS Web Services are secure. The protocol that is used to invoke the BGS Web Services is https, and every Web Service requires a user authentication (login and password) in order to conduct the business with the Brinks.

4.1.3. Account Setup

In order to access BGS Web Services, it is required to obtain valid username/password from Brinks Global Services, which will create and set up the customers default shipper address and pickup address, user basic profile. These default shipper address and pickup address will be used in the shipment creation only when those are not explicitly specified in the web service call. BGS Web Services 4.0 Page 6 of36

During the createShipment Web Service call invocation, shippers address and pickup address information will be gathered from the logged-in user and the same will be used in every shipment thereafter.

4.2.

Methods: createShipment, preadviseShipment

ShipmentResponse createShipment(Authentication, ShipmentRequest)

4.2.1. createShipment

4.2.2. preadviseShipment
Notification preadviseShipment(Authentication, ShipmentRequest)

4.2.3. ShipmentRequest Object

Shipment Request object contains the shipping elements of Consignee, Delivery Location, Pickup contact information, service type, shippers shipment reference, and one or more shipment items. Every Shipment Request has to have at least one, but not limited to, shipment item(package) to ship with the Web Service. Shipment item is comprised of commodity id, items insurance liability value, items weight and UOM, and a seal number (if any). Supports following more service types: o DD: Door-to-Door o AF: Air Freight o AD: Airport to Door o DA: Door to Airport o AS: Additional Services o BU: Brinks Pickup to UPS Delivery o UU: UPS Pickup to UPS Delivery o BF: Brinks Pickup to FedEx Delivery o FF: FedEx Pickup to FedEx Delviery

Every successful shipment returns a CreateShipmentResponse object which contains a HAWB (House Airway Bill Number) , notification objects for transaction status and shipment item response(s). On a successful shipment creation, the Shipment Response would have a notification code SUCCESS, Shipments HAWB, and shipment items Barcode and base64 encoded shipping label PDF document (includes all of the barcode labels one per page), in the first shipment items image string. On a failure scenario, the Shipment Response would have a notification code ERROR and an appropriate error message in message element of the notification.

BGS Web Services 4.0

Page 7 of36

When a shipment has more than the Brinks pre-approved limits on total Insurance Liability or total Gross Weight, the shipment is turned into a Service Order and it is notified to Brinks operation personnel for approval. Upon approval, the Service Order will be turned into a Shipment for regular processing. On this scenario, the Shipment Response would have notification code as WARNING and Shipment Type is set to Q, and Shipment Status is set to O (Open). For a successful shipment response, the Shipment Status is set to S. HAWB and Barcode: Every shipment has to have a unique Brinks HAWB number to identify the shipment. Every shipment item has to have a unique Brinks Barcode to identify the packages and it is attached to the enclosing HAWB. These HAWB and Barcode(s) are optional while creating a new shipment. However, you are allowed to supply either HAWB or Barcode(s) or both, from the pre-assigned range of HAWB number and/or Barcode. Please contact Brinks Global Services to obtain the pre-assigned range of these numbers.

Example
<ShipmentRequest> <billingType>P</billingType> <pickUpLocation> <contactName>Contact me</contactName> <mobileNumber>987-654-3210</mobileNumber> <phoneNumber>123-456-7890</phoneNumber> </pickUpLocation> <consignee> <address1>618 DELAWARE AVE.</address1> <address2/> <address3/> <address4/> <city>ALBANY</city> <countryCode>US</countryCode> <name>AAA EXPRESS</name> <postalCode>12209</postalCode> <provinceCode/> </consignee> <deliveryLocation> <address1>ZI ROUTE DE CASTELNAUDARY</address1> <address2/> <address3/> <address4/> <city>ALBANY</city> <contactName>John James</contactName> <countryCode>US</countryCode> <mobileNumber>5184261000</mobileNumber> <name>AAA EXPRESS </name> <phoneNumber>5184261000</phoneNumber> <postalCode>12209</postalCode> <provinceCode/> BGS Web Services 4.0 Page 8 of36

</deliveryLocation> <pickupDate>2011/01/31</pickupDate> <pickupTime>15:30</pickupTime> <reference>01820416</reference> <pickupNotes>Please pick up at 3:30PM</pickupNotes> <deliveryNotes>Ask for additional contact Mr.James </deliveryNotes> <shipmentNotes>shipment description goes here </shipmentNotes> <serviceType>DD</serviceType> <modeOfTransportCode>A</ modeOfTransportCode> <requestLabelImage>true</requestLabelImage> <shipmentLabelRequest> <type>PDF</type> <printOption>Laser</printOption> </ShipmentLabelRequest> <shipmentItemRequests> <packageTypeCode>BOX</packageTypeCode> <commodityId>44</commodityId> insuranceLiabilityCurrencyCode>EUR</insuranceLiabilityCurre ncyCode> <insuranceLiabilityValue>11370.00</insuranceLiabilityValue> <sealNumber>00011112</sealNumber> < grossWeight >3.49</ grossWeight > < grossWeightUOM >kgs</ grossWeightUOM > <packageTypeCode>BAG</packageTypeCode> <dimHeight>0.0</dimHeight> <dimLength>0.0</dimLength> <dimUOM/> <dimWidth>0.0</dimWidth> </shipmentItemRequests> </ShipmentRequest>

4.2.4. ShipmentRequest - Data Description

Please the find the below documentation (table) for additional information of the ShipmentRequest on the CreateShipment XML. Element/Field hawbNumber Max. Required Size /Optional 11 Optional/ Required Description Shipments unique Waybill number. Allowed Values WebService returns a barcode if it is empty. P for pre-paid, C for collect Required if it is different from users default shipper

billingType shipper/name

1 40

Required Optional/ Required

To specify the billing charges type Shippers name

BGS Web Services 4.0

Page 9 of36

shipper/address1

30

Optional/ Required Optional Optional Optional/ Optional/ Required Optional/ Required Optional Required

Shippers address line1 Shippers address line2 Shippers address line3 Shippers address line4 Shippers city

Required if shippers name is not empty

shipper/address2 Shipper/address3 Shipper/address4 shipper/city

30 30 30 25

shipper/postalCode

15

Shippers postal code Shippers province code Shippers country code

Required if shippers name is not empty Required if shippers name is not empty

shipper/provinceCode shipper/countryCode

5 3

Required if shippers name is not empty. 2 char codes (Example: FR France, US United States of America, CACanada)

pickUpLocation/name

40

Optional/ Required

Pickup locations name

pickUpLocation/address1

30

Optional/ Required Optional Optional Optional Optional/ Required Optional/ Required

Pickup locations address line1 Pickup locations address line2 Pickup locations address line3 Pickup locations address line4 Pickup locations city Pickup locations postal code

Required if it is different from users default pickup location Required if pickUpLocationN ame is not empty

pickUpLocation/address2 pickUpLocation/address3 pickUpLocation/address4 pickUpLocation/city

30 30 30 25

pickUpLocation/postalCode

15

Required if pickUpLocationN ame is not empty Required if pickUpLocationN ame is not empty

BGS Web Services 4.0

Page 10 of36

pickUpLocation/provinceCode pickUpLocation/countryCode

5 3

Optional Optional/ Required

Pickup locations province code Pickup locations country code

pickUpLocation/contactName

40

Optional/ Required Optional/ Required Optional

Pickup locations

pickUpLocation /phoneNumber

22

Pickup locations phone number Pickup locations mobile number Pickup locations email id

Required if pickUpLocationN ame is not empty . 2 char codes (Example: FR France, US United States of America, CACanada) Required if pickUpLocationN ame is not empty Required if pickUpLocationN ame is not empty

pickUpLocation /mobileNumber pickUpLocation /emailAddress

22

255 Optional

consignee/ globalCustomerCode consignee/name consignee/address1 consignee/address2 consignee/address3 consignee/address4 consignee/city consignee/postalCode consignee/provinceCode consignee/countryCode

20 40 30 30 30 30 25 15 5 3

Optional Required Required Optional Optional Optional Required Required Optional Required

Consignees global customer code Consignees name Consignees address Consignees address Consignees address Consignees address Consignees City Consignees postal code Consignees province code Consignees country code

Can be omitted for now

2 char codes (Example: FR France, US United States of America, CACanada)

BGS Web Services 4.0

Page 11 of36

deliveryLocation/ globalCustomerCode

20

Optional

deliveryLocation/name deliveryLocation/address1 deliveryLocation/ address2 deliveryLocation/ address3 deliveryLocation/ address4 deliveryLocation/city deliveryLocation/postalCode deliveryLocation/provinceCode deliveryLocation/countryCode

40 30 30 30 30 25 15 5 3

Required Required Optional Optional Optional Required Required Optional Required

Delivery locations global customer code Delivery locations Delivery locations address Delivery locations address Delivery locations address Delivery locations address Delivery locations Delivery locations Delivery locations Delivery locations

Can be omitted for now

2 char codes (Example: FR France, US United States of America, CACanada)

deliveryLocation/contactName deliveryLocation/phoneNumber

40 22

Required Required

deliveryLocation/mobileNumber

22

Optional

deliveryLocation/emailAddress serviceType

255 Optional 2 Required

Delivery location contact name Delivery location contacts phone number Delivery location contacts mobile number Delivery contacts email id Shipment service type 3 letter IATA shipment origin airport code. Required for service types: AF, AD

pickupAirportCode

Optional/ Required

Please refer Appendix-Service Type for details Example: DFW (DallasFortworth), LHR (London Heathrow), FRA (Frankfurt)

BGS Web Services 4.0

Page 12 of36

deliveryAirportCode

Optional/ Required

localServiceType

Optional/ Required

modeOfTransportCode

Required

Reference

30

Optional

pickupDate

10

Required

3 letter IATA shipment destination airport code. Required for service types: AF, DA Any local (to the servicing country) service should be populated in this field along with the service type set to AS. A Air, R Road, S Sea, L Rail. Only A is allowed code for all LVP shipment. Customers Shipment reference Shipment pickup date Shipment pickup time in 24 hrs format Shipment delivery date. Shipment delivery time. Request the response to include the base64 encoded Label image (png) string Required when pickup country code is other than US and pickup location name is not empty Special notes for shipment pickup

Example: DFW (DallasFortworth), LHR (London Heathrow), FRA (Frankfurt) Example: RI in Germany for road transport.

pickupTime

Required

deliveryDate

10

Optional

deliveryTime

Optional

requestLabelImage

Required

Allowed Format: YYYY/MM/DD. Ex: 2011/01/31 Allowed format: HH:mm Ex: 10:00, 17:30 Allowed Format: YYYY/MM/DD. Ex: 2011/02/01 Allowed format: HH:mm Ex: 10:00, 17:30 True, False

pickupSiteCode

Optional/ Required

Please request the site code(s) from BGS WebServices support.

pickupNotes

2000 Optional

BGS Web Services 4.0

Page 13 of36

deliveryNotes shipmentNotes requestLabelImage

2000 Optional 2000 Optional Required

Special notes for shipment delivery Shipment notes Request the response to include the base64 encoded Label image (pdf) string Required when requestLabelImage is set to true Required when requestLabelImage is set to true Shipment items unique barcode True/False

ShipmentLabelRequest/labelType

Required /Optional Required /Optional Optional/ Required

PDF

ShipmentLabelRequest/printOption

12

shipmentItemRequest/barcode

15

Please refer Appendix Label Print Option WebService returns a barcode if it is empty in ShipmentItemRe sponse.

shipmentItemRequest/sealNumber

15

Optional

shipmentItemRequest/ insuranceLiabilityCurrencyCode shipmentItemRequest/ insuranceLiabilityValue shipmentItemRequest/ insuranceLiabilityValueInUSD shipmentItemRequest/ commodityId

Required

float Required

Shipment seal number if there is any Shipment items liability currency code Shipment items liability value Shipment items liability value in US Dollars Please refer AppendixCommodity List KGS, LBS

float Optional

19

Required

shipmentItemRequest/ grossWeightUOM

shipmentItemRequest/grossWeight shipmentItemRequest/netWeight

Shipment items unit of measurement for package weight float Required Shipment Items (package) weight float Required Shipment items for commodity weight Internatio in commoditys nal UOM. Shipment 4

Required

Example: If the chosen commodity is Cut & Polished Diamonds then

BGS Web Services 4.0

Page 14 of36

s only

the netWeight should be defined in CTS (carats). Please see the Commodity Appendix for the full list. Shipment Items customs liability currency code

shipmentItemRequest/customsCurrencyCode

shipmentItemRequest/customsValue

shipmentItemRequest/ originCustomsCode

Required for Internatio nal Shipment s only Float Required for Internatio nal Shipment s only 4 Optional/ Required 4

Shipment Items customs liability value

shipmentItemRequest/desitnationCustomsC ode

Optional/ Required

shipmentItemRequest/packageTypeCode

Required

Items Customs code. Required only for International shipments. Items Customs code. Required only for International shipments. Shipment Items package type

Please refer AppendixCustoms Code List Please refer AppendixCustoms Code List Please refer AppendixPackage Type Code List 2 char codes (Example: FR France, US United States of America, CACanada)

shipmentItemRequest/commodityOriginCou ntryCode

Optional

Commoditys manufacturing origin country

shipmentItemRequest/poNumber

45

Optional

shipmentItemRequest/contentQuantity

long Optional

Shipment Items po number for customer reference only. Specifies the number of pieces in the Shipment

Example: 20 (diamond watches in the

BGS Web Services 4.0

Page 15 of36

shipmentItemRequest/dimLength shipmentItemRequest/dimWidth shipmentItemRequest/dimHeight shipmentItemRequest/dimUOM

float Optional float Optional float Optional 2 Optional/ Required

shipmentLVPOptionsRequest/deliveryTypeId

long Required for LVP

Item. Shipment Items dimension length Shipment Items dimension width Shipment Items dimension height Shipment Items UOM for dimension. Required only if dimension is supplied LVP shipment delivery type Need to be set to true when a shipment requires Saturday delivery Need to be set to true if the delivery location is residential

package)

in, cm

shipmentLVPOptionsRequest/saturdayDelive boole Required ryFlag an for LVP

Please refer Appendix-LVP Shipment Please refer Appendix-LVP Shipment Please refer Appendix-LVP Shipment Please refer Appendix-LVP Shipment Please refer AppendixCustoms Document Type List

shipmentLVPOptionsRequest/residentialDeliv boole Required eryFlag an for LVP

shipmentLVPOptionsRequest/signatureTypeI d customsDocumentRequest/documentCode

long Required for LVP 4 Optional/ Required

Can be filled in for international shipment to refer a customs document code customsDocumentRequest/documentNumbe 20 Required Need to be filled in when with the customs r documen document number tCode is when the cusomts populate documentCode is d populated brokerSelectFlag Boole Required Need to be set to an for BF, FF true for broker Internatio customer nal clearance. Shipment Available only for s only BF, FF international shipments. broker/name 40 Optional/ Eligible when Required brokerSelectFlag is BGS Web Services 4.0

Page 16 of36

broker/address1

30

Optional/ Required Optional/ Required Optional/ Required Optional/ Required Optional/ Required Optional/ Required Optional/ Required Optional/ Required Optional/ Required Optional/ Required Optional/ Required

broker/address2

30

broker/address3

30

broker/address4

30

broker/city

25

broker/provinceCode

broker/postalCode

15

broker/countryCode

broker/contactName

40

broker/phoneNumber

22

broker/mobileNumber

22

broker/emailAddress

255 Optional/ Required 15 Optional/ Required

aesNumber

set to true Eligible when brokerSelectFlag is set to true Eligible when brokerSelectFlag is set to true Eligible when brokerSelectFlag is set to true Eligible when brokerSelectFlag is set to true Eligible when brokerSelectFlag is set to true Eligible when brokerSelectFlag is set to true Eligible when brokerSelectFlag is set to true Eligible when brokerSelectFlag is set to true Eligible when brokerSelectFlag is set to true Eligible when brokerSelectFlag is set to true Eligible when brokerSelectFlag is set to true Eligible when brokerSelectFlag is set to true Valid AES Number for US outbound international shipments only.

4.3.

Method: updateShipment

ShipmentResponse updateShipment(Authentication, ShipmentRequest)

BGS Web Services 4.0

Page 17 of36

This method is to update an existing shipment that is created previously using the createShipment method. It takes exactly the same ShipmentRequest and returns ShipmentResponse objects that are used in createShipment. HAWB number is required in the ShipmentRequest object all shipment updates. Shipment items will be updated as per the new ShipmentRequest. Following are the list of possibilities: o Fill in the barcode that is obtained or supplied in createShipment: will update the shipment item. o Fill in new unique barcode or leaving it blank: will add this new shipment item to the shipment. o Omitting the previously added shipment item altogether: will remove the shipment item from the shipment. Cancelled and Locked shipments are not allowed for any updates. A shipment can be in a locked status if one or more of the following occurs: o Shipment gets downloaded into BITS o Shipment gets picked up by BRINKS and a pickup scan performed. o A manual pickup entry on the shipment from BRINKS Invoking updateShipment method on a locked or cancelled shipment will result in error.

4.4.

Method: cancelShipment

Notification cancelShipment(Authentication, hawbNumber)

This method cancels the shipment with the specified HAWB number. Users can only cancel the shipments that are created by the users belong to the same external account. Attempt to cancel a previously cancelled shipment will result it error.

4.5.

Method: getHistoryByBarcode

ShipmentHistoryResponse getHistoryByBarcode(Authentication, barcode)

This method retrieves the shipment history or tracking activities for the specified barcode. Users can retrieve the shipment history for the shipments that are created via Web Services as wells as Brinks automation systems, as long as the barcode is a valid one. It returns the list of activities that are of type PICK, DLVD, HUB, SCANC.

4.5.1. ShipmentHistoryActivity Object

This objects holds a single shipment item history activity for the given shipment item barcode. It includes unique shipment item history activity id, its barcode, type of the activity, and the date and time stamp of the activity when it occurred.

4.5.2. ShipmentHistoryActivity - Data Description

Element/Field Description Possible Values

BGS Web Services 4.0

Page 18 of36

Id barcode activityType

Unique activity id Shipment barcode Type of activity

PICK, DLVD, HUB, SCANC PICK Pickup scan activity DLVD Delivery scan activity HUB Hub Scan activity SCANC Shipment cancellation activity

timeStamp

timestampString

Timestamp of the activity as dateTime type Timestamp of the activity as string type Description of the activity

Data format: YYYY/MM/DD HH:mm. Hours in 24 hours format. Ex: 2011/01/31 20:15, 2011/02/03 09:20,

Detail

4.6.

Method: getHistorySince

ShipmentHistoryResponse getHistorySince(Authentication, sinceDate, sinceTime)

This method retrieves all of the shipment history or tracking activities that are created since the user specified sinceTimeStamp date & time stamp. It will return all of the activities that have activity time stamp that are greater than or equal to the specified since TimeStamp (sinceDate/SinceTime) . If there are no history activities for that period, then it will return a empty result set. It returns the list of activities are of type PICK, DLVD, HUB, SCANC. The date format for sinceDate is YYYY/MM/DD and the format for the sinceTime is HH:mm (24hrs format). It returns a list of Shipment History activities as result set. Please refer previous section for ShipmentHistoryActivity data description.

4.7.

Method: getPODDocument

PODDocumentResponse getPODDocument(Authentication, PODDocumentRequest)

This method retrieves the Proof of Document (POD) for delivery signature if it exists, for any given barcode.

4.7.1. PODDocumentRequest - Data Description

Element/Field barcode documentType Max Size 15 3 Required/Optional Description Possible Values Required Shipment barcode Required Type of POD PNG, PDF document PNG Returns Page 19 of36

BGS Web Services 4.0

the signature image as base64 encoded string PDF Returns the printable POD document as base64 encoded string

4.8.

Method: getPickupManifest

PickupManifestResponse getPickupManifest(Authentication, PickupManifestRequest)

This method returns the PickupManifest as PDF document for the given pickup dates OR todays shipments, when the pickup date is not supplied. Also, a set of shipment HAWB numbers can be supplied to print PickupManifest document only with those shipments. If no HAWB number is supplied, then the PickupManifest will include all the shipments that are qualified for the pickup date. This document is returned as based64 encoded string in the PickupManifestResponse object.

4.9.

Method: getDocument

This method retrieves the HAWB document (printable PDF format) only for international shipments for the given shipment HAWB Number. The document is returned as a base64 encoded string in DocumentResponse object.

4.9.1. DocumentRequest Data Description

Element/Field Max.Size documentName Required/Optional Description Required Name of the document to be obtained Required Shipment HAWB number Unused Reserved for future use Possible Values InternationalHAWB

hawbNumber barcode

11 15

5. Web Service: RateService

5.1. Rate Service

5.1.1. WSDL
Test Environment WSDL of RateService Web Service is located at: BGS Web Services 4.0 Page 20 of36

https://bgs01.brinksglobal.com/wstest3_v4-webservices/RateServiceBean?wsdl

5.2.

Method: getRateQuote

RateQuoteResponse getRateQuote(Authentication, ShipmentRequest)

This method is to get rate quote for a given shipment. It returns the shipment rate in total amount as well as a break down by charge type. It takes the same ShipmentRequest object that is defined in createShipment as one of parameters (along with the authentication) to quote the rate for that shipment. Currently, the service quotes rates for US domestic LVP shipments only.

6. Web Service: InvoiceService

6.1. Invoice Service

6.1.1. WSDL
Test Environment WSDL of InvoiceService Web Service is located at:
https://bgs01.brinksglobal.com/wstest3_v4-webservices/InvoiceServiceBean?wsdl

6.2.

Method: getInvoiceNumbersSince

InvoiceNumbersResponse getInvoiceNumbersSince(Authentication, sinceDate, sinceTime)

This method retrieves all of the invoice numbers that are created since the user specified sinceDate and sinceTime timestamp. It will return all of the invoice numbers that are created on or after the specified timestamp.

6.3.

Method: getInvoice

InvoiceResponse getInvoice(Authentication, InvoiceRequest invoiceRequest)

This method retrieves detailed invoice information that is broken down by shipments and also down to the various charges for each shipment.

6.3.1. InvoiceRequest Data Description

Element/Field invoiceNumber Max.Size Required/Optional Description 20 Required Invoice number for which the details to be obtained includeMAWBNumber boolean Required Specify whether the invoice items to include shipments BGS Web Services 4.0 Possible Values

Page 21 of36

MAWB numbers or not.

InvoiceResponse contains a list of InvoiceItems each representing a shipment that is included in that shipment. And, each shipment contains a list of InvoiceItemCharges each representing a charge line item for that shipment. Sample XML document illustrates the data structure: <invoiceItems> <charges> <amount>25.0</amount> <categoryCode>TRADE</categoryCode> <currencyCode>USD</currencyCode> <description>Security Surcharge</description> </charges> <charges> <amount>75.0</amount> <categoryCode>TRADE</categoryCode> <curreoncyCode>USD</currencyCode> <description>Carnet Fee</description> </charges> <hawbNumber>110412345678/hawbNumber> <insuranceLiabilityValue>151007.0</insuranceLiabilityValue> <mawbNumber>72497617262</mawbNumber> <totalShippingCost>100.0</totalShippingCost> </invoiceItems> Also, each charge line item has a charge categoryCode to indicate the charges category and the complete listing of this category code can be found in Appendix Category Code List

7. Web Service Client : Java

Below is the sample source code of invoking CreateShipment Web Service. Step-1: Generate the Web Service Client module classes using the service definition (WSDL): https://bgs01.brinksglobal.com/wstest3_v4-webservices/ShipServiceBean?wsdl Step-2: Use the below code to populate the request object, invoke the createShipment Web Service and then decode the base64 encoded shipping label image string.
import java.awt.image.BufferedImage; import java.io.*; import java.util.*; import import import import javax.imageio.ImageIO; javax.xml.datatype.DatatypeConfigurationException; javax.xml.datatype.DatatypeConstants; javax.xml.datatype.DatatypeFactory;

BGS Web Services 4.0

Page 22 of36

import org.apache.axis.encoding.Base64; import com.bgs.webservice.ship.*; public class ShipServiceTestClient { public static void main(String[] args) { String localFolder = "/temp/bgs"; File file = new File(localFolder); if (file.isFile()) { System.out.println("Cannot create folder - " + file.getAbsolutePath()); } else if (!file.isDirectory()) { if (file.mkdirs()) { System.out.println("Created folder - " + file.getAbsolutePath()); } } String username = (System.getProperty("username") == null ? "" : System.getProperty("username")); String password = (System.getProperty("password") == null ? "" : System.getProperty("password")); Authentication authentication = createAuthentication(username, password); testCreateShipmentForFRDomestic(authentication); } public static void testCreateShipmentForFRDomestic(Authentication authentication) { ShipmentRequest shipmentRequest = new ShipmentRequest(); shipmentRequest.getPickUpLocation().setContactName("PickUp Contact"); shipmentRequest. getPickUpLocation().setPhoneNumber("111-1231234"); shipmentRequest. getPickUpLocation().setMobileNumber("222-1231234"); Customer consignee = createCustomer("BULL ELEDTRONICS ANGERS", "34, RUE NID DE PIE", "", "", "", "ANGERS", "", "49004", "FR" );

BGS Web Services 4.0

Page 23 of36

Location deliveryLocation = createLocation("BULL ELEDTRONICS ANGERS", "Delivery contact", "34, RUE NID DE PIE", "", "", "", "ANGERS", "", "49004", "FR", "987-123-1234", "987-123-1234" ); shipmentRequest.setConsignee(consignee); shipmentRequest.setDeliveryLocation(deliveryLocation); // set the pickup date and time shipmentRequest.setPickupDate(2011/01/31); ShipmentRequest.setPickupTime(15:00); shipmentRequest.setReference("ref.no:" + today.getTimeInMillis()); shipmentRequest.setPickupNotes(Your pickup notes goes here); shipmentRequest.setDeliveryNotes(Your delivery notes goes here); shipmentRequest.setShipmentNotes(Short description of shipment); // Set the shipment items ShipmentItemRequest shipmentItemRequest = new ShipmentItemRequest(); shipmentItemRequest.setInsuranceLiabilityCurrencyCode("USD"); shipmentItemRequest.setInsuranceLiabilityValue(250000.00); shipmentItemRequest.setInsuranceLiabilityValueInUSD(250000.00); shipmentItemRequest.setWeightUOM("KGS"); shipmentItemRequest.setWeight(1.0); shipmentItemRequest.setCommodityId(5L); shipmentItemRequest.setSealNumber("12345"); List<ShipmentItemRequest> shipmentItemRequests = shipmentRequest.getShipmentItemRequests(); shipmentItemRequests.add(shipmentItemRequest); ShipmentItemRequest shipmentItemRequest2 = new ShipmentItemRequest(); shipmentItemRequest2.setInsuranceLiabilityCurrencyCode("USD"); shipmentItemRequest2.setInsuranceLiabilityValueInUSD(150000.00); shipmentItemRequest.setWeightUOM("KGS"); shipmentItemRequest.setWeight(3.0); shipmentItemRequest.setCommodityId(5L); shipmentItemRequest.setSealNumber("54321"); // shipmentItemRequests.add(shipmentItemRequest2); try { // Get BGS's ShipService Port ShipService shipService = new ShipService();

BGS Web Services 4.0

Page 24 of36

Ship ship = shipService.getShipPort(); // Create a shipment ShipmentResponse shipmentResponse = ship.createShipment(authentication, shipmentRequest); // Save the base64 encoded pdf label to local folder saveLabelsToLocalFolder(shipmentResponse, "/temp/bgs"); } catch (Exception e) { System.err.println(e.getMessage()); } }

private static Authentication createAuthentication(String username, String password) { Authentication authentication = new Authentication(); authentication.setUserName(username); authentication.setPassword(password); return authentication; } private static Customer createCustomer(String name, String address1, String address2, String address3, String address4, String city, String provinceCode, String postalCode, String countryCode) { Customer customer = new Customer(); customer.setName(name); customer.setAddress1(address1); customer.setAddress2(address2); customer.setAddress3(address3); customer.setAddress4(address4); customer.setCity(city); customer.setProvinceCode(provinceCode); customer.setPostalCode(postalCode); customer.setCountryCode(countryCode); return customer; } private static Location createLocation(String name, String contactName, String address1, String address2, String address3, String address4, String city, String provinceCode, String postalCode, String countryCode, String phoneNumber, String mobileNumber) { Location location = new Location(); location.setName(name); location.setAddress1(address1); location.setAddress2(address2); location.setAddress3(address3);

BGS Web Services 4.0

Page 25 of36

location.setAddress4(address4); location.setCity(city); location.setProvinceCode(provinceCode); location.setPostalCode(postalCode); location.setCountryCode(countryCode); location.setContactName(contactName); location.setPhoneNumber(phoneNumber); location.setMobileNumber(mobileNumber); return location; } private static void saveLabelsToLocalFolder(ShipmentResponse shipmentResponse, String localFolder) throws Exception { String graphicFormat = "PDF"; String outFile = shipmentResponse.getHawbNumber(); ShipmentItemResponse shipmentItemResponse1 = shipmentResponse.getShipmentItemResponses.toArray()[0]; ByteArrayInputStream input = new ByteArrayInputStream(Base64.decode(shipmentItemResponse1.getLabelImageString( ))); BufferedImage bufferedImage = ImageIO.read(input); // write image to file String outPath = localFolder + "/" + outFile; OutputStream out = new FileOutputStream(outPath); ImageIO.write(bufferedImage, graphicFormat, out); input.close(); out.close(); System.out.println("Label saved to: " + outPath); } }

BGS Web Services 4.0

Page 26 of36

8. Appendix Service Type

Service Type DD AF AD DA AS BU UU BF FF Description Pickup Delivery Is LVP? Pickup Delivery AirportCode AirportCode Required Required Y Y Y Y Y Y Y Y

Door-To-Door Air Freight Airport-To-Door Door-To-Airport Additional Service Door-To-UPS UPS-To-UPS Door-To-FedEx FedEx-To-FedEx

Brinks Airport Airport Brinks Brinks Brinks UPS Brinks FedEx

Brinks Airport Brinks Airport Brinks UPS UPS FedEx FedEx

9. Appendix LVP Shipment

Delivery Type Id: Service Type BU BU UU UU BF BF BF BF FF FF FF FF Delivery Type Id 101 102 104 105 201 202 203 204 205 206 207 208 Description UPS Next Day Air (10:30 AM) UPS Next Day Air Saver (3:00 PM) UPS Next Day Air (10:30 AM) UPS Next Day Air Saver (3:00 PM) FedEx Priority Overnight (10:30 AM) FedEx Standard Overnight (3 PM) FedEx 2 Day FedEx 3rd Day FedEx Priority Overnight (10:30 AM) FedEx Standard Overnight (3 PM) FedEx 2 Day FedEx 3rd Day

Signature Type Id: Service Type BU BU BU UU BGS Web Services 4.0 Signature Type Id 101 102 103 104 Description Adult Signature Signature None Adult Signature Page 27 of36

UU UU BF BF BF BF BF FF FF FF FF FF

105 106 201 202 203 204 205 206 207 208 209 210

Signature None Adult Signature Direct Signature Indirect Signature No Signature Required Service Default Adult Signature Direct Signature Indirect Signature No Signature Required Service Default

10.

Appendix Commodity List

List of commodities (most used): Commodity Description Banknotes- Local Banknotes- U.S. Credit Cards - Blank CURRENCY - FOREIGN Currency Paper Cut & Polished Diamonds Gold Gold And Silver Jewellery Gold Jewellery Holograms Indust. goods on PM basis Multiple Commodities Negotiable Securities Non-Negotiable Securities OTHER PRECIOUS METALS Precious Stones Rough Diamonds Silver & Gold Jewelry Silver Jewellery Data Media (Tapes/Disks) Examples: BGS Web Services 4.0 Page 28 of36 Commodity Id Commodity UOM KGS 2 KGS 1 KGS 37 KGS 123 KGS 82 CTS 18 FTO 107 GMS 17 KGS 5 KGS 36 KGS 89 KGS 61 KGS 23 KGS 28 FTO 140 CTS 12 CTS 19 GMS 62 GMS 6 KGS 52 UOM Description Kilograms Kilograms Kilograms Kilograms Kilograms Carats Fine Troy Ounce Grams Kilograms Kilograms Kilograms Kilograms Kilograms Kilograms Fine Troy Ounce Carats Carats Grams Grams Kilograms

If commodity is Cut & Polished Diamonds, then please populate the netWeight fied in terms CTS (Carats). If commodity is Gold or OTHER PRECIOUS METALS, then please populate the netWeight field in terms of FTO (Fine Troy Ounce) If commodity is CURRENCY FOREIGN or Gold Jewellery, then please populate the netWeight field in terms KGS (Kilograms)

BGS Web Services 4.0

Page 29 of36

11.

Appendix Customs Code List United States-US (Pickup Location)

Description ATA CARNET COMMISSION DRAWBACK INSPECT DRAWBACK NON INSPECT GSP PROGRAM IMMEDIATE EXPORT IMMEDIATE TRANSPORT REGISTRATION RETURN AFTER CERT RETURN AFTER MFGR RETURN AFTER REPR RETURN SHIPMENT SALE SEND FOR REPAIR Versandschein Verzollung TRANSHIPMENT WAREHOUSE

11.1.

CustomsCode ATA COM DBI DBNI GSP IE IT REG RETC RETM RER RET SALE REP TE TIB TFM WHSE

11.2.

Germany (Pickup Location)

Description ATA CARNET Controlled Airfreight COMMISSION ON CONSIGNMENT Freight Freischreibung ON LOAN SEND OF REPAIR RETURN AFTER REPAIR Rckware RETURN AFTER MFGR SALE

CustomsCode ATA CAF COM CON FG FS LOAN REP RER RET RETM SALE

BGS Web Services 4.0

Page 30 of36

TE TFM TI VS VZ ZNV UBE

TEMPORARY EXPORT TRANSHIPMENT TEMPORARY IMPORT Versandschein Verzollung Sammelzollanmeldung bergabe

11.3.

Russia (Pickup Location)

Description RETURN AFTER REPR MFGR Description AFTER EXPERTISE CARNET ATA FOR EXPERTISE IN THE WAREHOUSE FOR REFINEMENT(PROCESSING) RETURN AFTER REPR RETURNED SHIPMENT RETURNED AFTER MFGR FOR SALE TEMPORARY EXPORTATION TEMPORARY IMPORTATION

CustomsCode ACER ATA CERT CON MFG RER RET RETM SALE TE TI

BGS Web Services 4.0

Page 31 of36

12. Appendix Package Type Code List

List of allowed package type codes for Service Types: DD, AF, AD, DA, AS Package Type Code BAG BOTTLE BOX CARD CARTON CONT CRATE DRUM ITEM PALL POUCH SKYBOX TIN TOTE ULD Description BAG BOTTLE BOX CARDBOARD BOX CARTON CONTAINER WOODEN CRATE DRUM ITEM PALLET BRINKS SEALED POUCH SKYBOX METAL TIN TOTE BOX UNIT LOAD DEVICE

List of allowed package type codes for Service Types: BU, UU Package Type Code CSP LEB MEB PAK SEB SMEB TUBE UPS10K UPS25K UPSEB UPSL Description Customer Supplied Package Large Express Box Medium Express Box Pak Small Express Box Small Express Box Tube UPS 10Kg Box UPS 25Kg Box UPS Express Box UPS Letter

List of allowed package type codes for Service Types: BF, FF Package Type Code FX10 FX25 BGS Web Services 4.0 Description FedEx 10Kg Box FedEx 25Kg Box Page 32 of36

FXEN FXLB FXMB FXSB

FedEx Envelope FedEx IP Large Box FedEx IP Medium Box FedEx IP Small Box

BGS Web Services 4.0

Page 33 of36

13. Appendix Customs Document Type

List of allowed customs document types: Document Type Code ATAC C/O CITES FORM-A FORM-D KPC OTHER TIB Description ATA Carnet Certificate of origin CITES (for Fish & Wildlife products) FORM A (for GSP) FORM D (for ASEAN country) KP Certificate Other Customs Document Temporary Importation Bond

BGS Web Services 4.0

Page 34 of36

14. Appendix Label Print Option

List of allowed ShipmentLabelRequest label types: Print Option Laser LaserTwoPart Label LabelWithTab Description To print on laser printer Two labels per page on laser printer To print on label printer (Thermal label printer) To print on label printer with Tab at the top For LVP Yes No No No

BGS Web Services 4.0

Page 35 of36

15. Appendix Category Code List

List of possible category codes for categoryCode in InvoiceItemCharge object: Category Code AIRCHARTER AIRLINE CHCHARGE COLLECT COURIER CUSTOMS EXTRADELIV GROUND INSURANCE OTHER SEAFREIGHT STORAGE TAX TRADE USERFEE VALUE VAULT WEIGHT Description Air Charter Airline charge CH Charge Collect charges Courier Customs clearance Extra Delivery Ground support Valuation Charges Other Charges Sea Freight Storage Taxes Trade User Fee Charges Value Charges Vault charges Extra Weight

BGS Web Services 4.0

Page 36 of36