api-docs.parcel2go.com Open in urlscan Pro
54.158.115.241  Public Scan

Form analysis
0 forms found in the DOM

Text Content

Public


Documentation Settings

ENVIRONMENT
No Environment

LAYOUT
Double Column

LANGUAGE
cURL - cURL



Parcel2Go API
Introduction
Authentication and Authorisation
Orders
Making a Payment
Country Subdivisions
Links Object
Customs
Extras
Webhooks
Endpoints
Functional Differences between Live and Sandbox Environments
Terms and Conditions
Me
AddressRules
CollectionDates
Countries
DropShops
Faqs
Invoices
Labels
OrderDetails
Orders
PayWithPrepay
PrePay
ProhibitedItems
Quotes
Services
Tracking


PARCEL2GO API

The shipping API is ideal for implementing delivery solutions for any kind of
website. We support flexible authentication using OpenId connect with Oauth2. We
support the following :

   
 * Creating Orders
   
 * Tracking
   
 * Payments including : Prepay, Cards, External, On Account.
   
 * Drop shop geolocation
   
 * Quoting
   
 * Labels
   
 * Advanced address rules for international addresses
   


AUTHENTICATION AND AUTHORISATION

Before you can start using the APIs you need to configure an authentication
method. The APIs use the OAuth2 protocol for authentication which conforms to
the OpenID Connect specification. There are several types of OAuth 2.0
authentication scenarios, the common ones are detailed below. There are also
several levels of access which are controlled using the scope parameter, which
is specified when requesting access tokens.


CLIENT CREDENTIALS

REQUESTING A CLIENT ID

One can begin with obtaining client credentials from My Account or from Settings
> API. Then your client application will request an access token from the
Authorization Server. My account is an area where users can manage personal
details, orders and settings such as API Keys. When creating API credentials the
field named secret will require a password that you will be required to create.
The value of the secret will be used as a parameter when attempting to obtain an
access token and it is therefore important that you retain the secret in a
confidential place.

You will be assigned a client id and secret which you can then exchange for an
access token using the authorisation endpoint; The access token is then used in
the Authorization header when making HTTP calls to the API.

   
 * Clients using this method must be able to maintain a secret (not suitable for
   client side code).
   
 * Payments can be configured against clients account
   
 * Tokens have an expiry time
   

This method is ideal when the client will be communicating server to server and
the payment scope is not required or all payments will be coming from the hosts
account.

Note: Client credentials can be used to make payments, please see the section
named Making A Payment for further information.

ACCESS TOKEN

This access token can be used to access protected resources and can grant the
client access to many APIs. However, the scope parameter will control the set of
resources the token can access and the operations it is allowed to perform. In
the scope parameter there should be one or more values when making a request to
get an access token. The access token is only valid for the operations and
resources that were described in the scope parameter when obtaining the token.
The required scopes can be seen below.

   
 * payment: This scope is required in order to make payments on behalf of a
   customer using their PrePay balance.
   
 * public-api: this scope allows access to the API. This is the basic scope
   required for any API call.
   
 * my-profile: this scope allows access to a user profile and is required when
   making calls to the endpoints found in the Me section.
   

EXAMPLE TOKEN REQUEST

View More
Plain Text


POST /auth/connect/token HTTP/1.1
Host: example.com
User-Agent: insomnia/5.14.6
Content-Type: application/x-www-form-urlencoded
Accept: \\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\*/\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\*
grant_type=client_credentials
  &scope=public-api payment my-profile
  &client_id=
  &client_secret=

EXAMPLE RESPONSE

Plain Text


{
    "access_token": "435435435345SDFS...",
    "expires_in": 7200,
    "token_type": "Bearer"
}

The access_token here can now be used in HTTP requests to the api by specifying
a bearer token header.

View More
Plain Text


POST /api/quotes HTTP/1.1
Host: example.com
User-Agent: insomnia/5.14.6
Content-Type: application/json
Authorization: Bearer 
Accept: \\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\*/\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\*
{
  "CollectionAddress": {
    "Country": "GBR"
  },
  "DeliveryAddress": {
    "Country": "GBR"
  },
  "Parcels": [
    {
      "Value": 150,
      "Weight": 2,
      "Length": 9,
      "Width": 8,
      "Height": 10
    }
  ]
}


IMPLICIT FLOW

