developer

Shipping Guide API 2.0

Shipping Guide API 1.0 will finally be decomissoned on 01.07.2021

3 years ago, Shipping Guide API 2.0 was launched. Since then, schemas belonging to 1.0 have been phased out one by one. The last active schema, 11, will be decomissioned on 01.07.2021. If you haven't upgraded to Shipping Guide 2.0 yet, we strongly recommend to do that as soon as possible, and latest by 01.07.2021.

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 service 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.

NOTE:

  • Any new users created post launch date 28-may-2020 attempting to request agreement prices by using old versions of Shipping Guide API, will be provided with an error message referring to the latest version.

  • Any Shipping Guide requests for old phase 1 services without customer number specified, will return the corresponding revised service after 01.10.2020.

Versioning

Upgrade from previous version

Shipping Guide API 2.0 is a replacement for the original API that is now deprecated. If needed, can you you still read the documentation for the old version of the Shipping Guide API.

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.

Why upgrade?

  • Unified request and response model: Due to backwards compatibility, existing SOAP API versions had too many ways of requesting to Shipping Guide. 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 the ability to handle errors in a much simpler way.
  • Ability to fetch agreement prices specific to a service on REST: Now you can specify multiple services and multiple customer numbers in a single REST request.
  • 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.

Versioning strategy

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.

Authentication

To make API requests, you will need an API key from Mybring. Steps for getting a key and description of headers can be found on the general API Getting Started / Authentication page.

Example walkthrough

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 service SERVICEPAKKE and PA_DOREN for two packages.

1. 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.

2. Add the body to the request

In this request we will query prices and expected delivery time for the service 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:AddressLine>Testsvingen 12</ns:AddressLine>
                  <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: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>

3. 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

Error handling

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 description 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

  • 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. Details of possible error codes are documented in XSD and WDSL itself, making it easier for clients to parse it.

Improve performance

To have better performance of the api

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

Estimated arrival time for parcels

For the following Norwegian domestic parcel services you can now get extended leadtime information - the estimated arrival time.

  • Bedriftspakke (BPAKKE_DOR-DOR)
  • Pakke til bedrift (5000)
  • Klimanøytral Servicepakke (SERVICEPAKKE)
  • Pakke til hentested (5800)

Note: setting the actual shipping date in the Shipping Guide request is a prerequisite for getting the correct estimate back from the machine learning model, as the leadtime is always calculated from the day the parcel is handed in to Bring. In absence for a shipping date set by the user, the Shipping Guide API will default to “now”.

Parcels delivered to companies

For the services Bedriftspakke (BPAKKE_DOR-DOR) and Pakke til bedrift (5000), you can now get extended leadtime information - the estimated arrival time.

Earlier, we have just returned the expected delivery date when you request our Shipping Guide API to get leadtime for BPAKKE_DOR-DOR/5000. Now, based on a machine learning model gathering scanning data from deliveries made in Norway, we are also predicting the arrival window - i.e. when the parcel is expected to arrive at the recipient address. If you are already presenting expected delivery date in your checkout, we strongly recommend that you consider increasing the value by also including the predicted arrival window.

The estimated arrival window is returned automatically as long as the WithExpectedDelivery flag is set to true. If we for some reason are unable to predict the arrival window, the expected delivery date will still be returned.

The arrival window is returned as time slots in the API response:

<ns2:ExpectedDelivery>
    <ns2:WorkingDays>1</ns2:WorkingDays>
    <ns2:UserMessage/>
    <ns2:FormattedExpectedDeliveryDate>29.01.2021</ns2:FormattedExpectedDeliveryDate>
    <ns2:ExpectedDeliveryDate>
        <ns2:Year>2021</ns2:Year>
        <ns2:Month>1</ns2:Month>
        <ns2:Day>29</ns2:Day>
        <ns2:TimeSlots>
            <ns2:TimeSlot>
                <ns2:StartTime>
                    <ns2:Hour>9</ns2:Hour>
                    <ns2:Minute>0</ns2:Minute>
                </ns2:StartTime>
                <ns2:EndTime>
                    <ns2:Hour>13</ns2:Hour>
                    <ns2:Minute>0</ns2:Minute>
                </ns2:EndTime>
            </ns2:TimeSlot>
        </ns2:TimeSlots>
    </ns2:ExpectedDeliveryDate>
    <ns2:AlternativeDeliveryDates/>
