Shipping Guide API 2.0

Introduction

The Shipping Guide API 2.0 (Fraktguiden) for provides you with different shipping alternatives for your shipments. If you request applicable shipping alternatives with all relevant details you will receive an object with the following data:

  • Prices
  • Estimated delivery times
  • GUI information

The API returns the recommended way to present these shipping alternatives, meaning that the actual response can easily be shown in a web-shop checkout without any sorting or filtering and with human readable product texts.

The Shipping Guide API 2.0 has both a REST and a SOAP interface. The REST interface only supports single consignments, while the SOAP interface can be used for multiple consignments.

Why upgrade?

  • Unified request and response model: Due to backward compatibility, existing SOAP API versions had too many ways of requesting to Shipping Guide could be always confusing for clients. This has been simplified in the new version with one unified way of requesting to Shipping Guide.
  • Better error handling for both SOAP and REST: The new version of API gives ability to handle error in a much simpler way.
  • Ability to fetch agreement prices specific to a product on REST: Now you can specify multiple products and along with multiple customer number in a single REST request. How?
  • Some improvements to our service offering are planned for 2018-19. More info about upcoming changes will follow to all our partners. Future services will be supported by this new API-version in addition to other improvements. Note that our old versions of API’s will not support future changes in our service offering.

How to upgrade

Now that Shipping Guide API 2.0 is out you might be wondering how to upgrade to it. The Upgrade to version 2.0 will help you on your way to version 2.0 of the Shipping Guide API.

Getting started

This guide will walk you through getting shipment alternatives for your first consignment using Shipping Guide API. In this example we will be calling the SOAP interface with a HTTP client and query for the product SERVICEPAKKE and PA_DOREN for two packages.

Before you start

Before you can begin using the new API you’ll have to do the following:

1. Get your API key from Mybring

To make API requests you will need an API key.

To do this click the button below, which sends you to your “Settings and API” page in Mybring profile administration. Scroll down to the “API key” section. Your generated API key which you will use to authenticate your requests can be found here.


Get API key

2. Add authentication headers

A description of the headers can be found in Getting Started / Authentication.

3. Add additional headers

Since we’re using the SOAP (1.1) interface we’ll have to add the following header:

  • Content-type: text/xml

Most SOAP libraries will do this for you.

4. Add the body to the request

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

<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/"
                  xmlns:ns="http://www.bring.no/logistics/shippingguide/2.0">
    <soapenv:Header/>
    <soapenv:Body>
        <ns:ShippingGuideRequest xmlns:ns="http://www.bring.no/logistics/shippingguide/2.0">
            <ns:Language>no</ns:Language>
            <ns:WithPrice>true</ns:WithPrice>
            <ns:WithExpectedDelivery>false</ns:WithExpectedDelivery>
            <ns:WithGuiInformation>true</ns:WithGuiInformation>
            <ns:NumberOfAlternativeDeliveryDates>0</ns:NumberOfAlternativeDeliveryDates>
            <ns:EDI>true</ns:EDI>
            <ns:PostingAtPostoffice>true</ns:PostingAtPostoffice>
            <ns:Trace>true</ns:Trace>
            <ns:Consignments>
              <ns:Consignment id="101">
                  <ns:Products>
                      <ns:Product>
                          <ns:Id>SERVICEPAKKE</ns:Id>
                      </ns:Product>
                  </ns:Products>
                  <ns:FromCountryCode>NO</ns:FromCountryCode>
                  <ns:FromPostalCode>0015</ns:FromPostalCode>
                  <ns:ToCountryCode>NO</ns:ToCountryCode>
                  <ns:ToPostalCode>5518</ns:ToPostalCode>
                  <ns:ShippingDate>
                      <ns:Year>2016</ns:Year>
                      <ns:Month>10</ns:Month>
                      <ns:Day>10</ns:Day>
                      <ns:Hour>10</ns:Hour>
                      <ns:Minute>0</ns:Minute>
                  </ns:ShippingDate>
                  <ns:AdditionalServices>
                      <ns:AdditionalService>
                          <ns:Id>EVARSLING</ns:Id>
                      </ns:AdditionalService>
                      <ns:AdditionalService>
                          <ns:Id>POSTOPPKRAV</ns:Id>
                      </ns:AdditionalService>
                      <ns:AdditionalService>
                          <ns:Id>SOSIAL_KONTROLL</ns:Id>
                      </ns:AdditionalService>
                  </ns:AdditionalServices>
                  <ns:Packages>
                      <ns:Package id="10">
                          <ns:Height>10</ns:Height>
                          <ns:Width>10</ns:Width>
                          <ns:Length>10</ns:Length>
                          <ns:GrossWeight>50</ns:GrossWeight>
                      </ns:Package>
                      <ns:Package id="11">
                          <ns:Height>10</ns:Height>
                          <ns:Width>10</ns:Width>
                          <ns:Length>10</ns:Length>
                          <ns:GrossWeight>50</ns:GrossWeight>
                      </ns:Package>
                      <ns:Package id="12">
                          <ns:Height>11</ns:Height>
                          <ns:Width>10</ns:Width>
                          <ns:Length>10</ns:Length>
                          <ns:GrossWeight>50</ns:GrossWeight>
                      </ns:Package>
                  </ns:Packages>
              </ns:Consignment>
            </ns:Consignments>
        </ns:ShippingGuideRequest>
    </soapenv:Body>