Alternatively, you will redirect the user to our authorisation endpoint where
the user will log in and get redirected back to your site. The access token will
be included in the redirect url.

   
 * Provides greater level of access
   
 * Return URLs are part of the authentication so must be registered
   
 * No secret
   
 * Users have to log in
   
 * Users can revoke the access token
   
 * Tokens have a short lived expiry date
   
 * Enables us to authorise your application
   

This flow is ideal for clients which want to integrate with a customers account
and allow the customer to pay for their own orders. Implicit flow can be
requested in the api settings of your acccount.

EXAMPLE AUTHORIZE REDIRECT

Plain Text


GET /auth/connect/authorize
?client_id=example
&redirect_uri=http://www.example.com/return 
&response_type=token
&scope=openid+public-api 
HTTP/1.1
Host: www.example.com

EXAMPLE AUTHORIZE RETURN URL

Plain Text


GET /return
?access_token=xxxxxxx...
&token_type=Bearer
&expires_in=7200
HTTP/1.1
Host:www.example.com


ORDERS


ORDER FLOW

The order journey process consists of 5 mandatory steps accompanied by various
optional actions to enhance the experience of the customer.


   
 * Authenticate (Required) - The first step in the order journey is to get an
   access token for the API to perform further requests. Information on how to
   do so can be found in the 'Authentication and Authorisation' section of the
   documentation.
   
 * Get Countries (optional) - This step is to retrieve the list of countries
   that can be delivered to. The endpoint contains high level delivery
   information for the country such as address validation and whether customs
   are required. It's important to perform this step, because the information
   could change at anytime. It's advised to read the 'Country Subdivisions'
   section for more information.
   
 * Get Services (Optional) - The endpoint for this step returns a list of active
   services and their details. A use case for this would be for pre-selecting a
   service to get a quote for based on its features (Collection/Delivery type).
   
 * Get Address Rules (Optional) - The majority of services will accept the
   common details of house name/number, street, town, country and postcode. Some
   countries and services may have edge cases, so if an order is failing due to
   the address the full ruleset can be found here.
   
 * Search Prohibited Items (Optional) - Some countries and/or services have
   restrictions on what items can be delivered. This step should only need to be
   used the if the item may have cause for concern or it's unknown by the client
   what the customer will be sending until the point of order.
   
 * Get a Quote (Required) - Validates the delivery criteria and uses it to
   retrieve a list of matching services and pricing information.
   
 * Get Drop Shops (Optional) - For a drop off service this step can be used to
   retrieve a list of shops that a customer can drop their parcel off at.
   
 * Verify Order (Optional) - This step performs the same validation that 'Create
   an Order' does and returns detailed pricing information for each order line.
   A use case for this would be to confirm the final price to the customer if
   additional extras have been added on after receiving a quote.
   
 * Create an Order (Required) - This will create an unpaid order in the system
   and return links on how to pay. If errors are frequently encountered, such as
   address information then it's advised to look at the optional steps to
   resolve.
   
 * Pay for an Order (Required) - The final step to transact an order is using
   one of the payment options below. More information can be found under the
   'Making a Payment' section.
     
   * PrePay - Pay for the order using the logged in user's prepay balance
     
   * Payment - Redirect the customer to a payment page using the deep link.
     
   
 * Get Labels (Conditional) - For payment options where the customer ends the
   order journey on the client's application. The 'Labels' endpoints will return
   shipping labels in various formats.
   


CREATING AN ORDER

A successful response will include the orderId allow with links to payment
options.

   
 * OrderlineIdMap - This is a map of OrderLineIds to the original request item
   ids which you assigned.
     
   * Hash - This reference is for getting labels or doing any action which would
     normally require user permissions.
     
   * OrderLineId - This is the our reference for this shipment and is an
     important reference used for contacting us about a shipment.
     
   * ItemId - The id you assigned to the item.
     
   

SUCCESSFUL RESPONSE

The Following is a successful response from creating an order.

View More
Plain Text


