Clarification of doc

Clarification of doc

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

documentation:
- title: Introduction
  content: |
      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.**

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

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

- title: Authentication
  content: |
      The Shipping Guide API 2.0 requires 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](/api/#authentication) page.

- title: Example walkthrough
  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.

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

- title: Error handling
  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: 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

- title: Estimated arrival time for parcels going to pickup points
  content: |
      For our Norwegian domestic B2C parcel 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.

      ### Estimated arrival time for the end users default pickup point (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, based on it` s 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.

      ### 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:

      **Pakken ankommer vanligvis mellom kl. X og Y / The parcel usually arrives between X and Y.**

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

      **Forventet levert XX.XX.20XX. Pakken ankommer vanligvis mellom kl. X og Y / 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.

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

/v2/products:
  displayName: Get shipment prices and estimated delivery
  description: |
      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 og 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 wpecialgoods fee will apply to the shipment. You might leave dimensions empty in your request, but be aware that returned prices might be incorrect.

  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
      addressLine:
        description: Specify address. This parameter can be maximum 35 character long. It will be for Bedriftspakke and På døren only.
        type: string
        example: Testsvingen 12
        required: false
      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
      nonstandardcourierservice:
        description: Specify service code for customize courier services in the request. It will be for NonStandard Courier only.
        type: string
        example: CDA
        required: true
      estimateddeliverytime:
        description: True if you want estimated delivery time of input pickup points. Also, 'withExpectedDelivery' flag should be set to True along with this. Eligible services are 5800 and SERVICEPAKKE.
        type: boolean
        required: false
      pickuppoints:
        description: 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.
        type: string
        example: 171102,124518
        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: SOAP
  description: |
      The SOAP Body follows the same XML Schema Definition (XSD) as stated above.
      ### 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/shipping-guide-20.xsd)

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

  post:
    description: Use this endpoint to get same information as above REST API
    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/xml)
    body:
      application/xml:
        example: !include examples/soap_estimated_delivery_time_request.xml
    responses:
          200:
            displayName: Estimated delivery time successful response
            body:
              application/xml:
                example: !include examples/soap_estimated_delivery_time_response_200.xml

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

documentation:
- title: Introduction
  content: |
      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.**

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

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

- title: Authentication
  content: |
      The Shipping Guide API 2.0 requires 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](/api/#authentication) page.

- title: Example walkthrough
  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.

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

- title: Error handling
  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: 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

- title: Estimated arrival time for parcels going to pickup points
  content: |
      For our Norwegian domestic B2C parcel 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.

      ### Estimated arrival time for the end users default pickup point (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, based on it` s 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.

      ### 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:

      **Pakken ankommer vanligvis mellom kl. X og Y / The parcel usually arrives between X and Y.**

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

      **Forventet levert XX.XX.20XX. Pakken ankommer vanligvis mellom kl. X og Y / 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.

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

/v2/products:
  displayName: Get shipment prices and estimated delivery
  description: |
      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

  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
      addressLine:
        description: Specify address. This parameter can be maximum 35 character long. It will be for Bedriftspakke and På døren only.
        type: string
        example: Testsvingen 12
        required: false
      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
      nonstandardcourierservice:
        description: Specify service code for customize courier services in the request. It will be for NonStandard Courier only.
        type: string
        example: CDA
        required: true
      estimateddeliverytime:
        description: True if you want estimated delivery time of input pickup points. Also, 'withExpectedDelivery' flag should be set to True along with this. Eligible services are 5800 and SERVICEPAKKE.
        type: boolean
        required: false
      pickuppoints:
        description: 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.
        type: string
        example: 171102,124518
        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: SOAP
  description: |
      The SOAP Body follows the same XML Schema Definition (XSD) as stated above.
      ### 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/shipping-guide-20.xsd)

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

  post:
    description: Use this endpoint to get same information as above REST API
    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/xml)
    body:
      application/xml:
        example: !include examples/soap_estimated_delivery_time_request.xml
    responses:
          200:
            displayName: Estimated delivery time successful response
            body:
              application/xml:
                example: !include examples/soap_estimated_delivery_time_response_200.xml


api docs update

api docs update

