Using Shipping Guide API

Performance

To have better performance of the API:

Requests can be limited to have only the services needed since the response time of some services can be slow compared to others
If the request is only to find the lead time / prices of different services, the flag for withExpectedDelivery / withPrices should be set to true and others can be set to false. In case of REST these are different endpoints.
For net prices, requests should include customer number and correct package details
Request can include limited number of consignments in each request for quick response.
New shipment request can be part of separate requests.

Versioning

The Shipping Guide makes an effort to always be backwards compatible regarding data format for requests and responses. To achieve this, Versioning is defined as part of endpoint itself.

Important: All clients must accept new (unknown) elements in the response. E.g. unknown elements should be ignored. Also, new error codes and warning codes could be added as well. The client framework used by client must not crash when unknown elements or new code values are are encountered.

When incompatible changes in the schema are made (other than addition of new elements), the namespace versioning will be updated accordingly. The new schema is used at the same endpoint URL as before for webservices. Old schema versions will be shut down some time in the future, so its recommended always updating to the latest version.

Calling Shipping Guide API

This guide will walk you through getting shipment alternatives for your first consignment. We will be calling the REST interface with a HTTP client and query for the service 5800 and PA_DOREN for two packages.

1. Add additional headers

For the POST requests, Add the following header:

Content-type: application/json

2. Add the body to the request

There are several ways you can control the output of your request. The following elements controls what the API will calculate.

Element name	Description
`withPrice`	Controls whether prices should be calculated. Default `true`
`withExpectedDelivery`	Controls whether lead times should be calculated. Default `true`
`withGuiInformation`	Return detailed information about requested service. Default `true`
`withEstimatedDeliveryTime`	Extended lead time information, including predicted arrival time at pickup point. Only supported for a limited set of services. Default `false`
`numberOfAlternativeDeliveryDates`	Number of alternative delivery dates to be suggested. Default `0`, maximum `9`
`withEnvironmentalData`	Return environmental data about fossil free and electric transportation used on different transport legs
`language`	Language in which human readable message should be returned. Supported languages are `NO`, `DK`, `SE` and `EN`
`edi`	Should the parcel be registered using EDI when shipped. Note that this flag may affect price and which services are available. Default `true`
`postingAtPostoffice`	Will the parcel be delivered at a post office when shipped. Default `false`

In this request we will query prices and expected delivery time for the service 5800 for a single package being sent from the postal code 0015 to 5518 in Norway.

REST (POST)

{  
  "language": "no",
  "withPrice": true,
  "withExpectedDelivery": false,
  "withGuiInformation": true,
  "numberOfAlternativeDeliveryDates": 0,
  "edi": true,
  "postingAtPostOffice": true,
  "trace": true,
  "consignments": [
    {
      "id": 101,
      "products": [
        {
          "id": "5800"
        }
      ],
      "fromCountryCode": "NO",
      "toCountryCode": "NO",
      "fromPostalCode": "0015",
      "toPostalCode": "5518",
      "addressLine": "Testsvingen 2",
      "shippingDate": {
        "day": "10",
        "hour": "10",
        "minute": "0",
        "month": "10",
        "year": "2016"
      },
      "packages": [
        {
          "id": "10",
          "length": 10,
          "width": 10,
          "height": 10,
          "grossWeight": 50
        },
        {
          "id": "11",
          "length": 10,
          "width": 10,
          "height": 10,
          "grossWeight": 50
        },
        {
          "id": "12",
          "length": 11,
          "width": 10,
          "height": 10,
          "grossWeight": 50
        }        
      ],
      "additionalServices": [
        {
          "id": "EVARSLING"
        },
        {
          "id": "POSTOPPKRAV"
        }       
      ]
    }
  ]
}

3. Submit the request

Post your request to

https://api.bring.com/shippingguide/v2/products

The response may have changed since it was documented but you will get a response that looks something like this:

{
  "traceMessages": [],
  "consignments": [
    {
      "products": [
          {
              "id": "5800",
              "productionCode": "1202",
              "guiInformation": {
                  "sortOrder": "0",
                  "mainDisplayCategory": "Pakke",
                  "subDisplayCategory": "Til privatpersoner",
                  "trackable": false,
                  "logo": "POSTEN",
                  "logoUrl": "https://www.qa.mybring.com/shipping-guide/assets/img/Posten_logo.svg",
                  "displayName": "Til hentested",
                  "productName": "Pakke til hentested",
                  "descriptionText": "Pakken kan spores og utleveres på ditt lokale hentested.",
                  "helpText": "Pakke til hentested leveres til mottakers lokale hentested (postkontor eller Post i Butikk). Mottaker kan velge å hente sendingen på et annet hentested enn sitt lokale. Mottaker varsles om at sendingen er ankommet via SMS, e-post eller hentemelding i postkassen. Sendingen kan spores ved hjelp av sporingsnummeret.",
                  "shortName": "Pakke til hentested",
                  "deliveryType": "Hentested",
                  "maxWeightInKgs": "35"
              },
              "price": {
                  "listPrice": {
                      "priceWithoutAdditionalServices": {
                          "amountWithoutVAT": "750.96",
                          "vat": "187.74",
                          "amountWithVAT": "938.70"
                      },
                      "additionalServices": [
                          {
                              "additionalServiceId": "EVARSLING",
                              "additionalServiceDescription": "",
                              "additionalServicePrice": {
                                  "amountWithoutVAT": "0.00",
                                  "vat": "0.00",
                                  "amountWithVAT": "0.00"
                              },
                              "additionalServiceCodeFromProductionSystem": "1091"
                          },
                          {
                              "additionalServiceId": "POSTOPPKRAV",
                              "additionalServiceDescription": "",
                              "additionalServicePrice": {
                                  "amountWithoutVAT": "65.00",
                                  "vat": "16.25",
                                  "amountWithVAT": "81.25"
                              },
                              "additionalServiceCodeFromProductionSystem": "2000"
                          }
                      ],
                      "priceWithAdditionalServices": {
                          "amountWithoutVAT": "815.96",
                          "vat": "203.99",
                          "amountWithVAT": "1019.95"
                      },
                      "currencyCode": "NOK"
                  }
              }
          }
      ]
    }
  ],
  "uniqueId": "9944a207-82ee-464f-bb55-b77eb836adc2"
}

Error and warning handling

Errors

Errors should be handled gracefully. Your users should still be able to order even if the Shipping Guide API returns an error or if there is an error establishing a connection to the API.

The Shipping Guide API return two levels of error information:

HTTP error codes(We follow general convention of HTTP status codes.)
An error object in the response that is on service level

When we are not able to process one of the service requested, we will respond with a error on service level.

No applicable services found

When no services are applicable for the request you’ve made, an empty resultset is returned. Reasons can be that the shipment was too large or too small, or the requested shipment was outside the coverage area of the requested services. Your code should handle these cases, i.e. an empty result, and should not fail because of this.

To fix this, you could e.g. use a Cargo product for large shipments, or you could request other services and see which ones that fit your need and find your service by using What would you like to send?

Additional service XXX is not applicable for product YYY

If a requested additional service is not supported on requested product, API will just ignore that additional service for price calculation and return info as a trace message. Supported list of value added services on services can be found in the section Value added Services.

Warnings

Ideally, clients should not parse warning codes for any logic as they are bound to change and supposed to be treated as informational data. Warnings are sent out when Shipping Guide is able to validate the request but missed some part of response, for example price or lead time, due to unavailability of external systems.

Warning codes are documented in xsd as well.