{
  "OrderId": "76423942",
  "Links": {
    "PayWithPrePay": "https://example.com/api/orders/76423942/paywithprepay?hash=hXJHm9/gsMM8QkLhu7z/QbRc+IdhzpLXx86f1te9p0o=",
    "payment": "https://example.com/order/payment?id=76423942&hash=A0346D798A2AEA71D47776324F44ACA5A567425471BD6BF8D558828F48AD76661684249125",
    "help": "https://example.com/help-centre"
  },
  "TotalPrice": 7.38,
  "TotalVat": 1.23,
  "TotalPriceExVat": 6.15,
  "Hash": "hXJHm9/gsMM8QkLhu7z/QbRc+IdhzpLXx86f1te9p0o=",
  "OrderlineIdMap": [
    {
      "Hash": "9DXy5SLf6adMMqpZUljifjp92AfLwJuXaK+KYHCw9JA=",
      "OrderLineId": "115030194",
      "ItemId": "48867b5a-016e-4931-956c-e59b6eb84355"
    }
  ],
  "TotalDiscount": 0
}


ADDING EXTRAS TO YOUR ORDER

The following is an example of the body request used during a POST when creating
an order with extras.

*Please note when adding 'Extras' to the order request, these should be added
under the 'Upsells' property.

View More
Plain Text


{
  "Items": [
    {
      "Id": "9c2f14e4-eae2-47db-8e49-df2aba410268",
      "CollectionDate": "2021-12-13T14:22:14.2108186+00:00",
      "Service": "24h-example",
      "Upsells" : [
        {
            "Type": "Sms"
        }
      ],
      "Parcels": [
        {
          "Id": "00000000-0000-0000-0000-000000000000",
          "Height": 10,
          "Length": 10,
          "EstimatedValue": 100,
          "Weight": 1,
          "Width": 10,
          "DeliveryAddress": {
            "ContactName": "Test",
            "Email": "test@test.com",
            "Property": "11",
            "Street": "Saville St",
            "Town": "Malton",
            "County": "North Yorkshire",
            "Postcode": "YO17 7LL",
            "CountryIsoCode": "GBR",
            "CountryId": 0
          },
          "ContentsSummary": "Slippers"
        }
      ],
      "CollectionAddress": {
        "ContactName": "John Doe",
        "Organisation": "",
        "Email": "j.doe@yahoo.com",
        "Phone": "07587569852",
        "Property": "1",
        "Street": "Raleigh Street",
        "Locality": "",
        "Town": "Scarborough",
        "County": "North Yorkshire",
        "Postcode": "YO12 7JZ",
        "CountryIsoCode": "GBR",
        "CountryId": 0,
        "SpecialInstructions": ""
      }
    }
  ],
  "CustomerDetails": {
    "Email": "j.doe@yahoo.com",
    "Forename": "John",
    "Surname": "Doe"
  }
}

The following is a successful response from creating an order with extras, this
will reflect its increase in price depending on the extra's cost.

Plain Text


...
  "TotalPrice": 3.47,
  "TotalVat": 0.58,
  "TotalPriceExVat": 2.89,
  ...
}

The same successful response without extras.

Plain Text


{
  ...
  "TotalPrice": 3.11,
  "TotalVat": 0.52,
  "TotalPriceExVat": 2.59,
  ...
}


MAKING A PAYMENT

A variety of payment options are available to complete the order transaction.
The available payment options can vary, so it's advised to always check the
options returned to you from the API in the 'Links' object.


PREPAY

Use this option to pay for an order using the logged in user's pre pay balance.
A token must be provided which has the payment scope and you must be authorised
by the user (via implicit flow). In addition payments can be made on behalf of
the customer using their client credentials when a token with the payment scope
has been generated. Negative balances are not allowed, so it's advised to
monitor your balance and top-up accordingly - you can do so using the PrePay API
endpoint. It's also possible to setup prepay so that a single account will be
debited for clients which want to use their own account to pay for orders.

A pre generated URL for the 'PayWithPrepay' endpoint will be generated when
creating an order, which can be used to complete the transaction. If you'd like
to construct the URL yourself then please see the endpoint details for doing so.


PAYPAL

This option allows the order to be paid for with the customer's PayPal account.


CREDIT OR DEBIT CARD

Allow the customer to pay with their credit or debit card using one of our
selected payment gateways.


DEEPLINK

This option is for offloading the customer into the API's booking flow to
complete the order.

   
 * The customer will not be returned to the client's application, they'll end
   their order process on the API's completion page and be offered various
   options like downloading a label.
   
 * A selection of the above payment methods will be offered to the customer.
   
 * The buyer will not be allowed to pay with the customer's prepay balance (the
   account that was used to create the order via the API).
   


COUNTRY SUBDIVISIONS

For some parts of the world we've split a country into smaller areas. This is
usually down to the destination being an archipelago or island and/or the area
requires a different ruleset.

