brinks shipping api - bgs web services_v4.0.2 - annotated

BGS Web Services

BRINK’S Global Services

Version 4.0

BGS Web Services 4.0 of36

Contents

Purpose and Scope .................................................................................................................................. 4

1.1. Purpose.................................................................................................................................... 4

1.2. Scope ....................................................................................................................................... 4

2. Revision History ............................................................................................................................... 5

3. General Description ......................................................................................................................... 6

3.1. What is Web Service? ............................................................................................................... 6

3.2. WSDL (Web Service Definition Language) ................................................................................. 6

4. Web Service: ShipService ................................................................................................................. 6

4.1. Ship Service .............................................................................................................................. 6

4.1.1. WSDL................................................................................................................................ 6

4.1.2. Security (Authentication) .................................................................................................. 6

4.1.3. Account Setup .................................................................................................................. 6

4.2. Methods: createShipment, preadviseShipment ............................................................................ 7

4.2.1. createShipment ................................................................................................................ 7

4.2.2. preadviseShipment ........................................................................................................... 7

4.2.3. ShipmentRequest Object .................................................................................................. 7

4.2.4. ShipmentRequest - Data Description ................................................................................ 9

4.3. Method: updateShipment .......................................................................................................... 17

4.4. Method: cancelShipment ........................................................................................................... 18

4.5. Method: getHistoryByBarcode ................................................................................................... 18

4.5.1. ShipmentHistoryActivity Object ...................................................................................... 18

4.5.2. ShipmentHistoryActivity - Data Description .................................................................... 18

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


4.7. Method: getPODDocument ........................................................................................................ 19

4.7.1. PODDocumentRequest - Data Description ...................................................................... 19

4.8. Method: getPickupManifest ................................................................................................... 20

4.9. Method: getDocument ........................................................................................................... 20

4.9.1. DocumentRequest – Data Description ................................................................................ 20

5. Web Service: RateService............................................................................................................... 20

5.1. Rate Service ........................................................................................................................... 20

5.1.1. WSDL.............................................................................................................................. 20

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

6. Web Service: InvoiceService........................................................................................................... 21

6.1. Invoice Service ....................................................................................................................... 21

6.1.1. WSDL.............................................................................................................................. 21

6.2. Method: getInvoiceNumbersSince ......................................................................................... 21

6.3. Method: getInvoiceNumbersSince ......................................................................................... 21

6.3.1. InvoiceRequest – Data Description ..................................................................................... 21

7. Web Service Client : Java ............................................................................................................... 22

8. Appendix – Service Type ................................................................................................................ 27

9. Appendix – LVP Shipment .............................................................................................................. 27

10. Appendix – Commodity List........................................................................................................ 28

11. Appendix – Customs Code List ................................................................................................... 30

11.1. United States-US (Pickup Location)......................................................................................... 30

11.2. Germany (Pickup Location)..................................................................................................... 30

11.3. Russia (Pickup Location) ......................................................................................................... 31

12. Appendix – Package Type Code List ............................................................................................ 32

13. Appendix – Customs Document Type ......................................................................................... 34


14. Appendix – Label Print Option .................................................................................................... 35

15. 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 Brink’s Global Services (BGS) Web Services Version 3.0 operations.

1.2. Scope

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


2. Revision History

Revision Updated On Update By Description

1.0 2012/03/31 Ramesh Viswanathan Initial release

1.1 2012/07/03 Ramesh Viswanathan Added RateService to get rate quote for LVP

shipments

1.2 2012/09/05 Ramesh Viswanathan 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: Brink’s Pickup – to – UPS Delivery

o UU: UPS Pickup – to – UPS Delivery

o BF: Brink’s 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.


3. General Description

3.1. What is Web Service?

W3C’s Definition: A Web Service is a software system designed to support interoperable machine-

to-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 Service’s 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

Brink’s Global Services, which will create and set up the customer’s 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.


During the createShipment Web Service call invocation, shipper’s 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

4.2.1. createShipment

ShipmentResponse createShipment(Authentication, ShipmentRequest)

4.2.2. preadviseShipment

Notification preadviseShipment(Authentication, ShipmentRequest)

4.2.3. ShipmentRequest Object

Shipment Request object contains the shipping elements of Consignee, Delivery Location, Pick-

up contact information, service type, shipper’s 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, item’s insurance

liability value, item’s 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: Brink’s Pickup – to – UPS Delivery

o UU: UPS Pickup – to – UPS Delivery