</soapenv:Envelope>

5. Submit the request

Post your request to


  https://api.bring.com/shippingguide/api/ws

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

<SOAP-ENV:Envelope xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/">
    <SOAP-ENV:Header/>
    <SOAP-ENV:Body>
        <ns2:ShippingGuideResponse xmlns:ns2="http://www.bring.no/logistics/shippingguide/2.0">
            <ns2:Consignments>
                <ns2:Consignment consignmentId="101">
                    <ns2:Products>
                        <ns2:Product>
                            <ns2:Id>SERVICEPAKKE</ns2:Id>
                            <ns2:ProductionCode>1202</ns2:ProductionCode>
                            <ns2:GuiInformation>
                                <ns2:SortOrder>11</ns2:SortOrder>
                                <ns2:MainDisplayCategory>Pakke</ns2:MainDisplayCategory>
                                <ns2:SubDisplayCategory>Til private</ns2:SubDisplayCategory>
                                <ns2:DisplayName>Klimanøytral Servicepakke</ns2:DisplayName>
                                <ns2:ProductName>Klimanøytral Servicepakke</ns2:ProductName>
                                <ns2:DescriptionText>Pakken kan spores og utleveres på ditt lokale hentested.</ns2:DescriptionText>
                                <ns2:HelpText>Klimanøytral Servicepakke 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.</ns2:HelpText>
                                <ns2:ShortName>Klimanøytral Servicepakke</ns2:ShortName>
                                <ns2:ProductURL>http://www.bring.no/sende/pakker/private-i-norge/hentes-pa-posten</ns2:ProductURL>
                                <ns2:DeliveryType>Hentested</ns2:DeliveryType>
                                <ns2:MaxWeightInKgs>35</ns2:MaxWeightInKgs>
                            </ns2:GuiInformation>
                            <ns2:Price>
                                <ns2:ListPrice currencyCode="NOK">
                                    <ns2:PriceWithoutAdditionalServices>
                                        <ns2:AmountWithoutVAT>239.00</ns2:AmountWithoutVAT>
                                        <ns2:VAT>59.75</ns2:VAT>
                                        <ns2:AmountWithVAT>298.75</ns2:AmountWithVAT>
                                    </ns2:PriceWithoutAdditionalServices>
                                    <ns2:PriceWithAdditionalServices>
                                        <ns2:AmountWithoutVAT>239.00</ns2:AmountWithoutVAT>
                                        <ns2:VAT>59.75</ns2:VAT>
                                        <ns2:AmountWithVAT>298.75</ns2:AmountWithVAT>
                                    </ns2:PriceWithAdditionalServices>
                                </ns2:ListPrice>
                            </ns2:Price>
                            <ns2:ExpectedDelivery>
                                <ns2:WorkingDays>2</ns2:WorkingDays>
                                <ns2:UserMessage/>
                                <ns2:FormattedExpectedDeliveryDate>12.10.2018</ns2:FormattedExpectedDeliveryDate>
                                <ns2:ExpectedDeliveryDate>
                                    <ns2:Year>2018</ns2:Year>
                                    <ns2:Month>10</ns2:Month>
                                    <ns2:Day>12</ns2:Day>
                                </ns2:ExpectedDeliveryDate>
                                <ns2:AlternativeDeliveryDates/>
                            </ns2:ExpectedDelivery>
                        </ns2:Product>
                        <ns2:Product>
                            <ns2:Id>PA_DOREN</ns2:Id>
                            <ns2:ProductionCode>1736</ns2:ProductionCode>
                            <ns2:GuiInformation>
                                <ns2:SortOrder>41</ns2:SortOrder>
                                <ns2:MainDisplayCategory>Pakke</ns2:MainDisplayCategory>
                                <ns2:SubDisplayCategory>Til private</ns2:SubDisplayCategory>
                                <ns2:DisplayName>På Døren</ns2:DisplayName>
                                <ns2:ProductName>På Døren</ns2:ProductName>
                                <ns2:DescriptionText>Pakken kan spores og leveres hjem til deg mellom kl. 17-21. Sjåføren ringer 30-60 min før ankomst.</ns2:DescriptionText>
                                <ns2:HelpText>På Døren leveres hjem til mottaker mellom kl. 17 og 21. Mottaker varsles i god tid om forventet utleveringsdag via SMS eller e-post, i tillegg til nytt varsel når sendingen er lastet på bil for utkjøring samme kveld. Sjåføren ringer mottaker 30-60 minutter før ankomst. Mottaker kan endre leveringsdag når pakken spores (gjelder ikke lokalpakker). Dersom sendingen ikke kan leveres, blir den sendt til mottakers lokale hentested (postkontor eller Post i Butikk). Sendingen kan spores ved hjelp av sporingsnummeret.</ns2:HelpText>
                                <ns2:ShortName>På Døren</ns2:ShortName>
                                <ns2:ProductURL>http://www.bring.no/sende/pakker/private-i-norge/hjemlevering</ns2:ProductURL>
                                <ns2:DeliveryType>Dør</ns2:DeliveryType>
                                <ns2:MaxWeightInKgs>35</ns2:MaxWeightInKgs>
                            </ns2:GuiInformation>
                            <ns2:Price>
                                <ns2:ListPrice currencyCode="NOK">
                                    <ns2:PriceWithoutAdditionalServices>
                                        <ns2:AmountWithoutVAT>270.00</ns2:AmountWithoutVAT>
                                        <ns2:VAT>67.50</ns2:VAT>
                                        <ns2:AmountWithVAT>337.50</ns2:AmountWithVAT>
                                    </ns2:PriceWithoutAdditionalServices>
                                    <ns2:PriceWithAdditionalServices>
                                        <ns2:AmountWithoutVAT>270.00</ns2:AmountWithoutVAT>
                                        <ns2:VAT>67.50</ns2:VAT>
                                        <ns2:AmountWithVAT>337.50</ns2:AmountWithVAT>
                                    </ns2:PriceWithAdditionalServices>
                                </ns2:ListPrice>
                            </ns2:Price>
                            <ns2:Warnings>
                                <ns2:Warning>
                                    <ns2:code>NO_EXPECTED_DELIVERY</ns2:code>
                                    <ns2:description>Expected delivery date is not available</ns2:description>
                                </ns2:Warning>
                            </ns2:Warnings>
                        </ns2:Product>
                    </ns2:Products>
                </ns2:Consignment>
            </ns2:Consignments>
        </ns2:ShippingGuideResponse>
    </SOAP-ENV:Body>
