ParcelBroker API - V1 Booking

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.

Request

Please note the all data needs to be UTF-8 encoded. So for example the string:

<line1>Ågatan 11</line1>

should be

<line1>&#197;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>


Specification

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

 

<response>

    <header>

    <status>Success</status>

    </header>

    <shipment>

        <ordernumber>MPS00000</ordernumber>

        <net>58.92</net>

        <tax>11.78</tax>

    </shipment>

</response>


Specification

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>