When retrieving a list of countries from the API, a subdivision will have the
'Subdivision' field filled with a code. This code is not to be confused with an
ISO-3166-2 code, but you'll find some share the same value and / or format.

Below is a list of the subdivisions available. Please note this table is a guide
only, and it's advised to always check the countries API endpoint before usage.

View More

Name Code Bonaire BQ-BO Canary Islands ES-CN Channel Islands GB-CI St. Eustatius
BQ-SE Crete GR-M Balearic Islands ES-IB Ibiza ES-IBIZA Majorca ES-MAJORCA
Menorca ES-MENORCA Northern Ireland NIR Scottish Highlands and Islands HIGH
Azores PT-20 Ceuta ES-CE Melilla ES-ML Tenerife ES-TF Gran Canaria ES-GC
Lanzarote ES-LZ Fuerteventura ES-FU La Palma ES-LP La Gomera ES-LG El Hierro
ES-EH Madeira PT-30 Sicily IT-SI Sardinia IT-SA Isle of Man IOM Corsica FR-COR
Saint Helena SH-HL Ascension SH-AC Tristan da Cunha SH-TA


LINKS OBJECT

Some returned objects have a 'Links' object that contains URLs to perform
further actions.


REDIRECTS

   
 * URLs that you can redirect your customers to for more information about the
   object.
   

Key Description complete-page A page to display that the order has been
completed. tracking-page A page showing tracking information for the order. help
A link to our help centre.


API ENDPOINTS

   
 * A pre generated URL for an API endpoint.
   
 * See the documentation for each endpoint for further information.
   

Key Description Labels For the /labels/{reference} API endpoint, which will
create an A4 PNG for all labels in the order as a Base64 encoded string.


DOCUMENTS

   
 * A publicly accessible URL for getting a document.
   
 * Perform a GET request to retrieve the document.
   
 * No authorisation is required.
   

Key Type Description labels-a4 PDF An A4 page with a parcel label. Instructions
may also be included. labels-4x6 PDF A 4x6 page and parcel label. labels-a4-4x6
PDF An A4 page with a 4x6 parcel label label-a4-21 PDF A set of A4 pages with up
to 21 addresses per sheet. This is only available for orders created via
SmartSend. picking-list PDF A list for picking and packing invoice PDF An
invoice for the order. barcode-printinstore PNG A barcode for printing the
parcel's label in-store. wallet-ios-printinstore PNG A barcode for printing the
parcel's label in-store.


PAYMENT

   
 * A URL for invoking a payment option
   
 * Each option has a different implementation, please see the "Payment" section
   for further information.
   

Key Description PayWithPrePay Pay for the order with the logged in user's pre
pay balance. paypal Lets the customer for the order using their paypal account
payment Deeplink the customer into our booking flow and let them pay with one of
our available options card Lets the customer pay for the order using their card.
PayByCard A secondary option for letting the customer pay for the order using
their card.


CUSTOMS