</SOAP-ENV:Envelope>

If you want to know more about the fields you can have a look at the XSD linked from the section Request and response structure

Shipping Guide topics

If you want to know more about corner cases/topics/etc, then Let’s talk about Shipping Guide

Handle API errors

When using the Shipping Guide it is important to handle errors 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 or SOAP fault with a message in the body

    For REST we follow general convention of HTTP status codes.
    For SOAP we give out detailed error decription along with an error code which can be parsed programmatically.

    <SOAP-ENV:Envelope xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/">
        <SOAP-ENV:Header/>
        <SOAP-ENV:Body>
            <SOAP-ENV:Fault>
                <faultcode>SOAP-ENV:Client</faultcode>
                <faultstring>FG_INPUT_010 Number of alternative delivery dates must be numeric and less than 10 [errorId 2806bbda-1df0-4b1b-b008-1068f5c57f06]
                </faultstring>
                <detail>
                    <code>FG_INPUT_010</code>
                    <description>Error number of alternative deliverydates</description>
                </detail>
            </SOAP-ENV:Fault>
        </SOAP-ENV:Body>
    </SOAP-ENV:Envelope>
    

    Possible error codes can be found here

  • An error object in the response that is on product level

    When we are not able to process one of the product requested, we will respond with a error on product level. Details of possible error codes are documented in XSD and WDSL itself, making it easier for clients to parse it.

