-
Notifications
You must be signed in to change notification settings - Fork 0
Shipping Service
http://api.despatchbay.com/soap/v15/shipping?wsdl
The Shipping Service lets you lookup which shipping services are available services to a given address, query current the status of existing shipments and add new shipments to the shipment queue.
- GetAvailableServices
- GetAvailableCollectionDates
- GetCollection
- GetCollections
- GetShipment
- AddShipment
- BookShipments
- CancelShipment
The GetAvailableServices
method returns a list of shipping services which are available for a given ShipmentRequestType
<message name="GetAvailableServicesRequest">
<part name="Shipment" type="tns:ShipmentRequestType"/>
</message>
<message name="GetAvailableServicesResponse">
<part name="return" type="tns:ArrayOfServiceType"/>
</message>
...
<operation name="GetAvailableServices">
<documentation>
Returns all available courier services for a specific recipient address
</documentation>
<input message="tns:GetAvailableServicesRequest"/>
<output message="tns:GetAvailableServicesResponse"/>
</operation>
Note: Certain elements of the
ShipmentRequestType
are irrelevant for use in this call. The values ofServiceID
,ClientReference
andFollowShipment
should be null
Input | Output |
---|---|
ShipmentRequestType |
ArrayOfServiceType |
The GetAvailableCollectionDates
method lists the possible collection dates for a given SenderAddressType
<message name="GetAvailableCollectionDatesRequest">
<part name="SenderAddress" type="tns:SenderAddressType"/>
<part name="CourierID" type="xsd:int"/>
</message>
<message name="GetAvailableCollectionDatesResponse">
<part name="return" type="tns:ArrayOfCollectionDateType"/>
</message>
...
<operation name="GetAvailableCollectionDates">
<documentation>
Returns all available collection dates for a specific sender address and courier
</documentation>
<input message="tns:GetAvailableCollectionDatesRequest"/>
<output message="tns:GetAvailableCollectionDatesResponse"/>
</operation>
Input | Output |
---|---|
SenderAddressType (Integer) CourierID
|
ArrayOfCollectionDateType |
The GetCollection
method returns the details of a single collection
<message name="GetCollectionRequest">
<part name="CollectionID" type="xsd:string"/>
</message>
<message name="GetCollectionResponse">
<part name="return" type="tns:CollectionReturnType"/>
</message>
...
<operation name="GetCollection">
<documentation>
Returns an existing collection
</documentation>
<input message="tns:GetCollectionRequest"/>
<output message="tns:GetCollectionResponse"/>
</operation>
Input | Output |
---|---|
(String) CollectionID
|
CollectionreturnType |
The GetCollections
method returns the details of all upcoming collections
<message name="GetCollectionsRequest"></message>
<message name="GetCollectionsResponse">
<part name="return" type="tns:ArrayOfCollectionReturnType" />
</message>
...
<operation name="GetCollections">
<documentation>
Returns existing active collections
</documentation>
<input message="tns:GetCollectionsRequest"/>
<output message="tns:GetCollectionsResponse"/>
</operation>
Input | Output |
---|---|
None | ArrayOfCollectionReturnType |
The AddShipment
method creates a new shipment in Despatch Bay.
<message name="AddShipmentRequest">
<part name="Shipment" type="tns:ShipmentRequestType"/>
</message>
<message name="AddShipmentResponse">
<part name="ShipmentID" type="xsd:string"/>
</message>
...
<operation name="AddShipment">
<documentation>Queues a new shipment</documentation>
<input message="tns:AddShipmentRequest"/>
<output message="tns:AddShipmentResponse"/>
</operation>
Input | Output |
---|---|
ShipmentRequestType |
(String) ShipmentID
|
Note: The ServiceID element of
ShipmentRequestType
is mandatory for this call. A valid service ID must be passed.
The BookShipments
method books one or more shipments. Booking finalises a shipment and charges the shipment cost to your Despatch Bay account.
When a shipment is booked, a Document ID is generated. The Document ID can be used in conjunction with the Documents API in order to retrieve the labels for the shipment.
<message name="BookShipmentsRequest">
<part name="ShipmentIDs" type="tns:ArrayOfShipmentID" />
</message>
<message name="BookShipmentsResponse">
<part name="return" type="tns:ArrayOfShipmentReturnType" />
</message>
...
<operation name="BookShipments">
<documentation>
Books existing shipments if they have not already been booked
</documentation>
<input message="tns:BookShipmentsRequest"/>
<output message="tns:BookShipmentsResponse"/>
</operation>
Input | Output |
---|---|
ArrayOfShipmentID |
ArrayOfShipmentReturnType |
The GetShipment
method returns an existing shipment from Despatch Bay
<message name="GetShipmentRequest">
<part name="ShipmentID" type="xsd:string"/>
</message>
<message name="GetShipmentResponse">
<part name="return" type="tns:ShipmentReturnType"/>
</message>
...
<operation name="GetShipment">
<documentation>Returns an existing shipment</documentation>
<input message="tns:GetShipmentRequest"/>
<output message="tns:GetShipmentResponse"/>
</operation>
Input | Output |
---|---|
(String) ShipmentID
|
ShipmentReturnType |
The CancelShipment
method attempts to cancel an existing shipment. Shipment cancellation will usually succeed as long as a shipment has not yet been despatched. CancelShipment
will fail when called with a shipment ID which has already been cancelled.
<message name="CancelShipmentRequest">
<part name="ShipmentID" type="xsd:string"/>
</message>
<message name="CancelShipmentResponse">
<part name="Response" type="xsd:boolean"/>
</message>
...
<operation name="CancelShipment">
<documentation>
Cancels an existing shipment if it has not already been despatched
</documentation>
<input message="tns:CancelShipmentRequest"/>
<output message="tns:CancelShipmentResponse"/>
</operation>
Note: This method will return boolean indicating the success of the cancellation
Input | Output |
---|---|
(String) ShipmentID
|
Boolean |
- AddressType
- CollectionDateType
- ArrayOfCollectionDateType
- CourierType
- ArrayOfCourierType
- ParcelType
- ArrayOfParcelType
- ServiceType
- ArrayOfServiceType
- RecipientAddressType
- SenderAddressType
- ShipmentRequestType
- ShipmentReturnType
- ArrayOfShipmentReturnType
The AddressType
object Represents a postal address
<xsd:complexType name="AddressType">
<xsd:all>
<xsd:element name="CompanyName" type="xsd:string" minOccurs="0" maxOccurs="1"/>
<xsd:element name="Street" type="xsd:string" minOccurs="1" maxOccurs="1"/>
<xsd:element name="Locality" type="xsd:string" minOccurs="0" maxOccurs="1"/>
<xsd:element name="TownCity" type="xsd:string" minOccurs="1" maxOccurs="1"/>
<xsd:element name="County" type="xsd:string" minOccurs="0" maxOccurs="1"/>
<xsd:element name="PostalCode" type="xsd:string" minOccurs="1" maxOccurs="1"/>
<xsd:element name="CountryCode" type="xsd:string" minOccurs="1" maxOccurs="1"/>
</xsd:all>
</xsd:complexType>
Element Name | Type | Description |
---|---|---|
CompanyName |
String | Company/Organisation name (optional) |
Street |
String | First line of street address |
Locality |
String | Second line of street address (optional) |
TownCity |
String | Town or city name |
County |
String | County |
PostalCode |
String | Postal code (optional for countries without postcodes) |
CountryCode |
String | ISO 3166-1 alpha-2 code |
The CollectionReturnType
object represents a collection
<xsd:complexType name="CollectionReturnType">
<xsd:all>
<xsd:element name="CollectionID" type="xsd:string" minOccurs="1" maxOccurs="1"/>
<xsd:element name="CollectionDocumentID" type="xsd:string" minOccurs="1" maxOccurs="1"/>
<xsd:element name="CollectionType" type="xsd:string" minOccurs="1" maxOccurs="1"/>
<xsd:element name="CollectionDate" type="tns:CollectionDateType" minOccurs="1" maxOccurs="1"/>
<xsd:element name="SenderAddress" type="tns:SenderAddressType" minOccurs="1" maxOccurs="1"/>
<xsd:element name="Courier" type="tns:CourierType" minOccurs="1" maxOccurs="1"/>
<xsd:element name="LabelsURL" type="xsd:string" minOccurs="1" maxOccurs="1"/>
<xsd:element name="ManifestURL" type="xsd:string" minOccurs="1" maxOccurs="1"/>
</xsd:all>
</xsd:complexType>
Element Name | Type | Description |
---|---|---|
CollectionID |
String | The ID of the collection |
CollectionDocumentID |
String | The ID of the collection |
CollectionType |
String | The collection type |
CollectionDate |
CollectionDateType |
The date of the collection |
SenderAddress |
SenderAddressType |
The sender address |
Courier |
CourierType |
The courier |
LabelsURL |
String | Documents API URL for retreiving labels |
Manifest |
String | Documents API URL for retreiving manifest |
ArrayOfCollectionReturnType
is an array of CollectionReturnType
objects
<xsd:complexType name="ArrayOfCollectionReturnType">
<xsd:complexContent>
<xsd:restriction base="SOAP-ENC:Array">
<xsd:attribute ref="SOAP-ENC:arrayType" wsdl:arrayType="tns:CollectionReturnType[]"/>
</xsd:restriction>
</xsd:complexContent>
</xsd:complexType>
The CollectionDateType
object represents a collection date
<xsd:complexType name="CollectionDateType">
<xsd:all>
<xsd:element name="CollectionDate" type="xsd:string" minOccurs="1" maxOccurs="1"/>
</xsd:all>
</xsd:complexType>
Element Name | Type | Description |
---|---|---|
CollectionDate |
String | Expressed as an ISO 8601 Date |
ArrayOfCollectionDateType
is an array of CollectionDateType
objects
<xsd:complexType name="ArrayOfCollectionDateType">
<xsd:complexContent>
<xsd:restriction base="SOAP-ENC:Array">
<xsd:attribute ref="SOAP-ENC:arrayType" wsdl:arrayType="tns:CollectionDateType[]"/>
</xsd:restriction>
</xsd:complexContent>
</xsd:complexType>
The CourierType
object represents a shipping courier
<xsd:complexType name="CourierType">
<xsd:all>
<xsd:element name="CourierID" type="xsd:string" minOccurs="1" maxOccurs="1"/>
<xsd:element name="CourierName" type="xsd:string" minOccurs="1" maxOccurs="1"/>
</xsd:all>
</xsd:complexType>
Element Name | Type | Description |
---|---|---|
CourierID |
String | An ID representing the courier |
CourierName |
String | The display name of the courier (eg. "Parcelforce" ) |
ArrayOfCourierType
is an array of CourierType
objects
<xsd:complexType name="ArrayOfCourierType">
<xsd:complexContent>
<xsd:restriction base="SOAP-ENC:Array">
<xsd:attribute ref="SOAP-ENC:arrayType" wsdl:arrayType="tns:CourierType[]"/>
</xsd:restriction>
</xsd:complexContent>
</xsd:complexType>
The ParcelType
object represents a parcel
<xsd:complexType name="ParcelType">
<xsd:all>
<xsd:element name="Weight" type="xsd:float" minOccurs="1" maxOccurs="1"/>
<xsd:element name="Length" type="xsd:float" minOccurs="1" maxOccurs="1"/>
<xsd:element name="Width" type="xsd:float" minOccurs="1" maxOccurs="1"/>
<xsd:element name="Height" type="xsd:float" minOccurs="1" maxOccurs="1"/>
<xsd:element name="Contents" type="xsd:string" minOccurs="0" maxOccurs="1"/>
<xsd:element name="Value" type="xsd:float" minOccurs="0" maxOccurs="1"/>
<xsd:element name="TrackingNumber" type="xsd:string" minOccurs="0" maxOccurs="1"/>
</xsd:all>
</xsd:complexType>
TrackingNumber
is only relevant in a return context. You cannot set a tracking number. Any value passed in to TrackingNumber
will be ignored.
Note: When sending outside of the United Kingdom all elements become mandatory for customs reasons. This includes the channel islands (Jersey & Guernsey)
Element Name | Type | Description |
---|---|---|
Weight |
Float | The weight of the parcel in kg |
Length |
Float | The length of the parcel in cm (longest dimension) |
Width |
Float | The width of the parcel in cm (second longest dimension) |
Height |
Float | The height of the parcel in cm (shortest dimension) |
Contents |
String | Description of the contents of the parcel |
Value |
String | Monetary value of the contents of the parcel (in GBP) |
TrackingNumber |
String | The parcel tracking number (only relevant in return context) |
ArrayOfParcelType
is an array of ParcelType
objects
<xsd:complexType name="ArrayOfParcelType">
<xsd:complexContent>
<xsd:restriction base="SOAP-ENC:Array">
<xsd:attribute ref="SOAP-ENC:arrayType" wsdl:arrayType="tns:ParcelType[]"/>
</xsd:restriction>
</xsd:complexContent>
</xsd:complexType>
The ServiceType
object represents a shipping service
<xsd:complexType name="ServiceType">
<xsd:all>
<xsd:element name="ServiceID" type="xsd:int" minOccurs="1" maxOccurs="1"/>
<xsd:element name="Format" type="xsd:string" minOccurs="1" maxOccurs="1"/>
<xsd:element name="Name" type="xsd:string" minOccurs="1" maxOccurs="1"/>
<xsd:element name="Cost" type="xsd:float" minOccurs="0" maxOccurs="1"/>
<xsd:element name="Courier" type="tns:CourierType" minOccurs="1" maxOccurs="1"/>
</xsd:all>
</xsd:complexType>
Element Name | Type | Description |
---|---|---|
ServiceID |
Integer | An ID representing the service |
Format |
String | Either PARCEL , PACKET , LARGE_LETTER or PALLET
|
Name |
String | The name of the service |
Cost |
Float | The cost of the service (in Despatch Bay credits) |
Courier |
CourierType |
The courier which provides this service |
ArrayOfServiceType
is an array of ServiceType
objects
<xsd:complexType name="ArrayOfServiceType">
<xsd:complexContent>
<xsd:restriction base="SOAP-ENC:Array">
<xsd:attribute ref="SOAP-ENC:arrayType" wsdl:arrayType="tns:ServiceType[]"/>
</xsd:restriction>
</xsd:complexContent>
</xsd:complexType>
The RecipientAddress
object represents a recipient's address
<xsd:complexType name="RecipientAddressType">
<xsd:all>
<xsd:element name="RecipientName" type="xsd:string" minOccurs="1" maxOccurs="1"/>
<xsd:element name="RecipientTelephone" type="xsd:string" minOccurs="0" maxOccurs="1"/>
<xsd:element name="RecipientEmail" type="xsd:string" minOccurs="0" maxOccurs="1"/>
<xsd:element name="RecipientAddress" type="tns:AddressType" minOccurs="1" maxOccurs="1"/>
</xsd:all>
</xsd:complexType>
Note: All elements become mandatory when sending outside of the United Kingdom.
This includes the Channel Islands (Jersey & Guernsey)
Element Name | Type | Description |
---|---|---|
RecipientName |
String | The name of the recipient |
RecipientTelephone |
String | The telephone number of the recipient (optional) |
RecipientEmail |
String | The email address of the recipient (optional) |
RecipientAddress |
AddressType |
The address of the recipient |
The SenderAddress
object represents the address of the sender of a shipment. Any valid UK address can be supplied within SenderAddress.
However, If you wish to use one of your registered collection addresses it is important to set the SenderAddressID
to the ID of your registered sender address. This is particularly important if you have previously arranged a collection schedule with us.
It is possible to obtain a full list of your registered sender addresses from the GetSenderAddresses call.
<xsd:complexType name="SenderAddressType">
<xsd:all>
<xsd:element name="SenderName" type="xsd:string" minOccurs="1" maxOccurs="1"/>
<xsd:element name="SenderTelephone" type="xsd:string" minOccurs="1" maxOccurs="1"/>
<xsd:element name="SenderEmail" type="xsd:string" minOccurs="1" maxOccurs="1"/>
<xsd:element name="SenderAddress" type="tns:AddressType" minOccurs="0" maxOccurs="1"/>
<xsd:element name="SenderAddressID" type="xsd:int" minOccurs="0" maxOccurs="1"/>
</xsd:all>
</xsd:complexType>
Note: Sender addresses outside of The United Kingdom are not supported.
Element Name | Type | Description |
---|---|---|
SenderName |
String | The name of the sender |
SenderTelephone |
String | The telephone number of the sender |
SenderEmail |
String | The email address of the sender |
SenderAddress |
AddressType |
The address of the sender |
SenderAddressID |
Integer | The ID of a registered collection address |
Note:
SenderAddress
andSenderAddressID
are mutually exclusive.
Setting aSenderAddressID
and aSenderAddress
will result in an error.
The ShipmentRequestType
object represents a shipment you intend to create
<xsd:complexType name="ShipmentRequestType">
<xsd:all>
<xsd:element name="ServiceID" type="xsd:int" minOccurs="0" maxOccurs="1"/>
<xsd:element name="Parcels" type="tns:ArrayOfParcelType" minOccurs="1" maxOccurs="1"/>
<xsd:element name="ClientReference" type="xsd:string" minOccurs="0" maxOccurs="1"/>
<xsd:element name="CollectionDate" type="tns:CollectionDateType" minOccurs="0" maxOccurs="1"/>
<xsd:element name="SenderAddress" type="tns:SenderAddressType" minOccurs="0" maxOccurs="1"/>
<xsd:element name="RecipientAddress" type="tns:RecipientAddressType" minOccurs="1" maxOccurs="1"/>
<xsd:element name="FollowShipment" type="xsd:boolean" minOccurs="0" maxOccurs="1"/>
</xsd:all>
</xsd:complexType>
Element Name | Type | Description |
---|---|---|
ServiceID |
Integer | ID of the service you wish to use (optional) |
Parcels |
ArrayOfParcelType |
An array of parcels |
ClientReference |
String | Your own reference for the shipment (optional) |
CollectionDate |
CollectionDateType |
Your required collection date |
SenderAddress |
SenderAddressType |
The address of the sender |
RecipientAddress |
RecipientAddressType |
The address of the recipient |
FollowShipment |
Boolean | Follow the shipment on the Despatch Bay dashboard (optional) |
The ShipmentReturnType
object represents a shipment within Despatch Bay
<xsd:complexType name="ShipmentReturnType">
<xsd:all>
<xsd:element name="ShipmentID" type="xsd:string" minOccurs="1" maxOccurs="1"/>
<xsd:element name="ShipmentDocumentID" type="xsd:string" minOccurs="1" maxOccurs="1"/>
<xsd:element name="CollectionID" type="xsd:string" minOccurs="1" maxOccurs="1"/>
<xsd:element name="ServiceID" type="xsd:int" minOccurs="1" maxOccurs="1"/>
<xsd:element name="Parcels" type="tns:ArrayOfParcelType" minOccurs="1" maxOccurs="1"/>
<xsd:element name="ClientReference" type="xsd:string" minOccurs="0" maxOccurs="1"/>
<xsd:element name="RecipientAddress" type="tns:RecipientAddressType" minOccurs="1" maxOccurs="1"/>
<xsd:element name="IsFollowed" type="xsd:boolean" minOccurs="0" maxOccurs="1"/>
<xsd:element name="IsDespatched" type="xsd:boolean" minOccurs="1" maxOccurs="1"/>
<xsd:element name="IsPrinted" type="xsd:boolean" minOccurs="1" maxOccurs="1"/>
<xsd:element name="IsDelivered" type="xsd:boolean" minOccurs="1" maxOccurs="1"/>
<xsd:element name="IsCancelled" type="xsd:boolean" minOccurs="1" maxOccurs="1"/>
<xsd:element name="LabelsURL" type="xsd:string" minOccurs="1" maxOccurs="1"/>
</xsd:all>
</xsd:complexType>
Element Name | Type | Description |
---|---|---|
ShipmentID |
String | The Despatch Bay shipment ID |
ShipmentDocumentID |
String | The Document ID for use with the Documents API in order to obtain labels for the shipment. Populated only for shipments which have been booked. |
CollectionID |
String | The ID of the collection the shipment is part of |
ServiceID |
Integer | The service ID |
Parcels |
ArrayOfParcelType | An array of parcels |
ClientReference |
String | Your own reference for the shipment |
RecipientAddress |
RecipientAddressType |
The address of the recipient |
IsFollowed |
Boolean | Whether the shipment is followed |
IsPrinted |
Boolean | Whether the shipment has been printed |
IsDespatched |
Boolean | Whether the shipment is despatched |
IsDelivered |
Boolean | Whether the shipment has been delivered |
IsCancelled |
Boolean | Whether the shipment has been cancelled |
LabelsURL |
String | This is a fully formed url to the Documents API which can be used to fetch labels for the shipment using the default layout for the account. Alternatively the ShipmentDocumentID can be used to form your own custom requests to the Documents API. Populated only for shipments which have been booked. |
ArrayOfShipmentReturnType
is an array of ShipmentReturnType
objects
<xsd:complexType name="ArrayOfShipmentReturnType">
<xsd:complexContent>
<xsd:restriction base="SOAP-ENC:Array">
<xsd:attribute ref="SOAP-ENC:arrayType" wsdl:arrayType="tns:ShipmentReturnType[]"/>
</xsd:restriction>
</xsd:complexContent>
</xsd:complexType>
ArrayOfShipmentID
is an array of String
<xsd:complexType name="ArrayOfShipmentID">
<xsd:complexContent>
<xsd:restriction base="SOAP-ENC:Array">
<xsd:attribute ref="SOAP-ENC:arrayType" wsdl:arrayType="xsd:string[]"/>
</xsd:restriction>
</xsd:complexContent>
</xsd:complexType>