Overview Delivery Quotes Booking References Return Codes Test Harness
This API is used to make a bookings and collection requests on the ParcelBroker system. This API can be used for single shipments, multi-parcel bookings or pallet collections.
Please note the all data needs to be UTF-8 encoded. So for example the string:
<line1>Ågatan 11</line1>
should be
<line1>Ågatan 11</line1>
<booking>
<header>
<apikey>testapikey</apikey>
<key>publickey</key>
<token>e8beca07478a92507b4f91bc36638bdd09ad691f</token>
<uniqueid>64664664645125484</uniqueid>
</header>
<shipment>
<test>true</test>
<rate_id>3</rate_id>
<hash>a4e62686ad2ea528ded466acc3c87d9c6689f2a7</hash>
<customref>Order# 24157</customref>
<contents>
<content>Blue Widgets</content>
</contents>
<estvalue>12.00</estvalue>
<liability>true</liability>
<type>PARCEL</type>
<collection>
<name>John Smith</name>
<company>Blue Widgets Ltd</company>
<phone>01999 944449</phone>
<email>john@bluewidgets.co.uk</email>
<line1>Unit 6</line1>
<line2>Apex Way</line2>
<line3></line3>
<town>Wrexham</town>
<county>Surrey</county>
<postcode>RG1 3DW</postcode>
<countrycode>UK_M</countrycode>
</collection>
<destination>
<name>Reception</name>
<company>Forefront Solutions</company>
<phone>01333 334334</phone>
<email>info@forefront-solutions.co.uk</email>
<line1>14 The Drive</line1>
<line2>Aspen Lane</line2>
<line3></line3>
<town>Braintree</town>
<county>Essex</county>
<postcode>CM1 4TY</postcode>
<countrycode>UK_M</countrycode>
</destination>
<parcels>
<parcel>
<weight>10</weight>
<length>11</length>
<width>14</width>
<height>6</height>
<packaging>CARD</packaging>
</parcel>
<parcel>
<weight>16</weight>
<length>28</length>
<width>9</width>
<height>2</height>
<packaging>OTHER</packaging>
</parcel>
</parcels>
<pickup>
<date>2013-11-20</date>
</pickup>
<customs>
<type>PROFORMA</type>
<sendervat>12345</sendervat>
<receivervat></receivervat>
<com>XX</com>
<reason>SALE</reason>
<content>
<description>Blue Widgets</description>
<quantity >6</quantity>
<value>2.00</value>
</content>
</customs>
<label>A4</label>
</shipment>
</booking>
The Schema for this API can be downloaded here: Download Booking Schema.
| Element | Req | Description | |
|---|---|---|---|
<header> | Yes | Holder for header element. | |
<apikey> | Yes | This is the APIKey as provided by ParcelBroker. | |
<key> | Yes | This is your Public Key that use use to create the <token> value. | |
<token> | Yes | SHA1 hash of "SharedSecret_PublicKey". | |
<uniqueid> | Yes | A unique ID for every successful request. Duplicate requests with the same ID will be rejected. | |
</header> | |||
<shipment> | Yes | Holder for shipment element. | |
<test> | No | Indicates that this order is a test order. | |
<rate_id> | Yes | The rate ID as obtained from the Rates API. | |
<hash> | Yes | Hash for this service as obtained from the Rates API. | |
<customref> | Yes | Your reference for this shipment. | |
<contents> | Yes | Description of shipment contents. | |
<estvalue> | Yes | The estimated value of the shipment in GBP. | |
<liability> | Yes | Whether liability is required. If true then 2% of estvalue will be added your order. | |
<type> | Yes | Possible values are DOCUMENT, PARCEL, PALLET. | |
<collection> | Yes | Holder for collection address. | |
<name> | Yes | The collection persons name. | |
<company> | Yes | The collection company (if applicable). | |
<phone> | Yes | The collection phone number. | |
<email> | No | The collection email address. | |
<line1> | Yes | The collection address line 1. | |
<line2> | Yes | The collection address line 2. | |
<line3> | Yes | The collection address line 3. | |
<town> | Yes | The collection town/city. | |
<county> | Yes | The collection county/state. | |
<postcode> | Yes | The collection postcode. | |
<countrycode> | Yes | The collection country code. Please click here for country codes. | |
</collection> | |||
<destination> | Yes | Holder for destination address. | |
<name> | Yes | The destination persons name. | |
<company> | Yes | The destination company (if applicable). | |
<phone> | Yes | The destination phone number. | |
<email> | No | The destination email address. | |
<line1> | Yes | The destination address line 1. | |
<line2> | Yes | The destination address line 2. | |
<line3> | Yes | The destination address line 3. | |
<town> | Yes | The destination town/city. | |
<county> | Yes | The destination county/state. | |
<postcode> | Yes | The destination postcode. | |
<countrycode> | Yes | The destination country code. Please click here for country codes. | |
</destination> | |||
<parcels> | Yes | Holder for parcels. | |
<parcel> | Yes | Holder for a parcel (Can have more than 1). | |
<weight> | Yes | The weight in KG. | |
<length> | Yes | The length in CM. | |
<width> | Yes | The width in CM. | |
<height> | Yes | The height in CM. | |
<packaging> | Yes | This indicates the main type of outer packaging, valid values are CARD, METAL, PLASTIC, OTHER. | |
</parcel> | |||
</parcels> | |||
<pickup> | Yes | Holder for pick up type and details. Can be one of the following:. | |
<date> | Choice | To request a collection from the carrier on the specified date. Format is YYYY-MM-DD | |
<dropoff> | Choice | If the customer is going to drop the shipment at a local service point. | |
<today> | Choice | If the booking should be added to other collections already requested today. This is dependant on the cut off times as obtained via Rates API and whether the driver has already collected from the premises. | |
<daily> | Choice | If the customer has a daily collection, this shipment will be added to their next collection. | |
</pickup> | |||
<customs> | Yes/No | Holder for customs. | |
<type> | Yes/No | Can be either PROFORMA or COMMERCIAL. | |
<sendervat> | Yes/No | Senders VAT/EORI Number (if applicable). | |
<receivervat> | Yes/No | The receivers VAT or Personal ID number. For Gilbrator and Canary Islands this is known as the recipients CIF (Certificado de Identificación Fiscal) or NIF (Número de Identificación Fiscal) For Brazil this is known as the recipients Tax ID number (for companies) or CPF number (for individuals). For Norway this is known as the recipients VAT number (for companies) or Personal ID number (for individuals) | |
<com> | Yes/No | This is the two letter country code that identifies the Country of Manufacture (CoM). For items that have multiple countries please use XX | |
<reason> | Yes/No | The main reason for export. Can be any of the following values: SALE, GIFT, PERSONAL, DOCUMENTS, SAMPLE, REPAIR, REPLACEMENT, STOCK | |
<contents> | Yes/No | Holder for detailed description of contents. | |
<content> | Yes/No | For each type of item/product in the shipment a new content element should be included. | |
| <description> | Yes/No | A description of the contents. | |
| <quantity> | Yes/No | The item quantity. | |
| <value> | Yes/No | The individual quantity value in 0.00 format. | |
</content> | |||
</contents> | |||
</customs> | |||
<label> | No | The output format for the labels. Valid values are A4 or THERMAL. Default is A4 as some carrier do not have thermal compatible variations. | |
</shipment> |
<response>
<header>
<status>Success</status>
</header>
<shipment>
<ordernumber>MPS00000</ordernumber>
<net>58.92</net>
<tax>11.78</tax>
</shipment>
</response>
The Success response status returns an order number along with the final cost, including all surcharges and additional items:
| Element | Description |
|---|---|
<shipment> | Holder for service element. |
<ordernumber> | This is the order number for this booking. |
<net> | This is the net cost of the order. |
<tax> | This is the tax for this order. |
</shipment> |