Request and response structure

If you request shipping alternatives via the API your request and response will have to comply with the following schemas:

SOAP

https://api.bring.com/shippingguide/api/ws/shipping-guide-20.xsd

https://api.bring.com/shippingguide/api/ws/shippingguide-20.wsdl

Versioning

The Shipping Guide makes an effort to always be backwards compatible regarding data format for requests and responses. To achieve this, namespace schema versioning is used in the request for webservices, indicating which version the client is on and what data-format the client expects in the result. For REST, 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.

Improve performance

To have better performance of the api

  • Request can be limited to have only the products needed since the response time of some products can be slow as compared to others
  • If the request is only to find the lead time / prices of different product, 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 shipments request can be part of separate request

Overview of endpoints

Base URL

https://api.bring.com/shippingguide
Method Endpoint Usage
GET /v2/products Get shipment prices
GET /v2/products/price Use this endpoint to get price. The request parameters are the same as for [Get shipment prices and estimated delivery](/api/shipping-guide_v2/#get-shipment-prices-and-estimated-delivery)
GET /v2/products/expectedDelivery Get estimated delivery time
POST /api/ws Use this endpoint to get expected delivery, product categories and additional information.

Get shipment prices and estimated delivery

Use this endpoint to get expected delivery, product categories and additional information.

URL

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

Request params

Header name Type Description
X-MyBring-API-Uid string

Required. Your Mybring login ID

X-MyBring-API-Key string

Required. Your user’s API key

Accept string

Required. Specify request format (application/json, application/xml)

Query param Type Description
fromcountry string

Required. Sender country code

tocountry string

Required. Receiver country code

frompostalcode string

Required. Sender postal code

topostalcode string

Required. Receiver postal code

product string

Required. List of products requested. Multiple products can be requested in a single request. Requested product can also be specified with a customer number separated with delimiter (:). For example CARGO:CARGO-123456

date date

Optional. Shipping date


Example: 2018-11-18
time date

Optional. Shipping time


Example: 12:30
weight integer

Optional. Package weight in grams

volumeindm3 integer

Optional. Package volume in dm3

loadingmeter double

Optional. Package loading meters

width integer

Optional. Package width in cm

length integer

Optional. Package length in cm

height integer

Optional. Package height in cm

numberofpallets integer

Optional. Number of pallets.

nonstackable boolean

Optional. Set to true if you know that pallet would be non-stackable

edi boolean

Optional. Tells if the parcel will be registered using EDI when being booked. It may affect price and which products are available


Default value: true
postingatpostoffice boolean

Optional. Tells whether the parcel is delivered at a post office when it is shipped. A surcharge will be applied for SERVICEPAKKE and BPAKKE_DOR-DOR

additionalservice string

Optional. Additional service. Multiple additional services can be requested by repeating this parameter

customernumber string

Optional. Lets you specify which customer number to use in the request. If specified and product is not supplied with delimited customer number, then it will be applied on all request products


Example: CARGO-123456
language string

Optional. Language used for the product texts


Default value: no
volumeSpecial boolean

Optional. True if the package has a shape that requires special handling

incoterms string

Optional. Terms of delivery

unnumber integer

Optional. Code for dangerous goods

payer string

Optional. Payer type. Possible values are SENDER, RECEIVER or THIRD_PARTY

Responses

HTTP status code 200

A successful response

HTTP status code 400

This can mean that a required field or parameter has not been provided, the value supplied is invalid, or the combination of provided fields is invalid.

HTTP status code 401

A failed response when the request is unauthenticated

Get shipment prices

Use this endpoint to get prices. The request parameters are the same as for Get shipment prices and estimated delivery

URL

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

Get expected delivery times

Use this endpoint to get expected delivery. The request parameters are the same as for Get shipment prices and estimated delivery

URL

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

Get shipment prices and estimated delivery

Use this endpoint to get expected delivery, product categories and additional information.

URL

https://api.bring.com/shippingguide/api/ws

Request params

Header name Type Description
X-MyBring-API-Uid string

Required. Your Mybring login ID

X-MyBring-API-Key string

Required. Your user’s API key

Accept string

Required. Specify request format (application/json, application/xml)