update settings link

update settings link

#%RAML 1.0
---
title: Shipping Guide API 2.0
baseUri: https://api.bring.com/shippingguide

documentation:
- title: Introduction
  content: |

            Important notice: New service id for Mailbox parcel (Pakke i Postkassen) from 13.01.2020

            A simplified and enhanced version of Mailbox parcel (Pakke i postkassen) was launched on 13.01.2020. From the same date, the Mailbox Packet API was decomissioned, and the revitalized Mailbox parcel service is booked via Booking API like other Bring-services.

            Use the following service codes when requesting the new Mailbox parcel products:

3584 - Mailbox parcel (no tracking)

3570 - Mailbox parcel with tracking

            Also, we advise you to use the main customer number when requesting this, as specifying the customer number on the form PARCELS_NORWAY-*********** will eventually be phased out.

            More information on how to book and test-book Mailbox parcel (Pakke i postkassen) through the Booking API can be found here.

      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.

      ### 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 Guid API](/api/shipping-guide/).

      Now that Shipping Guide API 2.0 is out you might be wondering how to upgrade to it. The [Upgrade to version 2.0](/api/shipping-guide_2/upgrade-to-version-2) will help you on your way to version 2.0 of the Shipping Guide API.

      ### Why upgrade?

      * [Unified request and response model](/api/shipping-guide_2/#getting-started): 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](/api/shipping-guide_2/#handle-api-errors): The new version of API gives ability to handle error in a much simpler way.
      * [Ability to fetch agreement prices specific to a service on REST](/api/shipping-guide_2/#get-shipment-prices-and-estimated-delivery): Now you can specify multiple services and along with multiple customer number in a single REST request. [How?](/api/shipping-guide_2/#get-shipment-prices-and-estimated-delivery)
      *  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.

- title: Getting started
  content: |
      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.

      ### Before you start
      Before you can begin using the new API you'll have to do the following:

      * [Sign up for a Mybring account](https://www.mybring.com/signup/register/user) if you do not already have one. If you're already registered in Mybring, head to the [settings and API](https://www.mybring.com/useradmin/account/settings/api) page to get your API key.
      * [Generate an API key](/api/#authentication) for your user

      ### 1. Get your API key from Mybring
      To make API requests you will need an API key. Click the link 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](/api/#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 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: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>
      ```

      ### 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](/api/shipping-guide_2/#request-and-response-structure)

- title: Shipping Guide topics
  content: |
      If you want to know more about corner cases/topics/etc, then [Let's talk about Shipping Guide](/api/shipping-guide_2/topics)

- title: Handle API errors
  content: |
      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](https://api.bring.com/shippingguide/api/errors?clientUrl=developer.bring.com)

      * 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](https://api.bring.com/shippingguide/api/ws/shipping-guide-20.xsd) and [WDSL](https://api.bring.com/shippingguide/api/ws/shippingguide-20.wsdl) itself, making it easier for clients to parse it.

- title: Request and response structure
  content: |
      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/shipping-guide-20.xsd)

      [https://api.bring.com/shippingguide/api/ws/shippingguide-20.wsdl](https://api.bring.com/shippingguide/api/ws/shippingguide-20.wsdl)

- title: Versioning
  content: |
       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.

- title: Improve performance
  content: |
      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

/v2/products:
  displayName: Get shipment prices and estimated delivery
  description: Use this endpoint to get expected delivery, service categories and additional information.
  get:
    description: Get shipment prices
    headers:
      X-MyBring-API-Uid:
        description: Your Mybring login ID
      X-MyBring-API-Key:
        description: Your user's API key
      Accept:
        description: Specify request format (application/json, application/xml)
    queryParameters:
      fromcountry:
        description: Sender country code
        type: string
      tocountry:
        description: Receiver country code
        type: string
      frompostalcode:
        description: Sender postal code
        type: string
      topostalcode:
        description: Receiver postal code
        type: string
      product:
        description: 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
        type: string
      date:
        description: Shipping date
        type: date
        example: 2018-11-18
        required: false
      time:
        description: Shipping time
        type: date
        example: 12:30
        required: false
      weight:
        description: Package weight in grams
        type: integer
        required: false
      volumeindm3:
        description: Package volume in dm3
        type: integer
        required: false
      loadingmeter:
        description: Package loading meters
        type: double
        required: false
      width:
        description: Package width in cm
        type: integer
        required: false
      length:
        description: Package length in cm
        type: integer
        required: false
      height:
        description: Package height in cm
        type: integer
        required: false
      numberofpallets:
        displayName: Number of pallets
        type: integer
        required: false
      nonstackable:
        description: Set to true if you know that pallet would be non-stackable
        type: boolean
        required: false
        default: false
      edi:
        description: Tells if the parcel will be registered using EDI when being booked. It may affect price and which services are available
        type: boolean
        required: false
        default: true
      postingatpostoffice:
        description: |
          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
        type: boolean
        required: false
        default: false
      additionalservice:
        displayName: Additional service
        description: Multiple value added services can be requested by repeating this parameter
        required: false
        type: string
      customernumber:
        description: 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
        type: string
        example: CARGO-123456
        required: false
      language:
        description: Language used for the service texts
        type: string
        default: no
        required: false
      volumeSpecial:
        description: True if the package has a shape that requires special handling
        type: boolean
        default: false
        required: false
      incoterms:
        description: Terms of delivery
        type: string
        required: false
      unnumber:
        description: Code for dangerous goods
        type: integer
        required: false
      payer:
        description: Payer type. Possible values are SENDER, RECEIVER or THIRD_PARTY
        type: string
        required: false
      numberofdeliverydates:
        description: Number of alternative delivery dates to be suggested by API for request
        type: integer
        required: false

    responses:
      200:
        displayName: Successful response
        description: |
          A successful response
      400:
        displayName: User error
        description: |
          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.
      401:
        displayName: Unauthorized
        description: |
          A failed response when the request is unauthenticated

/v2/products/price:
  displayName: Get shipment prices
  description: |
      Use this endpoint to get prices. The request parameters are the same as for [Get shipment prices and estimated delivery](/api/shipping-guide_2/#get-shipment-prices-and-estimated-delivery)
  get:
    description: 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)

/v2/products/expectedDelivery:
  displayName: Get expected delivery times
  description: |
      Use this endpoint to get expected delivery. The request parameters are the same as for [Get shipment prices and estimated delivery](/api/shipping-guide_2/#get-shipment-prices-and-estimated-delivery)
  get:
    description: Get estimated delivery time

/api/ws:
  displayName: Get shipment prices and estimated delivery
  description: Use this endpoint to get expected delivery, service categories and additional information.
  post:
    description: Use this endpoint to get expected delivery, service categories and additional information.
    headers:
      X-MyBring-API-Uid:
        description: Your Mybring login ID
      X-MyBring-API-Key:
        description: Your user's API key
      Accept:
        description: Specify request format (application/json, application/xml)

#%RAML 1.0
---
title: Shipping Guide API 2.0
baseUri: https://api.bring.com/shippingguide

documentation:
- title: Introduction
  content: |

            Important notice: New service id for Mailbox parcel (Pakke i Postkassen) from 13.01.2020

            A simplified and enhanced version of Mailbox parcel (Pakke i postkassen) was launched on 13.01.2020. From the same date, the Mailbox Packet API was decomissioned, and the revitalized Mailbox parcel service is booked via Booking API like other Bring-services.

            Use the following service codes when requesting the new Mailbox parcel products:

3584 - Mailbox parcel (no tracking)

3570 - Mailbox parcel with tracking

            Also, we advise you to use the main customer number when requesting this, as specifying the customer number on the form PARCELS_NORWAY-*********** will eventually be phased out.

            More information on how to book and test-book Mailbox parcel (Pakke i postkassen) through the Booking API can be found here.

      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.

      ### 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 Guid API](/api/shipping-guide/).

      Now that Shipping Guide API 2.0 is out you might be wondering how to upgrade to it. The [Upgrade to version 2.0](/api/shipping-guide_2/upgrade-to-version-2) will help you on your way to version 2.0 of the Shipping Guide API.

      ### Why upgrade?

      * [Unified request and response model](/api/shipping-guide_2/#getting-started): 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](/api/shipping-guide_2/#handle-api-errors): The new version of API gives ability to handle error in a much simpler way.
      * [Ability to fetch agreement prices specific to a service on REST](/api/shipping-guide_2/#get-shipment-prices-and-estimated-delivery): Now you can specify multiple services and along with multiple customer number in a single REST request. [How?](/api/shipping-guide_2/#get-shipment-prices-and-estimated-delivery)
      *  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.

- title: Getting started
  content: |
      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.

      ### Before you start
      Before you can begin using the new API you'll have to do the following:

      * [Sign up for a Mybring account](https://www.mybring.com/signup/register/user) if you do not already have one. If you're already registered in Mybring, head to the [settings and API](https://www.mybring.com/useradmin/account/settings/) page to get your API key.
      * [Generate an API key](/api/#authentication) for your user

      ### 1. Get your API key from Mybring
      To make API requests you will need an API key. Click the link 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](/api/#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 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: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>
      ```

      ### 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](/api/shipping-guide_2/#request-and-response-structure)

- title: Shipping Guide topics
  content: |
      If you want to know more about corner cases/topics/etc, then [Let's talk about Shipping Guide](/api/shipping-guide_2/topics)

- title: Handle API errors
  content: |
      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](https://api.bring.com/shippingguide/api/errors?clientUrl=developer.bring.com)

      * 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](https://api.bring.com/shippingguide/api/ws/shipping-guide-20.xsd) and [WDSL](https://api.bring.com/shippingguide/api/ws/shippingguide-20.wsdl) itself, making it easier for clients to parse it.

- title: Request and response structure
  content: |
      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/shipping-guide-20.xsd)

      [https://api.bring.com/shippingguide/api/ws/shippingguide-20.wsdl](https://api.bring.com/shippingguide/api/ws/shippingguide-20.wsdl)

- title: Versioning
  content: |
       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.

- title: Improve performance
  content: |
      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

/v2/products:
  displayName: Get shipment prices and estimated delivery
  description: Use this endpoint to get expected delivery, service categories and additional information.
  get:
    description: Get shipment prices
    headers:
      X-MyBring-API-Uid:
        description: Your Mybring login ID
      X-MyBring-API-Key:
        description: Your user's API key
      Accept:
        description: Specify request format (application/json, application/xml)
    queryParameters:
      fromcountry:
        description: Sender country code
        type: string
      tocountry:
        description: Receiver country code
        type: string
      frompostalcode:
        description: Sender postal code
        type: string
      topostalcode:
        description: Receiver postal code
        type: string
      product:
        description: 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
        type: string
      date:
        description: Shipping date
        type: date
        example: 2018-11-18
        required: false
      time:
        description: Shipping time
        type: date
        example: 12:30
        required: false
      weight:
        description: Package weight in grams
        type: integer
        required: false
      volumeindm3:
        description: Package volume in dm3
        type: integer
        required: false
      loadingmeter:
        description: Package loading meters
        type: double
        required: false
      width:
        description: Package width in cm
        type: integer
        required: false
      length:
        description: Package length in cm
        type: integer
        required: false
      height:
        description: Package height in cm
        type: integer
        required: false
      numberofpallets:
        displayName: Number of pallets
        type: integer
        required: false
      nonstackable:
        description: Set to true if you know that pallet would be non-stackable
        type: boolean
        required: false
        default: false
      edi:
        description: Tells if the parcel will be registered using EDI when being booked. It may affect price and which services are available
        type: boolean
        required: false
        default: true
      postingatpostoffice:
        description: |
          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
        type: boolean
        required: false
        default: false
      additionalservice:
        displayName: Additional service
        description: Multiple value added services can be requested by repeating this parameter
        required: false
        type: string
      customernumber:
        description: 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
        type: string
        example: CARGO-123456
        required: false
      language:
        description: Language used for the service texts
        type: string
        default: no
        required: false
      volumeSpecial:
        description: True if the package has a shape that requires special handling
        type: boolean
        default: false
        required: false
      incoterms:
        description: Terms of delivery
        type: string
        required: false
      unnumber:
        description: Code for dangerous goods
        type: integer
        required: false
      payer:
        description: Payer type. Possible values are SENDER, RECEIVER or THIRD_PARTY
        type: string
        required: false
      numberofdeliverydates:
        description: Number of alternative delivery dates to be suggested by API for request
        type: integer
        required: false

    responses:
      200:
        displayName: Successful response
        description: |
          A successful response
      400:
        displayName: User error
        description: |
          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.
      401:
        displayName: Unauthorized
        description: |
          A failed response when the request is unauthenticated

/v2/products/price:
  displayName: Get shipment prices
  description: |
      Use this endpoint to get prices. The request parameters are the same as for [Get shipment prices and estimated delivery](/api/shipping-guide_2/#get-shipment-prices-and-estimated-delivery)
  get:
    description: 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)

/v2/products/expectedDelivery:
  displayName: Get expected delivery times
  description: |
      Use this endpoint to get expected delivery. The request parameters are the same as for [Get shipment prices and estimated delivery](/api/shipping-guide_2/#get-shipment-prices-and-estimated-delivery)
  get:
    description: Get estimated delivery time

/api/ws:
  displayName: Get shipment prices and estimated delivery
  description: Use this endpoint to get expected delivery, service categories and additional information.
  post:
    description: Use this endpoint to get expected delivery, service categories and additional information.
    headers:
      X-MyBring-API-Uid:
        description: Your Mybring login ID
      X-MyBring-API-Key:
        description: Your user's API key
      Accept:
        description: Specify request format (application/json, application/xml)


Write error

Write error

#%RAML 0.8
---
title: Order Management API
baseUri: https://api.bring.com/po/api/v1

documentation:
- title: Introduction
  content: |
    There are different customer types in Order Management and depending on what kind of customer you are setts the usage pattern for Order Management API.

    This is a step-by-step guide on how to use the API.

    A typical usage pattern for an Warehousing customer type is to create an order in Order Management that will go to the correct warehouse for picking, packing and sending. Then follow up with creating a packing list from the warehouse with transport information. All steps can be followed in Order Management.

    An other usage pattern is for an purchase order customer that create purchase orders and lets all of his suppliers get the order from Order Management. The suppliers will check whether a customer is a Order Management customer. Follow up with creating a packing list with transport information. All events and status changes will go back to purchase order owner.

    Order Management has several interfaces (SOAP and XML/JSON). Choose the option that fits your needs best (see table below). The SOAP interface is the core interface with complete functionality.

    Please note that this API currently doesn't support json on all of its methods yet. Look in the example section to see which are supported.

    ## SOAP

    ### Versioning

    Order Management makes an effort to always be backwards compatible regarding data format for requests and responses of the Web Service. To achieve this, a SchemaVersion element is used in the request, indicating which version the client is on and what data-format the client expects in the result.

    We make an effort not to return new elements in the response when an old schema version is specified. When changes in the schema are made, the SchemaVersion is incremented by one. The new schema is used at the same endpoint URL as before and uses the same namespace for its XML elements. A TraceMessage element (info message) in the response is added to inform the client that its schema should be updated. Old schema versions might in the future be unsupported.

    Regarding the XML API (not Web Services), an XML Schema is not used at all. Therefore, clients of the XML API are expected to handle new elements that appear. Nevertheless, the response will be backwards compatible in the sense that elements are not renamed or deleted.

    ### WSDL

    [https://api.bring.com/po/api/ws/purchaseorder-v1.wsdl](https://api.bring.com/po/api/ws/purchaseorder-v1.wsdl)

    [https://api.bring.com/po/api/ws/om-order-v1.wsdl](https://api.bring.com/po/api/ws/om-order-v1.wsdl)

    ## Error handling

    When using the Order Management, errors or service unavailability can occur, although we do our utmost to prevent any downtime. Thus it is important to use timeouts and other error handling techniques when making requests to the service.

    How you handle errors depends on the nature of your application, but one strategy for handling such situations is by providing a failover if the shipping guide responds with an error or does not respond at all (timeout).

    See [the list of error codes](#list-error-codes) for hints on how to implement error handling.

- title: Authentication
  content: |
    The Order Management API requires authentication for all its endpoints. See the [getting started guide on authentication](/api/#authentication) if you're not sure what this means.

    | Header | Example | Comment |
    |:-------|:--------|:--------|
    | `X-MyBring-API-Uid` | `john.doe@example.com` | Mybring login ID |
    | `X-MyBring-API-Key` | `1234abc-abcd-1234-5678-abcd1234abcd ` | Mybring login's API key |
    | `X-Bring-Client-URL` | `https://example.com/ ` | A URL that sort of identifies where you're using the APIs. |

    Those headers must be set for all endpoints documented below.

/purchaseorderCustomer/{customerId}:
  displayName: Check if customer is valid for order management
  description: |
      Check if a given customer number is an valid Order Management customer.
  get:
    description:
     Check if customer is valid for order management
    responses:
      200:
        displayName: Success
        description: |
          Returns `true` if given customer is a valid for order management.
        body:
          application/xml:
            example: !include examples/verify_customer.xml
          application/json:
            example: !include examples/verify_customer.json

/omorder/{customerId}/{orderId}:
  displayName: List order information
  description: |
      Get all information on a given order.
  get:
    description: List order information
    responses:
      200:
        displayName: Success
        description: |
          Complete order information including order items.
        body:
          application/xml:
            example: !include examples/retrieve_order.xml
          application/json:
            example: !include examples/retrieve_order.json

/omorder:
  displayName: Send an order
  description: |
      Send an order to Order Management. There are different types of order supported in Order Management.

       - Order / SalesOrder (as an pickorder for Warehousing)
            - Order Management act as an order repository.
            - When Warehousing functionality Order Management sends it to Warhousing system for picking and delivery.
       - PurchaseOrder
            - Order Management can give your suppliers access to purchase orders so they can get info, confirm, accept and deliver on them.
            - When Warehousing functionality Order Management sends it to Warhousing system for receiving notice.

  post:
    description: Send an order
    queryParameters:
      CreateOrderRequest messageFunction:
          description: Type of order.
"Order"
"OrderResponse"
"SalesOrder"
"NotifyTransport"
"PurchaseOrder"
"ArticleBalance"
"DespatchAdvice"
"ReceivingAdvice"
"PackageList"
          type: string
          required: true
          example: Order
      MessageSender partyId:
          description: Customer Number which Bring has provided. It cannot be demo customer number.
          type: string
          required: true
          example: 10000000000
      MessageRecipient partyId:
          description: Receiving Bring system. Constant value.
          type: string
          required: true
          example: NO98466118506
      MessageDate:
          description: The date on which message is sent.
          type: dateTime
          required: true
          example: 22.01.2017 11:36:22
      OrderSet updateIndicator:
          description: Type of order data. Original, Update or Deletion
          type: string
          required: true
          example: Original
      Order orderId:
          description: Ordernumber.
          type: dateTime
          required: true
          example: 101010
      Reference:
          description: Set of references.
          type: sequence
          required: false
      Reference referenceType:
          description: Type of reference coded. https://www.stylusstudio.com/edifact/D04A/1153.htm
          type: String
          required: true
          example: CMR
      Reference ReferenceNo:
          description: Reference.
          type: String
          required: true
          example: 10003455TT
      DateAndTimes subClass DocumentDate:
          description: The date on which order is booked.
          type: dateTime
          required: true
          example: 22.01.2017 11:36:22
      TransportService BasicServiceCode:
          description: Transport product for shipment to customer. http://developer.bring.com/api/products/
          type: String
          required: true
          example: SERVICEPAKKE
      TransportService AdditionalService AdditionalServiceCode:
          description: Transport services for shipment to customer. http://developer.bring.com/api/products/
          type: String
          required: true
          example: EVARSLING
      TransportLeg TransportLegType:
          description: TransportLegType id. Default value 30.
          type: String
          required: true
          example: 30
      TransportLeg ModeOfTransport:
          description: Type of transport.
1 = Sea
2 = Train
3 = Road
4 = Air.
          type: String
          required: true
          example: 3
      Party/subClass OrderingParty:
          description: Details of sender. Must have Name, Street, City, CountryCode.
          required: true
      Party/subClass DeliveryParty:
          description: Details of recipient. Must have Name, Street, City, CountryCode.
          required: true
      Party/subClass Supplier:
          description: Details of supplier. Must have Name, Street, City, CountryCode if used.
          required: false
      Party/subClass PerformingUnit partyId:
          description: Warehouse id for order. Required if order to Warehousing system.
          type: string
          required: false
          example: BERGER
      OrderLineSet:
          description: Set of order items.
          type: sequence
          required: true
      OrderItem articleLineId:
          description: Line id for this order line.
          type: integer
          required: true
          example: 10
      ArticleId:
          description: Article number or id.
          type: sequence
          required: true
          example: 123-4000
      ArticleId codeListAgencyIdentifier:
          description: Sets type of ArticleId.
"CustomerItemNo"
"VendorItemNo"
"EAN"
If not used ArticleId default is CustomerItemNo.
          type: string
          required: false
          example: VendorItemNo
      ArticleQuantity unitCode:
          description: Unit code for quantity ordered.
          type: string
          required: true
          example: STK
      ArticleQuantity:
          description: Quantity ordered.
          type: float
          required: true
          example: 2.0
      Description usageCode:
          description: Article description type. If description used set to AAA.
          type: string
          required: false
          example: AAA
      Description:
          description: Article description.
          type: string
          required: false
          example: Spear parts with all parts
      ArticleName:
          description: Article name.
          type: string
          required: false
          example: Spear parts
      DateAndTimes subClass DeliveryDateRequested:
          description: The date on which order is requested delivered.
          type: dateTime
          required: true
          example: 22.01.2017 11:36:22

    body:
        application/xml:
          example: !include examples/create_order.xml
        application/json:
          example: !include examples/create_order.json
    responses:
      200:
        displayName: Success
        description: |
          Successfully created a order.

/items/{customerId}/{orderId}:
  displayName: List order items
  description: |
      List all item lines on an order.
  get:
    description: List order items
    responses:
      200:
        displayName: Success
        description: |
          List of order items.
        body:
          application/xml:
            example: !include examples/retrieve_orderitems.xml
          application/json:
            example: !include examples/retrieve_orderitems.json

/packaginglist/{customerId}/{orderId}:
  displayName: List packaging list for order
  description: |
      List all packaging list information for this order. One order can have multiple packaging lists.
  get:
    description: List packaging list for order
    responses:
      200:
        displayName: Success
        description: |
          List of packaging list for given order, if any.
        body:
          application/xml:
            example: !include examples/retrieve_packinglist.xml
          application/json:
            example: !include examples/retrieve_packinglist.json

/packaginglist:
  displayName: Add packaging list
  description: |
      When an order have been picked and sent, add packing list on order with transport information.
  post:
    description: Add packaging list
    body:
      application/xml:
        example: !include examples/create_packaging_list.xml
    responses:
      200:
        displayName: Success
        description: |
          Successfully added packaging list.

/senderStatus/{customerId}/{orderId}:
  displayName: Get sender status for order
  description: |
      Check sender status for an order. Open when not fully delivered or locked when fully delivered.
  get:
    description: Get status for order
    responses:
      200:
        displayName: Success
        description: Open or Locked.
        body:
          application/xml:
            example: !include examples/check_status.xml
          application/json:
            example: !include examples/check_status.json

/event:
  displayName: Create TMSEvents
  description: |
      Create tracking events on shipments associated with orders in Order Management.
  post:
    description: Create TMSEvents
    body:
      application/xml:
        example: !include examples/create_events.xml
    responses:
      200:
        displayName: Success
        description: |
          Successfully created a new resource

/articlebalance:
  displayName: Create or update article balance list
  post:
    description: Create or update article balance list
    body:
      application/xml:
        example: !include examples/create_articlebalance.xml
    responses:
      200:
        displayName: Success
        description: |
          Successfully created balance list

/articlebalance/{customerId}:
  displayName: Get stock balance and info for all articles
  get:
    description: Get stock balance and info for all articles
    responses:
      200:
        displayName: Success
        description: |
        body:
          application/xml:
            example: !include examples/retrieve_articlebalance_all.xml
          application/json:
            example: !include examples/retrieve_articlebalance_all.json

/articlebalance/{customerId}/{articleNo}:
  displayName: Get stock balance and info for one article
  get:
    description: Get stock balance and info for one article
    responses:
      200:
        displayName: Success
        description: |
        body:
          application/xml:
            example: !include examples/retrieve_articlebalance_one.xml
          application/json:
            example: !include examples/retrieve_articlebalance_one.json

/articlebalance/info/{customerId}/{articleSearchString}:
  displayName: Get stock balance and info for all articles matching search string
  get:
    description: Get stock balance and info for all articles matching search string
    responses:
      200:
        displayName: Success
        description: |
        body:
          application/xml:
            example: !include examples/retrieve_articlebalance_search.xml
          application/json:
            example: !include examples/retrieve_articlebalance_search.json

/errorCodes:
  displayName: List error codes
  get:
    description: List error codes
    responses:
      200:
        displayName: Success
        description: |
          Dynamic list of error codes used in the solution.
        body:
          application/xml:
            example: !include examples/error_codes.xml
          application/json:
            example: !include examples/error_codes.json

#%RAML 0.8
---
title: Order Management API
baseUri: https://api.bring.com/po/api/v1

documentation:
- title: Introduction
  content: |
    There are different customer types in Order Management and depending on what kind of customer you are setts the usage pattern for Order Management API.

    This is a step-by-step guide on how to use the API.

    A typical usage pattern for an Warehousing cutomer type is to create an order in Order Management that will go to the correct warehouse for picking, packing and sending. Then follow up with creating a packing list from the warehouse with transport information. All steps can be followed in Order Management.

    An other usage pattern is for an purchase order customer that create purchase orders and lets all of his suppliers get the order from Order Management. The suppliers will check whether a customer is a Order Management customer. Follow up with creating a packing list with transport information. All events and status changes will go back to purchase order owner.

    Order Management has several interfaces (SOAP and XML/JSON). Choose the option that fits your needs best (see table below). The SOAP interface is the core interface with complete functionality.

    Please note that this API currently doesn't support json on all of its methods yet. Look in the example section to see which are supported.

    ## SOAP

    ### Versioning

    Order Management makes an effort to always be backwards compatible regarding data format for requests and responses of the Web Service. To achieve this, a SchemaVersion element is used in the request, indicating which version the client is on and what data-format the client expects in the result.

    We make an effort not to return new elements in the response when an old schema version is specified. When changes in the schema are made, the SchemaVersion is incremented by one. The new schema is used at the same endpoint URL as before and uses the same namespace for its XML elements. A TraceMessage element (info message) in the response is added to inform the client that its schema should be updated. Old schema versions might in the future be unsupported.

    Regarding the XML API (not Web Services), an XML Schema is not used at all. Therefore, clients of the XML API are expected to handle new elements that appear. Nevertheless, the response will be backwards compatible in the sense that elements are not renamed or deleted.

    ### WSDL

    [https://api.bring.com/po/api/ws/purchaseorder-v1.wsdl](https://api.bring.com/po/api/ws/purchaseorder-v1.wsdl)

    [https://api.bring.com/po/api/ws/om-order-v1.wsdl](https://api.bring.com/po/api/ws/om-order-v1.wsdl)

    ## Error handling

    When using the Order Management, errors or service unavailability can occur, although we do our utmost to prevent any downtime. Thus it is important to use timeouts and other error handling techniques when making requests to the service.

    How you handle errors depends on the nature of your application, but one strategy for handling such situations is by providing a failover if the shipping guide responds with an error or does not respond at all (timeout).

    See [the list of error codes](#list-error-codes) for hints on how to implement error handling.

- title: Authentication
  content: |
    The Order Management API requires authentication for all its endpoints. See the [getting started guide on authentication](/api/#authentication) if you're not sure what this means.

    | Header | Example | Comment |
    |:-------|:--------|:--------|
    | `X-MyBring-API-Uid` | `john.doe@example.com` | Mybring login ID |
    | `X-MyBring-API-Key` | `1234abc-abcd-1234-5678-abcd1234abcd ` | Mybring login's API key |
    | `X-Bring-Client-URL` | `https://example.com/ ` | A URL that sort of identifies where you're using the APIs. |

    Those headers must be set for all endpoints documented below.

/purchaseorderCustomer/{customerId}:
  displayName: Check if customer is valid for order management
  description: |
      Check if a given customer number is an valid Order Management customer.
  get:
    description:
     Check if customer is valid for order management
    responses:
      200:
        displayName: Success
        description: |
          Returns `true` if given customer is a valid for order management.
        body:
          application/xml:
            example: !include examples/verify_customer.xml
          application/json:
            example: !include examples/verify_customer.json

/omorder/{customerId}/{orderId}:
  displayName: List order information
  description: |
      Get all information on a given order.
  get:
    description: List order information
    responses:
      200:
        displayName: Success
        description: |
          Complete order information including order items.
        body:
          application/xml:
            example: !include examples/retrieve_order.xml
          application/json:
            example: !include examples/retrieve_order.json

/omorder:
  displayName: Send an order
  description: |
      Send an order to Order Management. There are different types of order supported in Order Management.

       - Order / SalesOrder (as an pickorder for Warehousing)
            - Order Management act as an order repository.
            - When Warehousing functionality Order Management sends it to Warhousing system for picking and delivery.
       - PurchaseOrder
            - Order Management can give your suppliers access to purchase orders so they can get info, confirm, accept and deliver on them.
            - When Warehousing functionality Order Management sends it to Warhousing system for receiving notice.

  post:
    description: Send an order
    queryParameters:
      CreateOrderRequest messageFunction:
          description: Type of order.
"Order"
"OrderResponse"
"SalesOrder"
"NotifyTransport"
"PurchaseOrder"
"ArticleBalance"
"DespatchAdvice"
"ReceivingAdvice"
"PackageList"
          type: string
          required: true
          example: Order
      MessageSender partyId:
          description: Customer Number which Bring has provided. It cannot be demo customer number.
          type: string
          required: true
          example: 10000000000
      MessageRecipient partyId:
          description: Receiving Bring system. Constant value.
          type: string
          required: true
          example: NO98466118506
      MessageDate:
          description: The date on which message is sent.
          type: dateTime
          required: true
          example: 22.01.2017 11:36:22
      OrderSet updateIndicator:
          description: Type of order data. Original, Update or Deletion
          type: string
          required: true
          example: Original
      Order orderId:
          description: Ordernumber.
          type: dateTime
          required: true
          example: 101010
      Reference:
          description: Set of references.
          type: sequence
          required: false
      Reference referenceType:
          description: Type of reference coded. https://www.stylusstudio.com/edifact/D04A/1153.htm
          type: String
          required: true
          example: CMR
      Reference ReferenceNo:
          description: Reference.
          type: String
          required: true
          example: 10003455TT
      DateAndTimes subClass DocumentDate:
          description: The date on which order is booked.
          type: dateTime
          required: true
          example: 22.01.2017 11:36:22
      TransportService BasicServiceCode:
          description: Transport product for shipment to customer. http://developer.bring.com/api/products/
          type: String
          required: true
          example: SERVICEPAKKE
      TransportService AdditionalService AdditionalServiceCode:
          description: Transport services for shipment to customer. http://developer.bring.com/api/products/
          type: String
          required: true
          example: EVARSLING
      TransportLeg TransportLegType:
          description: TransportLegType id. Default value 30.
          type: String
          required: true
          example: 30
      TransportLeg ModeOfTransport:
          description: Type of transport.
1 = Sea
2 = Train
3 = Road
4 = Air.
          type: String
          required: true
          example: 3
      Party/subClass OrderingParty:
          description: Details of sender. Must have Name, Street, City, CountryCode.
          required: true
      Party/subClass DeliveryParty:
          description: Details of recipient. Must have Name, Street, City, CountryCode.
          required: true
      Party/subClass Supplier:
          description: Details of supplier. Must have Name, Street, City, CountryCode if used.
          required: false
      Party/subClass PerformingUnit partyId:
          description: Warehouse id for order. Required if order to Warehousing system.
          type: string
          required: false
          example: BERGER
      OrderLineSet:
          description: Set of order items.
          type: sequence
          required: true
      OrderItem articleLineId:
          description: Line id for this order line.
          type: integer
          required: true
          example: 10
      ArticleId:
          description: Article number or id.
          type: sequence
          required: true
          example: 123-4000
      ArticleId codeListAgencyIdentifier:
          description: Sets type of ArticleId.
"CustomerItemNo"
"VendorItemNo"
"EAN"
If not used ArticleId default is CustomerItemNo.
          type: string
          required: false
          example: VendorItemNo
      ArticleQuantity unitCode:
          description: Unit code for quantity ordered.
          type: string
          required: true
          example: STK
      ArticleQuantity:
          description: Quantity ordered.
          type: float
          required: true
          example: 2.0
      Description usageCode:
          description: Article description type. If description used set to AAA.
          type: string
          required: false
          example: AAA
      Description:
          description: Article description.
          type: string
          required: false
          example: Spear parts with all parts
      ArticleName:
          description: Article name.
          type: string
          required: false
          example: Spear parts
      DateAndTimes subClass DeliveryDateRequested:
          description: The date on which order is requested delivered.
          type: dateTime
          required: true
          example: 22.01.2017 11:36:22

    body:
        application/xml:
          example: !include examples/create_order.xml
        application/json:
          example: !include examples/create_order.json
    responses:
      200:
        displayName: Success
        description: |
          Successfully created a order.

/items/{customerId}/{orderId}:
  displayName: List order items
  description: |
      List all item lines on an order.
  get:
    description: List order items
    responses:
      200:
        displayName: Success
        description: |
          List of order items.
        body:
          application/xml:
            example: !include examples/retrieve_orderitems.xml
          application/json:
            example: !include examples/retrieve_orderitems.json

/packaginglist/{customerId}/{orderId}:
  displayName: List packaging list for order
  description: |
      List all packaging list information for this order. One order can have multiple packaging lists.
  get:
    description: List packaging list for order
    responses:
      200:
        displayName: Success
        description: |
          List of packaging list for given order, if any.
        body:
          application/xml:
            example: !include examples/retrieve_packinglist.xml
          application/json:
            example: !include examples/retrieve_packinglist.json

/packaginglist:
  displayName: Add packaging list
  description: |
      When an order have been picked and sent, add packing list on order with transport information.
  post:
    description: Add packaging list
    body:
      application/xml:
        example: !include examples/create_packaging_list.xml
    responses:
      200:
        displayName: Success
        description: |
          Successfully added packaging list.

/senderStatus/{customerId}/{orderId}:
  displayName: Get sender status for order
  description: |
      Check sender status for an order. Open when not fully delivered or locked when fully delivered.
  get:
    description: Get status for order
    responses:
      200:
        displayName: Success
        description: Open or Locked.
        body:
          application/xml:
            example: !include examples/check_status.xml
          application/json:
            example: !include examples/check_status.json

/event:
  displayName: Create TMSEvents
  description: |
      Create tracking events on shipments associated with orders in Order Management.
  post:
    description: Create TMSEvents
    body:
      application/xml:
        example: !include examples/create_events.xml
    responses:
      200:
        displayName: Success
        description: |
          Successfully created a new resource

/articlebalance:
  displayName: Create or update article balance list
  post:
    description: Create or update article balance list
    body:
      application/xml:
        example: !include examples/create_articlebalance.xml
    responses:
      200:
        displayName: Success
        description: |
          Successfully created balance list

/articlebalance/{customerId}:
  displayName: Get stock balance and info for all articles
  get:
    description: Get stock balance and info for all articles
    responses:
      200:
        displayName: Success
        description: |
        body:
          application/xml:
            example: !include examples/retrieve_articlebalance_all.xml
          application/json:
            example: !include examples/retrieve_articlebalance_all.json

/articlebalance/{customerId}/{articleNo}:
  displayName: Get stock balance and info for one article
  get:
    description: Get stock balance and info for one article
    responses:
      200:
        displayName: Success
        description: |
        body:
          application/xml:
            example: !include examples/retrieve_articlebalance_one.xml
          application/json:
            example: !include examples/retrieve_articlebalance_one.json

/articlebalance/info/{customerId}/{articleSearchString}:
  displayName: Get stock balance and info for all articles matching search string
  get:
    description: Get stock balance and info for all articles matching search string
    responses:
      200:
        displayName: Success
        description: |
        body:
          application/xml:
            example: !include examples/retrieve_articlebalance_search.xml
          application/json:
            example: !include examples/retrieve_articlebalance_search.json

/errorCodes:
  displayName: List error codes
  get:
    description: List error codes
    responses:
      200:
        displayName: Success
        description: |
          Dynamic list of error codes used in the solution.
        body:
          application/xml:
            example: !include examples/error_codes.xml
          application/json:
            example: !include examples/error_codes.json