#%RAML 1.0
---
title: movie-library API
version: v1
protocols: [HTTPS]
mediaType: application/json
#baseUri: https://?.com/api/{version}
documentation:
  - title: Home
    content: |
      Welcome to the movie-library documentation.
      Movie-library API allows you to search for the best movies and add your own.
uses:
  resource: lib/resourceTypes.lib.raml
  response: lib/responseTypes.lib.raml

types:
  Item: !include dataTypes/item.raml
  Movie: !include dataTypes/movie.raml
  MovieItem: [Movie, Item]

/movies:
  type: resource.collection
  description: Movies collection
  get:
    description: List all existing movie items. Sorting possible with sort query parameter.
    queryParameters:
      sort:
        description: |
          The list of comma-separated properties used to sort the results.
          The columns are sorted by default in ascending order. Descending order is specified by fieldName:desc
          Allowed forms are: fieldName, fieldName:asc, fieldName:desc.
          Default: rating:asc
        example: "?sort=rating,category:desc"
    responses:
      200:
        description: Success. The list of movie items returned.
        body:
          application/json:
            type: array
            items: MovieItem
            example: !include /examples/moviesGet.json
  post:
    description: Add a new movie item.
    body:
      application/json:
        type: Movie
        example: !include /examples/moviesPost.json
    responses:
      201:
        description: Success. The movie item created.
        body:
          application/json:
            type: array
            items: MovieItem
            example: !include /examples/moviesGet.json
      400:
        description: Request syntactically incorrect.
        body:
          application/json:
            type: response.400
  /{id}:
    type: resource.item
    uriParameters:
      id:
        description: Id of a movie item
        type: string
    get:
      description: Get a single movie item
      responses:
        200:
          description: Success. The movie item returned.
          body:
            application/json:
              type: MovieItem
              example: !include /examples/movieGet.json
        404:
          description: Resource not found.
          body:
            application/json:
              type: response.404
    delete:
      description: Delete a single movie item
      responses:
        204:
          description: Success. The movie item deleted.
        404:
          description: Resource not found.
          body:
            application/json:
              type: response.404


Remove unnecessary application/json properties

Since the default mediaType is declared at the root level, you can omit the explicit application/json media types for any body. DRY!