</ns2:ExpectedDelivery>

How to present the time window data in your checkout

We recommend to insert the start (X) and end (Y) time values into the following sentence:

  • NO: Pakken ankommer vanligvis mellom kl. X og Y
  • EN: The parcel usually arrives between X and Y

Together with the expected delivery date, we recommend the following implementation:

  • NO: Forventet levert XX.XX.20XX. Pakken ankommer vanligvis mellom kl. X og Y
  • EN: Expected delivered XX.XX.20XX. The parcel usually arrives between X and Y

Even though the API response schema supports minute granularity for start and end time, the minute value will always be set to 0. It is therefore sufficient to parse hours only.

Note that Bring cannot guarantee the arrival time for a specific parcel. The estimated arrival time indicates when, based on historical scanning data, the parcel normally will arrive at the recipient address.

Parcels going to pickup points

For the services Klimanøytral Servicepakke (SERVICEPAKKE) and Pakke til hentested (5800), you can now get extended leadtime information - the estimated arrival time for one or more pickup points.

Earlier, we have just returned the expected delivery date when you request our Shipping Guide API to get leadtime for SERVICEPAKKE/5800. Now, based on a machine learning model gathering scanning data from all pickup points in Norway, we are also predicting the arrival window - i.e. when the parcel is expected to arrive at a specific pickup point on that specific date. If you are already showing expected delivery date in your checkout, we strongly recomment that you consider increasing the value by also including the predicted arrival window.

To get the estimaterd arrival time for one or more pickup points, use the following new fields:

  • SOAP: WithEstimatedDeliveryTime, PickupPoints
  • REST: estimateddeliverytime, pickuppoints

Note: along with WithEstimatedDeliveryTime, make sure ensure the flag WithExpectedDelivery is also set to true, and remember that customerNumber must also be set.

There are two ways of using the functionality for estimated arrival time for pickup points in our Shipping Guide API - with or without the Pickup Point API:

Estimated arrival time for specified pickup points (w/ Pickup Point API)

You specify which pickup points you want us to return estimated arrival time for by including the relevant pickup point IDs in the Shipping guide request. Based on that, we return the start and end time of the expected arrival time window for each pickup point ID you have specified in the request. For a best possible customer experience, we strongly recommend that you use the functionality in combination with the Pickup Point API. For an example on how to do this, see the example request at the bottom of this page.

Estimated arrival time for the end users default pickup point(s) (w/o Pickup Point API)

In the absence of specified pickup point IDs, we take care of looking up the recipient´s default pickup point(s), based on its postal code. Based on that, we return the start and end time of the expected arrival time window for the recipient´s default pickup point(s). In this case, we will also provide the name of the default pickup point(s). To use the API this way, just omit the PickupPoints/pickuppoints element from the example at the page bottom. Please note that in some cases, the recipient´s postal code may have several default pickup points.

How to present the time window data in your checkout

We recommend to insert the start (X) and end (Y) time values into the following sentence:

  • NO: Pakken ankommer vanligvis mellom kl. X og Y
  • EN: The parcel usually arrives between X and Y

Together with the expected delivery date, we recommend the following implementation:

  • NO: Forventet levert XX.XX.20XX. Pakken ankommer vanligvis mellom kl. X og Y
  • EN: Expected delivered XX.XX.20XX. The parcel usually arrives between X and Y

Note that Bring cannot guarantee the arrival time for a specific parcel. The estimated arrival time indicates when, based on historical scanning data, the parcel normally will become available for pickup at a specific pickup point on that specific date. Also note that CustomerNumber is mandatory to set in order to get estimated delivery time.

Get unique expected delivery dates

