Skip to content

Shipping Service

Jump to bottom
jamiethompson edited this page Feb 6, 2017 · 15 revisions

http://api.despatchbay.com/soap/v14/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.

Note: The Shipping API does not currently support downloading labels. If you require labels please see the PDF Labels Web Service documentation.

Methods

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

AddShipment

The AddShipment method creates a new shipment in Despatch Bay.

Note: The Shipping API does not currently support downloading labels. If you require labels please see the PDF Labels Web Service documentation.

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

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

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

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="1" maxOccurs="1"/>
    <xsd:element name="Value" type="xsd:float" minOccurs="1" 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="Name" type="xsd:string" minOccurs="1" maxOccurs="1"/>
    <xsd:element name="Cost" type="xsd:float" minOccurs="1" 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
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 a sender's address

<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="1" 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="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="CollectionDate" type="tns:CollectionDateType" minOccurs="1" 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="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:all>
</xsd:complexType>
Element Name Type Description
ShipmentID String The Despatch Bay shipment ID
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

Despatch Bay SOAP API v14

Clone this wiki locally