o BF: Brink’s 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”, Shipment’s HAWB, and shipment item’s Barcode and base64 encoded shipping label

PDF document (includes all of the barcode labels one per page), in the first shipment item’s

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.


When a shipment has more than the Brink’s pre-approved limits on total Insurance Liability or

total Gross Weight, the shipment is turned into a Service Order and it is notified to Brink’s

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 Brink’s HAWB number to identify the

shipment. Every shipment item has to have a unique Brink’s 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 Brink’s

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/>


</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 Max.

Size

Required

/Optional

Description Allowed Values

hawbNumber 11 Optional/

Required

Shipment’s unique

Waybill number.

WebService

returns a

barcode if it is empty.

billingType 1 Required To specify the

billing charges type

“P” for pre-paid,

“C” for collect

shipper/name 40 Optional/

Required

Shipper’s name Required if it is

different from

user’s default

shipper


shipper/address1 30 Optional/

Required

Shipper’s address

line1

Required if

shipper’s name is

not empty

shipper/address2 30 Optional Shipper’s address

line2

Shipper/address3 30 Optional Shipper’s address

line3

Shipper/address4 30 Optional/ Shipper’s address

line4

shipper/city 25 Optional/

Required

Shipper’s city Required if

shipper’s name is

not empty

shipper/postalCode 15 Optional/

Required

Shipper’s postal

code

Required if

shipper’s name is

not empty

shipper/provinceCode 5 Optional Shipper’s province

code

shipper/countryCode 3 Required Shipper’s country

code

Required if

shipper’s name is

not empty. 2

char codes

(Example: FR –

France, US –

United States of

America, CA-

Canada)

pickUpLocation/name 40 Optional/

Required

Pickup location’s

name

Required if it is

different from

user’s default

pickup location

pickUpLocation/address1 30 Optional/

Required

Pickup location’s

address line1

Required if

pickUpLocationN

ame is not empty

pickUpLocation/address2 30 Optional Pickup location’s

address line2


address line3


address line4

pickUpLocation/city 25 Optional/

Required

Pickup location’s

city

Required if

pickUpLocationN

ame is not empty

pickUpLocation/postalCode 15 Optional/

Required

Pickup location’s

postal code

Required if

pickUpLocationN

ame is not empty


pickUpLocation/provinceCode 5 Optional Pickup location’s

province code

pickUpLocation/countryCode 3 Optional/

Required

Pickup location’s

country code

Required if

pickUpLocationN

ame is not empty

. 2 char codes

(Example: FR –

France, US –

United States of

America, CA-

Canada)

pickUpLocation/contactName 40 Optional/

Required

Pickup location’s Required if

pickUpLocationN

ame is not empty

pickUpLocation /phoneNumber 22 Optional/

Required

Pickup location’s

phone number

Required if

pickUpLocationN

ame is not empty

pickUpLocation /mobileNumber 22 Optional Pickup location’s

mobile number

pickUpLocation /emailAddress 255 Optional Pickup location’s

email id

consignee/ globalCustomerCode 20 Optional Consignee’s global

customer code

Can be omitted

for now

consignee/name 40 Required Consignee’s name

consignee/address1 30 Required Consignee’s

address

consignee/address2 30 Optional Consignee’s

address


address


address

consignee/city 25 Required Consignee’s City

consignee/postalCode 15 Required Consignee’s postal

code

consignee/provinceCode 5 Optional Consignee’s

province code

consignee/countryCode 3 Required Consignee’s

country code

2 char codes

(Example: FR –

France, US –

United States of

America, CA-

Canada)


deliveryLocation/ globalCustomerCode 20 Optional Delivery location’s

global customer

code

Can be omitted

for now

deliveryLocation/name 40 Required Delivery location’s

deliveryLocation/address1 30 Required Delivery location’s

address

deliveryLocation/ address2 30 Optional Delivery location’s address

deliveryLocation/ address3 30 Optional Delivery location’s

address

deliveryLocation/ address4 30 Optional Delivery location’s

address

deliveryLocation/city 25 Required Delivery location’s

deliveryLocation/postalCode 15 Required Delivery location’s

deliveryLocation/provinceCode 5 Optional Delivery location’s

deliveryLocation/countryCode 3 Required Delivery location’s 2 char codes

(Example: FR –

France, US –

United States of

America, CA-

Canada)

deliveryLocation/contactName 40 Required Delivery location

contact name

deliveryLocation/phoneNumber 22 Required Delivery location

