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.

Methods

• GetAvailableServices
• GetAvailableCollectionDates
• GetCollection
• GetCollections
• GetShipment
• AddShipment
• BookShipments
• CancelShipment

GetAvailableServices

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 of ServiceID, ClientReference and FollowShipment should be null

Input	Output
ShipmentRequestType	ArrayOfServiceType

GetAvailableCollectionDates

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

GetCollection

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

GetCollections

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

AddShipment

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.

BookShipments

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

GetShipment

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

CancelShipment

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

Types

• AddressType
• CollectionDateType
• ArrayOfCollectionDateType
• CourierType
• ArrayOfCourierType
• ParcelType
• ArrayOfParcelType
• ServiceType
• ArrayOfServiceType
• RecipientAddressType
• SenderAddressType
• ShipmentRequestType
• ShipmentReturnType
• ArrayOfShipmentReturnType

AddressType

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

CollectionReturnType

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

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>

CollectionDateType

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

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>

CourierType

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

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>

ParcelType

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

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>

ServiceType

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

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>

RecipientAddressType

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

SenderAddressType

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 and SenderAddressID are mutually exclusive.
Setting a SenderAddressID and a SenderAddress will result in an error.

ShipmentRequestType

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)

ShipmentReturnType

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

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

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>