Customers who want the x next possible delivery dates in the response, can use the numberOfAlternativeDeliveryDates. When using this parameter, the same delivery date might be returned several times (as several shipping dates might correspond to the same delivery date). To only get the unique alternative delivery dates use following field:

  • SOAP: withUniqueAlternateDeliveryDates
<withUniqueAlternateDeliveryDates>true</withUniqueAlternateDeliveryDates>
<numberOfAlternativeDeliveryDates>2</numberOfAlternativeDeliveryDates>
  • REST GET: uniqueAlternateDeliveryDates
uniqueAlternateDeliveryDates=true&numberofdeliverydates=2
  • REST POST: withUniqueAlternateDeliveryDates
"withUniqueAlternateDeliveryDates": true,
"numberOfAlternativeDeliveryDates": 2

Note: along with withUniqueAlternateDeliveryDates, make sure the numberOfAlternativeDeliveryDates is also set to some positive value.

Shipping Guide topics

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

Overview of endpoints

Base URL

https://api.bring.com/shippingguide
Method Endpoint Usage
GET /v2/products Get shipment prices and leadtime
POST /v2/products Get shipment prices and leadtime
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 same information as above REST API

Get shipment prices and estimated delivery

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

Measurements

For cargo services(5100, 5300, 9100, CARGO), Weight is mandatory and one of the Volume / Load Meter / Dimensions / Number of Pallets is mandatory.

Note: The prices for our revised services depends on volumetric weight: 5000, 5100, 5300, 5600, 5800, 4850 plus return services 9000, 9100, 9300 or 9600. For these services, dimensions (L/W/H) is needed to calculate the expected price correctly. Dimensions are also used to decide if handling fee or specialgoods fee will apply to the shipment. You might leave dimensions empty in your request, but be aware that returned prices might be incorrect.

The Post endpoint is in Beta stage.

URL

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

Request parameters

HTTP header Type Description
Accept string Required Specify request format (application/json, application/xml)
X-MyBring-API-Key string Required Your user’s API key
X-MyBring-API-Uid string Required Your Mybring login ID
Query param Type Description
additionalservice string Optional Additional service. Multiple value added services can be requested by repeating this parameter
addressline string Optional Specify address. This parameter can be maximum 35 character long. It will be for Bedriftspakke and På døren only.
Example: Testsvingen 12
customernumber string Optional Lets you specify which customer number to use in the request. If specified and service is not supplied with delimited customer number, then it will be applied on all request services
Example: CARGO-123456
date string Optional Shipping date
Example: 2018-11-18
edi boolean Optional Tells if the parcel will be registered using EDI when being booked. It may affect price and which services are available
Default value: true
estimateddeliverytime boolean Optional True if you want estimated delivery time of input pickup points. Eligible services are 5800 and SERVICEPAKKE.
fromcountry string Required Sender country code
frompostalcode string Required Sender postal code
height integer Optional Package height in cm
incoterms string Optional Terms of delivery
language string Optional Language used for the service texts
Default value: no
length integer Optional Package length in cm
loadingmeter double Optional Package loading meters
nonstackable boolean Optional Set to true if you know that pallet would be non-stackable
nonstandardcourierservice string Required Specify service code for customize courier services in the request. It will be for NonStandard Courier only.
Example: CDA
numberofdeliverydates integer Optional Number of alternative delivery dates to be suggested by API for request
numberofpallets integer Optional Number of pallets.
payer string Optional Payer type. Possible values are SENDER, RECEIVER or THIRD_PARTY
pickuppoints string Optional If pickup points are specified then estimated delivery time will be added in the response for them, when ‘estimateddeliverytime’ flag is True. If it is not specified, then default pickup point(s) for receiver’s postal code will be used. Eligible services are 5800 and SERVICEPAKKE. However we recommend to always specify pickup points for optimum results.
Example: 171102,124518
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
product string Required List of services requested. Multiple services can be requested in a single request. Requested service can also be specified with a customer number separated with delimiter (:). For example CARGO**:**CARGO-123456
time string Optional Shipping time
Example: 12:30
tocountry string Required Receiver country code
topostalcode string Required Receiver postal code
uniqueAlternateDeliveryDates boolean Optional True if you want unique expected delivery dates when requested with ‘numberofdeliverydates’.
unnumber integer Optional Code for dangerous goods
volumeSpecial boolean Optional True if the package has a shape that requires special handling
volumeindm3 integer Optional Package volume in dm3
weight integer Optional Package weight in grams
width integer Optional Package width in cm

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