#%RAML 0.8
baseUri: http://server/api/{version}
title: Kubernetes
version: v1beta1
mediaType: application/json
documentation:
 - title: Overview
   content: |
     The Kubernetes API currently manages 3 main resources: `pods`,
     `replicationControllers`, and `services`. Pods correspond to
     colocated groups of [Docker containers](http://docker.io) with
     shared volumes, as supported by [Google Cloud Platform's
     container-vm
     images](https://developers.google.com/compute/docs/containers).
     Singleton pods can be created directly via the `/pods`
     endpoint. Sets of pods may created, maintained, and scaled using
     replicationControllers.  Services create load-balanced targets
     for sets of pods.

 - title: Resource identifiers
   content: |
     Each resource has a string `id` and list of key-value
     `labels`. The `id` is generated by the system and is guaranteed
     to be unique in space and time across all resources.  `labels`
     is a map of string (key) to string (value). Each resource may
     have at most one label with a particular key. Individual labels
     are used to specify identifying metadata that can be used to
     define sets of resources by specifying required labels. Examples
     of typical pod label keys include `stage`, `service`, `name`,
     `tier`, `partition`, and `track`, but you are free to develop
     your own conventions.

 - title: Creation semantics
   content: |
     Creation is currently not idempotent. We plan to add a
     modification token to each resource. A unique value for the token
     should be provided by the user during creation. If the user
     specifies a duplicate token at creation time, the system should
     return an error with a pointer to the exiting resource with that
     token. In this way a user can deterministically recover from a
     dropped connection during a resource creation request.

 - title: Update semantics
   content: |
     Custom verbs are minimized and are used only for 'edge triggered'
     actions such as a reboot. Resource descriptions are generally set
     up with `desiredState` for the user provided parameters and
     `currentState` for the actual system state. While consistent
     terminology is used across these two stanzas they do not match
     member for member.

     When a new version of a resource is PUT the `desiredState` is
     updated and available immediately. Over time the system will work
     to bring the `currentState` into line with the `desiredState`. The
     system will drive toward the most recent `desiredState` regardless
     of previous versions of that stanza. In other words, if a value
     is changed from 2 to 5 in one PUT and then back down to 3 in
     another PUT the system isn't required to 'touch base' at 5 before
     making 3 the `currentState`.

     When doing an update, we assume that the entire `desiredState`
     stanza is specified. If a field is omitted it is assumed that the
     user is looking to delete that field. It is viable for a user to
     GET the resource, modify what they like in the `desiredState` or
     labels stanzas and then PUT it back. If the `currentState` is
     included in the PUT it will be silently ignored.

     While currently unspecified, it is intended that concurrent
     modification should be accomplished with optimistic locking of
     resources. We plan to add a modification token to each resource. If
     this is included with the PUT operation the system will verify
     that there haven't been other successful mutations to the
     resource during a read/modify/write cycle. The correct client
     action at this point is to GET the resource again, apply the
     changes afresh and try submitting again.

     Note that updates currently only work for replicationControllers
     and services, but not for pods. Label updates have not yet been
     implemented, either.

/pods:
  get:
    description: List all pods on this cluster
    responses:
      200:
        body:
          example: !include examples/pod-list.json
  post:
    description: Create a new pod. currentState is ignored if present.
    body:
      schema: !include doc/pod-schema.json
      example: !include examples/pod.json

  /{podId}:
    get:
      description: Get a specific pod
      responses:
        200:
          body:
            example: !include examples/pod.json
    put:
      description: Update a pod
      body:
        schema: !include doc/pod-schema.json
        example: !include examples/pod.json
    delete:
      description: Delete a specific pod
      responses:
        200:
          body:
            example: |
              {
                "success": true
              }

/replicationControllers:
  get:
    description: List all replicationControllers on this cluster
    responses:
      200:
        body:
          example: !include examples/controller-list.json
  post:
    description: Create a new controller. currentState is ignored if present.
    body:
      schema: !include doc/controller-schema.json
      example: !include examples/controller.json

  /{controllerId}:
    get:
      description: Get a specific controller
      responses:
        200:
          body:
            example: !include examples/controller.json
    put:
      description: Update a controller
      body:
        schema: !include doc/controller-schema.json
        example: !include examples/controller.json
    delete:
      description: Delete a specific controller
      responses:
        200:
          body:
            example: |
              {
                "success": true
              }

/services:
  get:
    description: List all services on this cluster
    responses:
      200:
        body:
          example: !include examples/service-list.json
  post:
    description: Create a new service
    body:
      schema: !include doc/service-schema.json
      example: !include examples/service.json

  /{serviceId}:
    get:
      description: Get a specific service
      responses:
        200:
          body:
            example: !include examples/service.json
    put:
      description: Update a service
      body:
        schema: !include doc/service-schema.json
        example: !include examples/service.json
    delete:
      description: Delete a specific service
      responses:
        200:
          body:
            example: |
              {
                "success": true
              }

#%RAML 0.8
baseUri: http://server/api/{version}
title: Kubernetes
version: v1beta1
mediaType: application/json
documentation:
 - title: Overview
   content: |
     The Kubernetes API currently manages 3 main resources: `pods`,
     `replicationControllers`, and `services`. Pods correspond to
     colocated groups of [Docker containers](http://docker.io) with
     shared volumes, as supported by [Google Cloud Platform's
     container-vm
     images](https://developers.google.com/compute/docs/containers).
     Singleton pods can be created directly via the `/pods`
     endpoint. Sets of pods may created, maintained, and scaled using
     replicationControllers.  Services create load-balanced targets
     for sets of pods.

 - title: Resource identifiers
   content: |
     Each resource has a string `id` and list of key-value
     `labels`. The `id` is generated by the system and is guaranteed
     to be unique in space and time across all resources.  `labels`
     is a map of string (key) to string (value). Each resource may
     have at most one label with a particular key. Individual labels
     are used to specify identifying metadata that can be used to
     define sets of resources by specifying required labels. Examples
     of typical pod label keys include `stage`, `service`, `name`,
     `tier`, `partition`, and `track`, but you are free to develop
     your own conventions.

 - title: Creation semantics
   content: |
     Creation is currently not idempotent. We plan to add a
     modification token to each resource. A unique value for the token
     should be provided by the user during creation. If the user
     specifies a duplicate token at creation time, the system should
     return an error with a pointer to the exiting resource with that
     token. In this way a user can deterministically recover from a
     dropped connection during a resource creation request.

 - title: Update semantics
   content: |
     Custom verbs are minimized and are used only for 'edge triggered'
     actions such as a reboot. Resource descriptions are generally set
     up with `desiredState` for the user provided parameters and
     `currentState` for the actual system state. While consistent
     terminology is used across these two stanzas they do not match
     member for member.

     When a new version of a resource is PUT the `desiredState` is
     updated and available immediately. Over time the system will work
     to bring the `currentState` into line with the `desiredState`. The
     system will drive toward the most recent `desiredState` regardless
     of previous versions of that stanza. In other words, if a value
     is changed from 2 to 5 in one PUT and then back down to 3 in
     another PUT the system isn't required to 'touch base' at 5 before
     making 3 the `currentState`.

     When doing an update, we assume that the entire `desiredState`
     stanza is specified. If a field is omitted it is assumed that the
     user is looking to delete that field. It is viable for a user to
     GET the resource, modify what they like in the `desiredState` or
     labels stanzas and then PUT it back. If the `currentState` is
     included in the PUT it will be silently ignored.

     While currently unspecified, it is intended that concurrent
     modification should be accomplished with optimistic locking of
     resources. We plan to add a modification token to each resource. If
     this is included with the PUT operation the system will verify
     that there haven't been other successful mutations to the
     resource during a read/modify/write cycle. The correct client
     action at this point is to GET the resource again, apply the
     changes afresh and try submitting again.

     Note that updates currently only work for replicationControllers
     and services, but not for pods. Label updates have not yet been
     implemented, either.

/pods:
  get:
    description: List all pods on this cluster
    responses:
      200:
        body:
          application/json:
            example: !include examples/pod-list.json
  post:
    description: Create a new pod. currentState is ignored if present.
    body:
      json/application:
        schema: !include doc/pod-schema.json
        example: !include examples/pod.json

  /{podId}:
    get:
      description: Get a specific pod
      responses:
        200:
          body:
            application/json:
              example: !include examples/pod.json
    put:
      description: Update a pod
      body:
        json/application:
          schema: !include doc/pod-schema.json
          example: !include examples/pod.json
    delete:
      description: Delete a specific pod
      responses:
        200:
          body:
            application/json:
              example: |
                {
                  "success": true
                }

/replicationControllers:
  get:
    description: List all replicationControllers on this cluster
    responses:
      200:
        body:
          application/json:
            example: !include examples/controller-list.json
  post:
    description: Create a new controller. currentState is ignored if present.
    body:
      json/application:
        schema: !include doc/controller-schema.json
        example: !include examples/controller.json

  /{controllerId}:
    get:
      description: Get a specific controller
      responses:
        200:
          body:
            application/json:
              example: !include examples/controller.json
    put:
      description: Update a controller
      body:
        json/application:
          schema: !include doc/controller-schema.json
          example: !include examples/controller.json
    delete:
      description: Delete a specific controller
      responses:
        200:
          body:
            application/json:
              example: |
                {
                  "success": true
                }

/services:
  get:
    description: List all services on this cluster
    responses:
      200:
        body:
          application/json:
            example: !include examples/service-list.json
  post:
    description: Create a new service
    body:
      json/application:
        schema: !include doc/service-schema.json
        example: !include examples/service.json

  /{serviceId}:
    get:
      description: Get a specific service
      responses:
        200:
          body:
            application/json:
              example: !include examples/service.json
    put:
      description: Update a service
      body:
        json/application:
          schema: !include doc/service-schema.json
          example: !include examples/service.json
    delete:
      description: Delete a specific service
      responses:
        200:
          body:
            application/json:
              example: |
                {
                  "success": true
                }


Add API specification

Add API specification


enum param in form

enum param in form

title: Example
baseUri: https://api.example.com
traits: !include /traits.yaml
/jsonapi:
  is: [authorized-by-token]
  get:
    displayName: fetch
    description: Fetch list
    queryParameters:
      default:
        description: java reserved word "default"
      if:
        description: java reserved word "if"
      enumparam:
        description: enum parameter with one underscored
        enum: [one, 2, underscored_param, for]
      boolparam:
        description: boolean parameter
        type: boolean
      required_param:
        description: required string param
        type: string
        required: true
      with_default_param:
        description: param with default value
        type: string
        default: default value
      _dotted_param.0:
        description: param with dot and digit in name
    responses:
      200:
        body:
          application/json:
            schema: !include schemas/groupResp.json
  post:
    description: Создание группы
    body:
      application/json:
        schema: !include schemas/group.json
    responses:
      201:
        description: |
          Group is created
      409:
        description: Group is already exist
      422:
        description: Validation error
  /{uri_param}:
    uriParameters:
      uri_param:
        description: integer param
        type: integer
    delete:
      description: Deletion
      responses:
        200:
          description: Group is deleted
        422:
          description: Deletion is forbidden
    get:
      description: Get group data
    patch:
      description: Change group data
      body:
        application/json:
          schema: !include schemas/group.json
      responses:
        200:
          description: Data is changed.
        422:
          description: Validation error
          body:
            application/json:
              schema: !include schemas/messageResp.json
/rpc_api:
  description: Some rpc deep api
  /{uid}/:
    uriParameters:
      uid:
        description: integer param
        type: integer
    /info/:
      description: in the middle of the path - template, ends with slash
      get:
  /password:
    displayName: password
    description: this lvl has display name
    /submit:
      displayName: submit
      description: |
        ## link
        https://wiki.example.com/auth/#initialization
      get:
        queryParameters:
          duplicated_param:
            description: this param duplicated in get and post
            required: true
      post:
        body:
          application/x-www-form-urlencoded:
            formParameters:
              duplicated_param:
                description: this param duplicated in post and get
              form_param:
                description: clean form param
              enumparam_in_form:
                description: enum parameter in form parameters should not became query parameter
                enum: [one, 2, underscored_param, for]

title: Example
baseUri: https://api.example.com
traits: !include /traits.yaml
/jsonapi:
  is: [authorized-by-token]
  get:
    displayName: fetch
    description: Fetch list
    queryParameters:
      default:
        description: java reserved word "default"
      if:
        description: java reserved word "if"
      enumparam:
        description: enum parameter with one underscored
        enum: [one, 2, underscored_param, for]
      boolparam:
        description: boolean parameter
        type: boolean
      required_param:
        description: required string param
        type: string
        required: true
      with_default_param:
        description: param with default value
        type: string
        default: default value
      _dotted_param.0:
        description: param with dot and digit in name
    responses:
      200:
        body:
          application/json:
            schema: !include schemas/groupResp.json
  post:
    description: Создание группы
    body:
      application/json:
        schema: !include schemas/group.json
    responses:
      201:
        description: |
          Group is created
      409:
        description: Group is already exist
      422:
        description: Validation error
  /{uri_param}:
    uriParameters:
      uri_param:
        description: integer param
        type: integer
    delete:
      description: Deletion
      responses:
        200:
          description: Group is deleted
        422:
          description: Deletion is forbidden
    get:
      description: Get group data
    patch:
      description: Change group data
      body:
        application/json:
          schema: !include schemas/group.json
      responses:
        200:
          description: Data is changed.
        422:
          description: Validation error
          body:
            application/json:
              schema: !include schemas/messageResp.json
/rpc_api:
  description: Some rpc deep api
  /{uid}/:
    uriParameters:
      uid:
        description: integer param
        type: integer
    /info/:
      description: in the middle of the path - template, ends with slash
      get:
  /password:
    displayName: password
    description: this lvl has display name
    /submit:
      displayName: submit
      description: |
        ## link
        https://wiki.example.com/auth/#initialization
      get:
        queryParameters:
          duplicated_param:
            description: this param duplicated in get and post
      post:
        body:
          application/x-www-form-urlencoded:
            formParameters:
              duplicated_param:
                description: this param duplicated in post and get
              form_param:
                description: clean form param