contact’s phone

number

deliveryLocation/mobileNumber 22 Optional Delivery location

contact’s mobile

number

deliveryLocation/emailAddress 255 Optional Delivery contact’s

email id

serviceType 2 Required Shipment service

type

Please refer

Appendix-Service

Type for details

pickupAirportCode 3 Optional/Required

3 letter IATA

shipment origin

airport code.

Required for

service types: AF,

AD

Example: DFW

(Dallas-

Fortworth), LHR

(London

Heathrow), FRA

(Frankfurt)


deliveryAirportCode 3 Optional/Required

3 letter IATA

shipment

destination airport

code. Required for

service types: AF,

DA

Example: DFW

(Dallas-

Fortworth), LHR

(London

Heathrow), FRA

(Frankfurt)

localServiceType 2 Optional/Required

Any local (to the

servicing country)

service should be

populated in this

field along with the

service type set to

“AS”.

Example: RI in

Germany for

road transport.

modeOfTransportCode 1 Required “A” – Air, “R” –

Road, “S” – Sea, “L”

– Rail.

Only “A” is allowed

code for all LVP shipment.

Reference 30 Optional Customer’s

Shipment

reference

pickupDate 10 Required Shipment pickup

date

Allowed Format:

YYYY/MM/DD.

Ex: 2011/01/31

pickupTime 5 Required Shipment pickup

time in 24 hrs

format

Allowed format:

HH:mm

Ex: 10:00, 17:30

deliveryDate 10 Optional Shipment delivery

date.

Allowed Format:

YYYY/MM/DD.

Ex: 2011/02/01

deliveryTime 5 Optional Shipment delivery

time.

Allowed format:

HH:mm

Ex: 10:00, 17:30

requestLabelImage Required Request the

response to include

the base64

encoded Label image (png) string

True, False

pickupSiteCode 4 Optional/Required

Required when

pickup country code is other than

US and pickup

location name is

not empty

Please request

the site code(s) from BGS

WebServices

support.

pickupNotes 2000 Optional Special notes for

shipment pickup


deliveryNotes 2000 Optional Special notes for

shipment delivery

shipmentNotes 2000 Optional Shipment notes

requestLabelImage Required Request the

response to include

the base64

encoded Label

image (pdf) string

True/False

ShipmentLabelRequest/labelType 3 Required

/Optional

Required when

requestLabelImage

is set to true

PDF

ShipmentLabelRequest/printOption 12 Required

/Optional

Required when

requestLabelImage

is set to true

Please refer

Appendix – Label

Print Option

shipmentItemRequest/barcode 15 Optional/

Required

Shipment item’s

unique barcode

WebService

returns a

barcode if it is

empty in

ShipmentItemRe

sponse.

shipmentItemRequest/sealNumber 15 Optional Shipment seal

number if there is

any

shipmentItemRequest/

insuranceLiabilityCurrencyCode

4 Required Shipment item’s

liability currency

code


insuranceLiabilityValue

float Required Shipment item’s

liability value


insuranceLiabilityValueInUSD

float Optional Shipment item’s

liability value in US

Dollars

shipmentItemRequest/ commodityId 19 Required Please refer

Appendix-

Commodity List

shipmentItemRequest/ grossWeightUOM 4 Required Shipment item’s

unit of

measurement for

package weight

“KGS”, “LBS”

shipmentItemRequest/grossWeight float Required Shipment Item’s

(package) weight

shipmentItemRequest/netWeight float Required

for

International

Shipment

Shipment item’s

commodity weight

in commodity’s UOM.

Example: If the

chosen

commodity is “Cut & Polished

Diamonds” then


s only the netWeight

should be

defined in CTS

(carats). Please

see the

Commodity

Appendix for the

full list.

shipmentItemRequest/customsCurrencyCode 4 Required

for

Internatio

nal

Shipment

s only

Shipment Item’s

customs liability

currency code

shipmentItemRequest/customsValue Float Required for

Internatio

nal

Shipment

s only

Shipment Items’ customs liability

value

shipmentItemRequest/ originCustomsCode 4 Optional/Required

Item’s Customs

code. Required

only for

International

shipments.

Please refer

Appendix-

Customs Code

List

shipmentItemRequest/desitnationCustomsC

ode

4 Optional/Required

Item’s Customs

code. Required

only for

International

shipments.

Please refer

Appendix-

Customs Code

List

shipmentItemRequest/packageTypeCode 6 Required Shipment Item’s

package type