URL

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

Request parameters

HTTP header Type Description
Content-Type string Required application/json
X-MyBring-API-Key string Required Your user’s API key
X-MyBring-API-Uid string Required Your Mybring login ID

Request body

{
  "consignments": [
    {
      "id": 1,
      "products": [
        {
          "id": "5000",
          "customerNumber": "XXXXXXXXX"
        }
      ],
      "packages": [
        {
          "length": 21,
          "width": 12,
          "height": 12,
          "grossWeight": 1000,
          "volumeInDm3": 1,
          "id": 1
        }
      ],
      "fromCountryCode": "NO",
      "fromPostalCode": "0120",
      "toCountryCode": "NO",
      "toPostalCode": "2003",
      "additionalServices": [
        "SIMPLE_DELiVERY"
      ],
      "shippingDate": {
        "year": "2021",
        "month": "01",
        "day": "13",
        "hour": "06",
        "minute": "54"
      }
    }
  ],
  "withPrice": true,
  "withExpectedDelivery": true,
  "withGuiInformation": false,
  "edi": true,
  "trace": true
}

Responses

HTTP status code 200

{
  "traceMessages": [],
  "consignments": [
    {
      "products": [
        {
          "id": "5000",
          "customerNumber": "XXXXXXXXX",
          "productionCode": "5000",
          "price": {
            "listPrice": {
              "priceWithoutAdditionalServices": {
                "amountWithoutVAT": "145.75",
                "vat": "36.44",
                "amountWithVAT": "182.19"
              },
              "priceWithAdditionalServices": {
                "amountWithoutVAT": "145.75",
                "vat": "36.44",
                "amountWithVAT": "182.19"
              },
              "currencyCode": "NOK"
            },
            "netPrice": {
              "priceWithoutAdditionalServices": {
                "amountWithoutVAT": "145.75",
                "vat": "36.44",
                "amountWithVAT": "182.19"
              },
              "priceWithAdditionalServices": {
                "amountWithoutVAT": "145.75",
                "vat": "36.44",
                "amountWithVAT": "182.19"
              },
              "currencyCode": "NOK"
            }
          },
          "expectedDelivery": {
            "workingDays": "1",
            "userMessage": "",
            "formattedExpectedDeliveryDate": "14.01.2021",
            "expectedDeliveryDate": {
              "year": "2021",
              "month": "1",
              "day": "14"
            },
            "alternativeDeliveryDates": []
          }
        }
      ]
    }
  ],
  "uniqueId": "cedb345a-759a-4892-9ee8-3672f5a5ebf5"
}

Get shipment prices

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

URL

                          GET
                          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

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

SOAP

The SOAP Body follows the same XML Schema Definition (XSD) as stated above.

Estimated delivery times

To get estimated delivery times in the response, set WithExpectedDelivery and WithEstimatedDeliveryTime to true in the request along with specifying PickupPoints

Request and response structure

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

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

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

URL

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

Request parameters

HTTP header Type Description
Accept string Required Specify request format (application/xml)
X-MyBring-API-Key string Required Your user’s API key
X-MyBring-API-Uid string Required Your Mybring login ID

Request body