International shipments require additional customs details which are provided
below :

   
 * ExportReason - The reason for exporting the item, acceptable values are:
     
   * Sale
     
   * Gift
     
   * Sample
     
   * Repair
     
   * Documents
     
   * IntraCompanyTransfer
     
   * TemporaryExport
     
   
 * VatStatus - This is the VAT status of the sender, one of :
     
   * Individual
     
   * NotRegistered
     
   * Registered
     
   
 * VatNumber - The sender's VAT number if VAT status is 'Registered'.
   
 * NifNumber - Tax identification number for Spanish companies.
   
 * EoriNumber - Economic Operator Registration and Identification Number - For
   registered companies.
   
 * OriginCountry - This is the ISO 3166-1 alpha 3 code for the country the item
   was manufactured in.
   
 * TariffCode - The trade tariff code can be specified where applicable. (See
   https://www.gov.uk/trade-tariff)
   

EXAMPLE OF A FAILED INTERNATIONAL ORDER

This is an example of a response when customs is required but not specified.

View More
Plain Text


{
  "Errors": [
    {
      "Type": "Customs",
      "Error": "Please supply the reason for exporting your parcel.",
      "ItemId": "c1361416-53ca-4d67-974a-60f5335cdaf1"
    },
    {
      "Type": "Customs",
      "Error": "Please supply your VAT status.",
      "ItemId": "c1361416-53ca-4d67-974a-60f5335cdaf1"
    },
    {
      "Type": "Customs",
      "Error": "Please supply details of your parcel's country of manufacture.",
      "ItemId": "c1361416-53ca-4d67-974a-60f5335cdaf1"
    },
    {
      "Type": "Customs",
      "Error": "Please supply details of your international parcel's contents.",
      "ItemId": "c1361416-53ca-4d67-974a-60f5335cdaf1"
    },
    {
      "Type": "Service",
      "Error": "A price could not be found for these specifications.",
      "ItemId": "c1361416-53ca-4d67-974a-60f5335cdaf1"
    }
  ]
}

EXAMPLE OF AN ORDER SPECIFYING CUSTOMS DATA

This is an international order request which properly specifies customs
information

View More
Plain Text


{
  "Items": [
    {
      "Id": "c1361416-53ca-4d67-974a-60f5335cdaf1",
      "CollectionDate": "2017-02-09T10:09:11.9730419+00:00",
      "Parcels": [
        {
          "Id": "c1361416-53ca-4d67-974a-60f5335cdaf1",
          "Height": 10,
          "Length": 10,
          "EstimatedValue": 10,
          "Weight": 1,
          "Width": 10,
          "DeliveryAddress": {
            "ContactName": "Gary Wilson",
            "Email": "g.wilson@yahoo.com",
            "Phone": "+4477777777777",
            "Organisation": "",
            "Property": "1",
            "Street": "S Brooklyn View Ln",
            "Locality": "",
            "Town": "South Jordan",
            "County": "UTah",
            "Postcode": "84095",
            "CountryIsoCode": "USA"
          },
          "ContentsSummary": "Slippers",
          // Additional details of contents provided
          "Contents": [
            {
              "Description": "Slippers",
              "Quantity": "1",
              "EstimatedValue": "10"
            }
          ]
        }
      ],
      "Service": "24h-example",
      "CollectionAddress": {
        "ContactName": "Test",
        "Email": "collection@example.com",
        "Phone": "+4477777777777",
        "Property": "11",
        "Street": "Saville St",
        "Town": "Malton",
        "County": "North Yorkshire",
        "Postcode": "YO17 7LL",
        "CountryIsoCode": "GBR"
      },
      // additional details for customs below
      "OriginCountry": "GBR",
      "ExportReason": "Sale",
      "VatStatus": "Individual"
    }
  ],
  "CustomerDetails": {
    "Email": "jj@yahoo.com",
    "Forename": "Joe",
    "Surname": "Joggs"
  }
}


EXTRAS


WHAT ARE EXTRAS ?

'Extras' are additional products which can be selected with your order. These
include parcel protection, delivery text messages, delivery signatures as well
as other options listed below. These might have an additional cost, be included
with your service, or be offered as a free optional product.:


WHICH EXTRAS CAN I HAVE?

The extras you can choose are returned on your quote response under
'AvailableExtras', as show on the example below. These are based on the courier
and type of service you have chosen, for example Print in Store is only
available on drop off services. Here are a few examples of other extras which
are available:

   
 * Sms
   
 * Signature
   
 * Cover
   
 * DeliveryGuarantee
   
 * ExtendedBaseCover
   
 * PrintInStore
   


HOW DO I GET A QUOTE WITH EXTRAS, LIKE TEXT MESSAGES?

When requesting a quote, you can choose to include the extras you need on the
'Extras' property.

View More
json


{
      "CollectionAddress": {
        "Country": "GBR"
      },
      "DeliveryAddress": {
        "Country": "GBR"
      },
      "Parcels": [
        {
          "Value": 150,
          "Weight": 1.5,
          "Length": 9,
          "Width": 8,
          "Height": 10
        }
      ],
      "Extras": [
        {
          "Type": "Sms"
        }
      ]
 }


HOW DO I GET PARCEL PROTECTION?

As above, you can request protection as an 'Extra'.

   
 * Including 'ExtendedBaseCover' will get a quote with the standard £20
   (depending on service) included protection.
   
 * Including 'Cover' will include protection to the value of your item, or
   maximum protection limit offered by the service - which ever is the lowest.
   
 * Including both extras will include the £20 protection and an additional cost
   for any protection above this value.
   

View More
json


{
      "CollectionAddress": {
        "Country": "GBR"
      },
      "DeliveryAddress": {
        "Country": "GBR"
      },
      "Parcels": [
        {
          "Value": 150,
          "Weight": 1.5,
          "Length": 9,
          "Width": 8,
          "Height": 10
        }
      ],
      "Extras": [
        {
          "Type": "ExtendedBaseCover"
        },
        {
          "Type": "Cover"
        }
      ]
}


WHAT ARE 'EXTRAS' AND 'AVAILABLEEXTRAS' ON A QUOTE RESPONSE?

Any extras which are available on the service, but not included on your initial
quote request, will be returned on the 'AvailableExtras' property of the quote
response. Any extras you include (like Sms in the example above) will be added
to the quote total price, and detailed on the 'Extras' property of the quote
response. The example below shows Sms as £0.30.

EXAMPLE OF A QUOTE WITH EXTRAS

View More
Plain Text


{
  "AvailableExtras": [
    {
      "Type": "Cover",
      "Price": 7.5,      
      "Vat": 1.5,      
      "Total": 9,      
      "Details": null            
    },
    {
      "Type": "DeliveryGuarantee",      
      "Price": 1.1,      
      "Vat": 0.22,      
      "Total": 1.32,      
      "Details": null      
    },
    {
      "Type": "ExtendedBaseCover",
      "Price": 0.2,      
      "Vat": 0.04,      
      "Total": 0.24,      
      "Details": {      
        "IncludedCover": "20.00",     
        "MaxWeight": "5.00"     
      }      
    }
  ],
  "Discount": 0,
  "Extras": [
    {
      "Amount": 0.3,
      "Type": "Sms"
    }
  ],
  ...
}


WEBHOOKS

We support multiple different types of webhooks / notifications based on events
which can occur on your account. We will post a specific payload for each
available event to an endpoint you specify. If a 200 response is not received,
we will keep retrying using a backoff algorithm until we get a 200 response or
hit our limit.


ENABLING WEBHOOKS

From the My Account page, go through the settings menu to the API credentials
page. Click to Edit the API credentials you want webhooks enabled for and scroll
down to the Webhooks section at the bottom. Fill in your URL details, and give
us a secret which can be used to verify a notification we send you (see
Verifying Webhooks for details).


WEBHOOK FORMAT

All the webhook events are wrapped in the following json class :

Plain Text


{
     "Id":"e0363b4a-aead-4dd5-bcc5-73793ad49974",
     "Timestamp": "2018-08-30T11:37:03.6386334+00:00",
     "Signature": "ac6cff923966b1dfcb4560e32d9a6683ea9b1c1f41aa3ad9c8e36658f7389703",
     "Type": "Example",
     "Payload": {
       ...
     }
 }

Field Type Description Id string (guid) An autogenerated identifier for this
webhook Timestamp datetime A timestamp for when this webhook was sent Signature
string The HEX signature generated for this webhook (see how to verify) Type
string The type of webhook Payload object The payload for the webhook, this
varies depending on the type of webhook


SUPPORTED WEBHOOK PAYLOADS


TRACKING

Plain Text


{
  ...
  "Type":"Tracking",
  "Payload" : {
    "OrderLineId": 1234567,
    "Timestamp": "2018-08-28T09:36:07.4805536+00:00",
    "StatusCode": "ABC",
    "StatusDescription": "Handed to Customer",
    "TrackingStage": "Delivered"
  }
}

Field Type Description OrderLineId Int This is our number Timestamp datetime A
timestamp of when this tracking stage was entered StatusCode string Courier's
specific tracking status StatusDescription string Description from the courier
TrackingStage string The is one of our normalised tracking stages

TrackingStage can be one of the following :

Stage Description DroppedOff [only drop off services] We have received a drop of
scan from the drop shop Collected Parcel has been collected from your collection
point (home or dropshop) InTransit Parcel is in transit from collection point to
depot AtDepot Parcel has been scanned in at the depot DeliveryScheduled Parcel
has been scheduled for delivery from depot Delivered Parcel has been delivered


CASES

We will raise case events with the following format

View More
Plain Text


{
  ...
  "Type":"Case",
  "Payload": {
    "OrderLineId":"1234",
    "CustomerReference" : "ab1234",
    "CaseId" : "12345",
    "Reference" : "ABER343434",
    "Status" : "Approved",
    "CaseType" : "Claim"
  }
}

Field Type Description OrderLineId Int This is our number CustomerReference
string This is an optional field you can specify in our API orders endpoint
CaseId int The unique identifier for this case Reference string This is an
optional field you can specify in our API orders endpoint Status string The
status the claim has entered CaseType string The type of case, can be Enquiry or
Claim


VERIFYING WEBHOOKS

All our events are signed with a SHA256 signature of the header fields Id,
Timestamp and Type.

The following is sudo code showing how to verify the hash :

csharp


var toHash = Id + ":" + Timestamp.ToString("yyyy-MM-dd HH:mm:ss") + ":" + Type;
  var hexhash = GetHash(toHash, secret);

The following is a implementation in c#

View More
csharp


public static void Main()
    {
    /\\\\\\\\\\\\\\\\\\\\\\\\\\\* This is an example of a webhook  \\\\\\\\\\\\\\\\\\\\\\\\\\\*/
        var payload = new {
            Id = "33bb3c63-c2ec-4b69-8db3-301fa8cfe024",
            Timestamp = new DateTime(2018,01,01),
            Type="Case"
        };
        string toHash = payload.Id + ":" + payload.Timestamp.ToString("yyyy-MM-dd HH:mm:ss") + ":" + payload.Type;
        string secret = "abcd"; /\\\\\\\\\\\\\\\\\\\\\\\\\\\* your webhook secret \\\\\\\\\\\\\\\\\\\\\\\\\\\*/
        string hexhash = GetHash(toHash, secret);
        Console.WriteLine(hexhash);
    }
    private static string GetHash(string text, string key)
    {
        var textBytes = Encoding.UTF8.GetBytes(text);
        var keyBytes = Encoding.UTF8.GetBytes(key);
        byte[] hashBytes;
        using (HMACSHA256 hash = new HMACSHA256(keyBytes))
        {
            hashBytes = hash.ComputeHash(textBytes);
        }
        return BitConverter.ToString(hashBytes).Replace("-", "").ToLower();
    }


SECURING YOUR ENDPOINT

We recommend that you verify your webhooks when received. We also recommend that
you don't allow replaying of webhooks with the same id (replay attacks) and that
you discard any webhooks received outside of a sensible time range based on the
timestamp.


ENDPOINTS


SANDBOX URLS

Type Url API Docs https://sandbox.parcel2go.com/api/docs Swagger
https://sandbox.parcel2go.com/api/swagger Auth Base
https://sandbox.parcel2go.com/auth Auth Token Endpoint
https://sandbox.parcel2go.com/auth/connect/token Auth OpenId Config (well-known
config) https://sandbox.parcel2go.com/auth/.well-known/openid-configuration