Please refer

Appendix-

Package Type

Code List

shipmentItemRequest/commodityOriginCou

ntryCode

3 Optional Commodity’s

manufacturing

origin country

2 char codes

(Example: FR –

France, US –

United States of

America, CA-

Canada)

shipmentItemRequest/poNumber 45 Optional Shipment Item’s po

number for

customer reference only.

shipmentItemRequest/contentQuantity long Optional Specifies the number of pieces

in the Shipment

Example: 20 (diamond

watches in the


Item. package)

shipmentItemRequest/dimLength float Optional Shipment Item’s

dimension length

shipmentItemRequest/dimWidth float Optional Shipment Item’s

dimension width

shipmentItemRequest/dimHeight float Optional Shipment Item’s

dimension height

shipmentItemRequest/dimUOM 2 Optional/

Required

Shipment Item’s

UOM for

dimension.

Required only if

dimension is

supplied

in, cm

shipmentLVPOptionsRequest/deliveryTypeId long Required

for LVP

LVP shipment

delivery type

Please refer

Appendix-LVP

Shipment

shipmentLVPOptionsRequest/saturdayDelive

ryFlag

boole

an

Required

for LVP

Need to be set to

true when a

shipment requires

Saturday delivery

Please refer

Appendix-LVP

Shipment

shipmentLVPOptionsRequest/residentialDeliv

eryFlag

boole

an

Required

for LVP

Need to be set to

true if the delivery

location is residential

Please refer

Appendix-LVP

Shipment

shipmentLVPOptionsRequest/signatureTypeI

d

long Required for LVP

Please refer Appendix-LVP

Shipment

customsDocumentRequest/documentCode 4 Optional/

Required

Can be filled in for

international

shipment to refer a

customs document

code

Please refer

Appendix-

Customs

Document Type

List

customsDocumentRequest/documentNumbe

r

20 Required

when

documen

tCode is

populate

d

Need to be filled in

with the customs

document number

when the cusomts

documentCode is

populated

brokerSelectFlag Boole

an

Required

for BF, FF Internatio

nal

Shipment

s only

Need to be set to

true for broker customer

clearance.

Available only for

BF, FF international

shipments.

broker/name 40 Optional/Required

Eligible when

brokerSelectFlag is


set to true

broker/address1 30 Optional/Required

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

broker/city 25 Optional/Required

Eligible when

brokerSelectFlag is

set to true

broker/provinceCode 5 Optional/Required

Eligible when

brokerSelectFlag is

set to true

broker/postalCode 15 Optional/Required

Eligible when

brokerSelectFlag is

set to true

broker/countryCode 3 Optional/Required

Eligible when

brokerSelectFlag is

set to true

broker/contactName 40 Optional/Required

Eligible when

brokerSelectFlag is set to true

broker/phoneNumber 22 Optional/Required

Eligible when

brokerSelectFlag is

set to true

broker/mobileNumber 22 Optional/Required

Eligible when

brokerSelectFlag is

set to true

broker/emailAddress 255 Optional/Required

Eligible when

brokerSelectFlag is

set to true

aesNumber 15 Optional/Required

Valid AES Number

for US outbound

international

shipments only.

4.3. Method: updateShipment ShipmentResponse updateShipment(Authentication, ShipmentRequest)


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 BRINK’S and a pickup scan performed.

o A manual pickup entry on the shipment from BRINK’S

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, it’s 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


Id Unique activity id

barcode Shipment barcode

activityType Type of activity PICK, DLVD, HUB, SCANC

PICK – Pickup scan activity

DLVD – Delivery scan activity

HUB – Hub Scan activity

SCANC – Shipment cancellation

activity

timeStamp Timestamp of the

activity as

dateTime type

timestampString Timestamp of the

activity as string

type

Data format: YYYY/MM/DD HH:mm.

Hours in 24 hours format.

Ex: 2011/01/31 20:15, 2011/02/03

09:20,

Detail Description of the

activity

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 Max Size Required/Optional Description Possible Values

barcode 15 Required Shipment barcode

documentType

3 Required Type of POD

document

PNG, PDF

PNG – Returns


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 date’s OR today’s

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 Required/Optional Description Possible Values

documentName Required Name of the

document to be obtained

InternationalHAWB

hawbNumber 11 Required Shipment HAWB

number

barcode

15 Unused Reserved for future

use

5. Web Service: RateService

5.1. Rate Service

5.1.1. WSDL