<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>
    <ns:Language>en</ns:Language>
    <ns:WithPrice>true</ns:WithPrice>
    <ns:WithExpectedDelivery>true</ns:WithExpectedDelivery>
    <ns:WithGuiInformation>true</ns:WithGuiInformation>
    <ns:NumberOfAlternativeDeliveryDates>0</ns:NumberOfAlternativeDeliveryDates>
    <ns:EDI>true</ns:EDI>
    <ns:Trace>true</ns:Trace>
    <ns:PostingAtPostoffice>true</ns:PostingAtPostoffice>
    <ns:WithEstimatedDeliveryTime>true</ns:WithEstimatedDeliveryTime>
    <ns:Consignments>
      <ns:Consignment id="101">
        <ns:Products>
          <ns:Product>
            <ns:Id>SERVICEPAKKE</ns:Id>
            <ns:CustomerNumber>PARCELS_NORWAY-00000000001</ns:CustomerNumber>
          </ns:Product>
        </ns:Products>
        <ns:FromCountryCode>NO</ns:FromCountryCode>
        <ns:FromPostalCode>0150</ns:FromPostalCode>
        <ns:ToCountryCode>NO</ns:ToCountryCode>
        <ns:ToPostalCode>0550</ns:ToPostalCode>
        <ns:ShippingDate>
          <ns:Year>2020</ns:Year>
          <ns:Month>09</ns:Month>
          <ns:Day>10</ns:Day>
          <ns:Hour>15</ns:Hour>
          <ns:Minute>00</ns:Minute>
        </ns:ShippingDate>
        <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:Packages>
        <ns:AdditionalServices>
          <ns:AdditionalService>
            <ns:Id>EVARSLING</ns:Id>
          </ns:AdditionalService>
        </ns:AdditionalServices>
        <ns:PickupPoints>
          <ns:PickupPoint>
            <ns:Id>124518</ns:Id>
          </ns:PickupPoint>
        </ns:PickupPoints>
      </ns:Consignment>
    </ns:Consignments>
  </ns:ShippingGuideRequest>
</soapenv:Body>
</soapenv:Envelope>

Responses

HTTP status code 200