LIVE URLS

Type Url API Docs https://www.parcel2go.com/api/docs Swagger
https://www.parcel2go.com/api/swagger Auth Base https://www.parcel2go.com/auth
Auth Token Endpoint https://www.parcel2go.com/auth/connect/token Auth OpenId
Config (well-known config)
https://www.parcel2go.com/auth/.well-known/openid-configuration


FUNCTIONAL DIFFERENCES BETWEEN LIVE AND SANDBOX ENVIRONMENTS

Please note that the Live and Sandbox environments of our API may exhibit
functional differences in certain areas. While we strive to maintain parity
between these environments, there are specific scenarios where the Sandbox
environment may not fully replicate the functionality or behaviour of the Live
environment.

It is important to understand that the Sandbox environment is primarily designed
for development, testing, and experimentation purposes. While it provides a safe
and isolated space to validate your integration with our API, it may not
accurately reflect the production-ready behaviour you can expect in the Live
environment.

To ensure a seamless transition from Sandbox to Live, we recommend thoroughly
testing your implementation in both environments and identifying any
discrepancies. It is crucial to consider the following points:

   
 * Features and Limitations: Some features available in the Live environment may
   not be fully supported or available in the Sandbox environment. Conversely,
   the Sandbox environment might provide additional features or capabilities
   that are not present in the Live environment.
   
 * Data Integrity: While the Sandbox environment utilises sample or simulated
   data, the Live environment operates with actual production data.
   Consequently, data integrity, accuracy, and consistency may differ between
   the two environments
   
 * External Integrations: If your API implementation relies on external services
   or integrations, keep in mind that the behaviour of these integrations may
   not be identical across the Sandbox and Live environments. Verify and test
   these integrations thoroughly to ensure their compatibility in both
   environments
   


TERMS AND CONDITIONS

The Terms and Conditions can be found at the following URL:
https://www.parcel2go.com/api/docs/articles/terms.html