Test Environment WSDL of RateService Web Service is located at:


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 Max.Size Required/Optional Description Possible Values

invoiceNumber 20 Required Invoice number for

which the details to

be obtained

includeMAWBNumber boolean Required Specify whether the

invoice item’s to

include shipment’s


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 charge’s 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 javax.imageio.ImageIO;

import javax.xml.datatype.DatatypeConfigurationException;

import javax.xml.datatype.DatatypeConstants;

import javax.xml.datatype.DatatypeFactory;


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-123-

1234");

shipmentRequest. getPickUpLocation().setMobileNumber("222-123-

1234");

Customer consignee = createCustomer("BULL ELEDTRONICS ANGERS",

"34, RUE NID DE PIE", "", "", "",

"ANGERS", "", "49004", "FR"

);


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();


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.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.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);

}

}


8. Appendix – Service Type

Service

Type

Description Pickup Delivery Is

LVP?

Pickup

AirportCode

Required

Delivery

AirportCode

Required

DD Door-To-Door Brink’s Brink’s

AF Air Freight Airport Airport Y Y

AD Airport-To-Door Airport Brink’s Y

DA Door-To-Airport Brink’s Airport Y

AS Additional Service Brink’s Brink’s

BU Door-To-UPS Brink’s UPS Y

UU UPS-To-UPS UPS UPS Y

BF Door-To-FedEx Brink’s FedEx Y

FF FedEx-To-FedEx FedEx FedEx Y

9. Appendix – LVP Shipment

Delivery Type Id:

Service Type Delivery

Type Id

Description

BU 101 UPS Next Day Air (10:30 AM)

BU 102 UPS Next Day Air Saver (3:00 PM)

UU 104 UPS Next Day Air (10:30 AM)

UU 105 UPS Next Day Air Saver (3:00 PM)

BF 201 FedEx Priority Overnight (10:30 AM)

BF 202 FedEx Standard Overnight (3 PM)

BF 203 FedEx 2 Day

BF 204 FedEx 3rd Day

FF 205 FedEx Priority Overnight (10:30 AM)

FF 206 FedEx Standard Overnight (3 PM)

FF 207 FedEx 2 Day

FF 208 FedEx 3rd Day

Signature Type Id:

Service Type Signature

Type Id

Description

BU 101 Adult Signature

BU 102 Signature

BU 103 None

UU 104 Adult Signature


UU 105 Signature

UU 106 None

BF 201 Adult Signature

BF 202 Direct Signature

BF 203 Indirect Signature

BF 204 No Signature Required

BF 205 Service Default

FF 206 Adult Signature

FF 207 Direct Signature

FF 208 Indirect Signature

FF 209 No Signature Required

FF 210 Service Default

10. Appendix – Commodity List

List of commodities (most used):

Commodity Description Commodity Id Commodity UOM UOM Description

Banknotes- Local 2 KGS Kilograms

Banknotes- U.S. 1 KGS Kilograms

Credit Cards - Blank 37 KGS Kilograms

CURRENCY - FOREIGN 123 KGS Kilograms

Currency Paper 82 KGS Kilograms

Cut & Polished Diamonds 18 CTS Carats

Gold 107 FTO Fine Troy Ounce

Gold And Silver Jewellery 17 GMS Grams

Gold Jewellery 5 KGS Kilograms

Holograms 36 KGS Kilograms

Indust. goods on PM basis 89 KGS Kilograms

Multiple Commodities 61 KGS Kilograms

Negotiable Securities 23 KGS Kilograms

Non-Negotiable Securities 28 KGS Kilograms

OTHER PRECIOUS METALS 140 FTO Fine Troy Ounce

Precious Stones 12 CTS Carats

Rough Diamonds 19 CTS Carats

Silver & Gold Jewelry 62 GMS Grams

Silver Jewellery 6 GMS Grams

Data Media (Tapes/Disks) 52 KGS Kilograms

Examples:


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)


11. Appendix – Customs Code List

11.1. United States-US (Pickup Location)

CustomsCode Description

ATA ATA CARNET

COM COMMISSION

DBI DRAWBACK INSPECT

DBNI DRAWBACK NON INSPECT

GSP GSP PROGRAM

IE IMMEDIATE EXPORT

IT IMMEDIATE TRANSPORT

REG REGISTRATION

RETC RETURN AFTER CERT

RETM RETURN AFTER MFGR

RER RETURN AFTER REPR

RET RETURN SHIPMENT

SALE SALE

REP SEND FOR REPAIR