<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" uniqueId="a13c3fce-80a6-4e77-9497-0ca880deb93d">
      <ns2:TraceMessages/>
      <ns2:Consignments>
        <ns2:Consignment consignmentId="101">
          <ns2:Products>
            <ns2:Product>
              <ns2:Id>SERVICEPAKKE</ns2:Id>
              <ns2:CustomerNumber>PARCELS_NORWAY-00000000001</ns2:CustomerNumber>
              <ns2:ProductionCode>1202</ns2:ProductionCode>
              <ns2:GuiInformation>
                <ns2:SortOrder>11</ns2:SortOrder>
                <ns2:MainDisplayCategory>Parcels</ns2:MainDisplayCategory>
                <ns2:SubDisplayCategory>To private customers</ns2:SubDisplayCategory>
                <ns2:DisplayName>Climate-neutral Service Parcel</ns2:DisplayName>
                <ns2:ProductName>Climate-neutral Service Parcel</ns2:ProductName>
                <ns2:DescriptionText>The parcel can be tracked and is delivered to your local pickup point.</ns2:DescriptionText>
                <ns2:HelpText>Climate-neutral Service Parcel is delivered to the recipient's local pickup point (post office or post-in-shop). The recipient can choose to collect the shipment at a different pickup point than the local. The recipient is notified that the shipment has arrived via SMS, e-mail or letter notification in the mailbox. The shipment can be tracked by its tracking number.</ns2:HelpText>
                <ns2:ShortName>Climate-neutral Service Parcel</ns2:ShortName>
                <ns2:ProductURL>http://www.bring.no/english/sending/parcels/private-in-norway/to-be-collected-at-the-post-office</ns2:ProductURL>
                <ns2:DeliveryType>Pickup point</ns2:DeliveryType>
                <ns2:MaxWeightInKgs>35</ns2:MaxWeightInKgs>
              </ns2:GuiInformation>
              <ns2:Price>
                <ns2:ListPrice currencyCode="NOK">
                  <ns2:PriceWithoutAdditionalServices>
                    <ns2:AmountWithoutVAT>224.69</ns2:AmountWithoutVAT>
                    <ns2:VAT>56.17</ns2:VAT>
                    <ns2:AmountWithVAT>280.86</ns2:AmountWithVAT>
                  </ns2:PriceWithoutAdditionalServices>
                  <ns2:PriceWithAdditionalServices>
                    <ns2:AmountWithoutVAT>224.69</ns2:AmountWithoutVAT>
                    <ns2:VAT>56.17</ns2:VAT>
                    <ns2:AmountWithVAT>280.86</ns2:AmountWithVAT>
                  </ns2:PriceWithAdditionalServices>
                  <ns2:AdditionalServicePrices>
                    <ns2:AdditionalService>
                      <ns2:AdditionalServiceId>EVARSLING</ns2:AdditionalServiceId>
                      <ns2:AdditionalServiceDescription/>
                      <ns2:AdditionalServicePrice>
                        <ns2:AmountWithoutVAT>0.00</ns2:AmountWithoutVAT>
                        <ns2:VAT>0.00</ns2:VAT>
                        <ns2:AmountWithVAT>0.00</ns2:AmountWithVAT>
                      </ns2:AdditionalServicePrice>
                      <ns2:AdditionalServiceCodeFromProductionSystem>1091</ns2:AdditionalServiceCodeFromProductionSystem>
                    </ns2:AdditionalService>
                  </ns2:AdditionalServicePrices>
                </ns2:ListPrice>
                <ns2:NetPrice currencyCode="NOK">
                  <ns2:PriceWithoutAdditionalServices>
                    <ns2:AmountWithoutVAT>224.69</ns2:AmountWithoutVAT>
                    <ns2:VAT>56.17</ns2:VAT>
                    <ns2:AmountWithVAT>280.86</ns2:AmountWithVAT>
                  </ns2:PriceWithoutAdditionalServices>
                  <ns2:PriceWithAdditionalServices>
                    <ns2:AmountWithoutVAT>224.69</ns2:AmountWithoutVAT>
                    <ns2:VAT>56.17</ns2:VAT>
                    <ns2:AmountWithVAT>280.86</ns2:AmountWithVAT>
                  </ns2:PriceWithAdditionalServices>
                  <ns2:AdditionalServicePrices>
                    <ns2:AdditionalService>
                      <ns2:AdditionalServiceId>EVARSLING</ns2:AdditionalServiceId>
                      <ns2:AdditionalServiceDescription/>
                      <ns2:AdditionalServicePrice>
                        <ns2:AmountWithoutVAT>0.00</ns2:AmountWithoutVAT>
                        <ns2:VAT>0.00</ns2:VAT>
                        <ns2:AmountWithVAT>0.00</ns2:AmountWithVAT>
                      </ns2:AdditionalServicePrice>
                      <ns2:AdditionalServiceCodeFromProductionSystem>1091</ns2:AdditionalServiceCodeFromProductionSystem>
                    </ns2:AdditionalService>
                  </ns2:AdditionalServicePrices>
                </ns2:NetPrice>
              </ns2:Price>
              <ns2:ExpectedDelivery>
                <ns2:WorkingDays>1</ns2:WorkingDays>
                <ns2:UserMessage/>
                <ns2:FormattedExpectedDeliveryDate>11.09.2020</ns2:FormattedExpectedDeliveryDate>
                <ns2:ExpectedDeliveryDate>
                  <ns2:Year>2020</ns2:Year>
                  <ns2:Month>9</ns2:Month>
                  <ns2:Day>11</ns2:Day>
                </ns2:ExpectedDeliveryDate>
                <ns2:AlternativeDeliveryDates/>
              </ns2:ExpectedDelivery>
              <ns2:EstimatedDeliveryTimes>
                <ns2:EstimatedDeliveryTime>
                  <ns2:PickupPointId>124518</ns2:PickupPointId>
                  <ns2:DeliveryStartTime>10:00</ns2:DeliveryStartTime>
                  <ns2:DeliveryEndTime>13:00</ns2:DeliveryEndTime>
                  <ns2:FormattedExpectedDeliveryDate>11.09.2020</ns2:FormattedExpectedDeliveryDate>
                </ns2:EstimatedDeliveryTime>
              </ns2:EstimatedDeliveryTimes>
            </ns2:Product>
          </ns2:Products>
        </ns2:Consignment>
      </ns2:Consignments>
    </ns2:ShippingGuideResponse>
  </SOAP-ENV:Body>
</SOAP-ENV:Envelope>
comments powered by Disqus