brinks shipping api - bgs web services_v4.0.2 - annotated
TRANSCRIPT
BGS Web Services
BRINK’S Global Services
Version 4.0
BGS Web Services 4.0 Page 2 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
BGS Web Services 4.0 Page 3 of36
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
BGS Web Services 4.0 Page 4 of36
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.
BGS Web Services 4.0 Page 5 of36
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.
BGS Web Services 4.0 Page 6 of36
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.
BGS Web Services 4.0 Page 7 of36
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.
BGS Web Services 4.0 Page 8 of36
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/>
BGS Web Services 4.0 Page 9 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 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
BGS Web Services 4.0 Page 10 of36
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
pickUpLocation/address3 30 Optional Pickup location’s
address line3
pickUpLocation/address4 30 Optional Pickup location’s
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
BGS Web Services 4.0 Page 11 of36
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
consignee/address3 30 Optional Consignee’s
address
consignee/address4 30 Optional Consignee’s
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)
BGS Web Services 4.0 Page 12 of36
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)
BGS Web Services 4.0 Page 13 of36
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
BGS Web Services 4.0 Page 14 of36
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
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
shipmentItemRequest/
insuranceLiabilityValue
float Required Shipment item’s
liability value
shipmentItemRequest/
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
BGS Web Services 4.0 Page 15 of36
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
BGS Web Services 4.0 Page 16 of36
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
BGS Web Services 4.0 Page 17 of36
set to true
broker/address1 30 Optional/Required
Eligible when
brokerSelectFlag is
set to true
broker/address2 30 Optional/Required
Eligible when
brokerSelectFlag is
set to true
broker/address3 30 Optional/Required
Eligible when
brokerSelectFlag is
set to true
broker/address4 30 Optional/Required
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)
BGS Web Services 4.0 Page 18 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 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
BGS Web Services 4.0 Page 19 of36
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
BGS Web Services 4.0 Page 20 of36
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:
BGS Web Services 4.0 Page 21 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 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
BGS Web Services 4.0 Page 22 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 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;
BGS Web Services 4.0 Page 23 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-123-
1234");
shipmentRequest. getPickUpLocation().setMobileNumber("222-123-
1234");
Customer consignee = createCustomer("BULL ELEDTRONICS ANGERS",
"34, RUE NID DE PIE", "", "", "",
"ANGERS", "", "49004", "FR"
);
BGS Web Services 4.0 Page 24 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 25 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 26 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 27 of36
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
BGS Web Services 4.0 Page 28 of36
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:
BGS Web Services 4.0 Page 29 of36
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 30 of36
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
BGS Web Services 4.0 Page 31 of36
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
BGS Web Services 4.0 Page 32 of36
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
Package Type Code Description
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
Package Type Code Description
FX10 FedEx 10Kg Box
FX25 FedEx 25Kg Box
BGS Web Services 4.0 Page 33 of36
FXEN FedEx Envelope
FXLB FedEx IP Large Box
FXMB FedEx IP Medium Box
FXSB FedEx IP Small Box
BGS Web Services 4.0 Page 34 of36
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
BGS Web Services 4.0 Page 35 of36
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
BGS Web Services 4.0 Page 36 of36
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