TE Versandschein

TIB Verzollung

TFM TRANSHIPMENT

WHSE WAREHOUSE

11.2. Germany (Pickup Location)

CustomsCode Description

ATA ATA CARNET

CAF Controlled Airfreight

COM COMMISSION

CON ON CONSIGNMENT

FG Freight

FS Freischreibung

LOAN ON LOAN

REP SEND OF REPAIR

RER RETURN AFTER REPAIR

RET Rückware

RETM RETURN AFTER MFGR

SALE SALE


TE TEMPORARY EXPORT

TFM TRANSHIPMENT

TI TEMPORARY IMPORT

VS Versandschein

VZ Verzollung

ZNV Sammelzollanmeldung

UBE Übergabe

11.3. Russia (Pickup Location)

CustomsCode Description Description

ACER ПОСЛЕ ЭКСПЕРТИЗЫ AFTER EXPERTISE

ATA КАРНЕТ АТА CARNET ATA

CERT ДЛЯ ЭКСПЕРТИЗЫ FOR EXPERTISE

CON НА СКЛАДЕ IN THE WAREHOUSE

MFG ДЛЯ ОБРАБОТКИ FOR REFINEMENT(PROCESSING)

RER RETURN AFTER REPR RETURN AFTER REPR

RET ВОЗВРАТНЫЙ ГРУЗ RETURNED SHIPMENT

RETM ВОЗВРАТ ПОСЛЕ MFGR RETURNED AFTER MFGR

SALE НА ПРОДАЖУ FOR SALE

TE ВРЕМЕННЫЙ ВЫВОЗ TEMPORARY EXPORTATION

TI ВРЕМЕННЫЙ ВВОЗ TEMPORARY IMPORTATION


12. Appendix – Package Type Code List

List of allowed package type codes for Service Types: DD, AF, AD, DA, AS

Package Type Code Description

BAG BAG

BOTTLE BOTTLE

BOX BOX

CARD CARDBOARD BOX

CARTON CARTON

CONT CONTAINER

CRATE WOODEN CRATE

DRUM DRUM

ITEM ITEM

PALL PALLET

POUCH BRINKS SEALED POUCH

SKYBOX SKYBOX

TIN METAL TIN

TOTE TOTE BOX

ULD UNIT LOAD DEVICE

List of allowed package type codes for Service Types: BU, UU


CSP Customer Supplied Package

LEB Large Express Box

MEB Medium Express Box

PAK Pak

SEB Small Express Box

SMEB Small Express Box

TUBE Tube

UPS10K UPS 10Kg Box

UPS25K UPS 25Kg Box

UPSEB UPS Express Box

UPSL UPS Letter

List of allowed package type codes for Service Types: BF, FF


FX10 FedEx 10Kg Box

FX25 FedEx 25Kg Box


FXEN FedEx Envelope

FXLB FedEx IP Large Box

FXMB FedEx IP Medium Box

FXSB FedEx IP Small Box


13. Appendix – Customs Document Type

List of allowed customs document types:

Document Type Code Description

ATAC ATA Carnet

C/O Certificate of origin

CITES CITES (for Fish & Wildlife

products)

FORM-A FORM A (for GSP)

FORM-D FORM D (for ASEAN country)

KPC KP Certificate

OTHER Other Customs Document

TIB Temporary Importation Bond


14. Appendix – Label Print Option

List of allowed ShipmentLabelRequest label types:

Print Option Description For LVP

Laser To print on laser printer Yes

LaserTwoPart Two labels per page on

laser printer

No

Label To print on label printer

(Thermal label printer)

No

LabelWithTab To print on label printer

with Tab at the top

No


15. Appendix – Category Code List

List of possible category codes for categoryCode in InvoiceItemCharge object:

Category Code Description

AIRCHARTER Air Charter

AIRLINE Airline charge

CHCHARGE CH Charge

COLLECT Collect charges

COURIER Courier

CUSTOMS Customs clearance

EXTRADELIV Extra Delivery

GROUND Ground support

INSURANCE Valuation Charges

OTHER Other Charges

SEAFREIGHT Sea Freight

STORAGE Storage

TAX Taxes

TRADE Trade

USERFEE User Fee Charges

VALUE Value Charges

VAULT Vault charges

WEIGHT Extra Weight

brinks shipping api - bgs web services_v4.0.2 - annotated

Documents

fedex standard

bull eledtronics

internatio

brinks global

charge line

web service

day air saver

outbound international