Example for validated order

Example for validated order

#%RAML 1.0
---
title: Order to Mailbox API
version: v1
baseUri: https://api.bring.com/order/to-mailbox
mediaType: application/json
types:
  Order:
    type: object
    properties:
      customerNumber:
        type: string
      senderName:
        type: string
      senderEmail:
        required: false
        type: string
        pattern: ".+@.+"
        description: Defaults to the user's email address.
      postalCode:
        type: string
        description: A valid Norwegian postal code.
      streetAddress:
        type: string
      reference:
        required: true
      packages:
        minItems: 1
        type: Package[]
  Package:
    type: object
    properties:
      priority:
        enum: [ A, B ]
        description: Delivery speed (A-post or B-post).
      rfid:
        type: boolean
        description: Whether to activate [tracking for the package](#tracking-with-rfid)
      weight:
        maximum: 2000
        type: integer
      recipientName: string
      postalCode:
        type: string
        description: A valid Norwegian postal code.
      streetAddress:
        type: string
      phoneNumber:
        type: string
        pattern: "\\+[0-9 ]+"
        description: A phone number including country code
        example: "+4700000000"
      email:
        type: string
        pattern: ".+@.+"
  SuccessfulOrder:
    properties:
      id:
        type: number
      customerName:
        type: string
      customerOrganizationNumber:
        type: string
      customerNumber:
        type: string
      senderName:
        type: string
      streetAddress:
        type: string
      postalCode:
        type: string
        description: A valid Norwegian postal code.
      postalPlace:
        type: string
      email:
        type: string
        pattern: ".+@.+"
      reference:
        type: string
      labelUri:
        type: string
        description: URL to PDF label if ordered without tracking.
      rfidLabelUri:
        type: string
        description: URL to ZPL label if ordered with tracking.
      waybillUri:
        type: string
        description: URL to waybill PDF that goes with the order.
      priceWithoutVat:
        type: number
      priceWithVat:
        type: number
      vat:
        type: number
      currency:
        type: string
        default: NOK
      orderTime:
        type: datetime
      userEmail:
        required: false
        type: string
        description: The email address for the user that placed the order.
      userPhone:
        required: false
        type: string
        description: The phone number for the user that placed the order.
      userFullName:
        required: false
        type: string
        description: The name for the user that placed the order.
      orderNumberReference:
        type: string
        description: The order number reference for the placed order. This is the number on the waybill.
      packages:
        minItems: 1
        type: OrderedPackage[]
  OrderedPackage:
    properties:
      priority:
        enum: [ A, B ]
        description: Delivery speed (A-post or B-post).
      rfid:
        type: boolean
        description: Whether to [tracking for the package](#tracking-with-rfid) was activated.
      specialist:
        type: string
        description: The type of customer for which the order was placed.
      recipientName:
        type: string
      streetAddress:
        type: string
      postalCode:
        type: string
        description: A valid Norwegian postal code.
      postalPlace:
        type: string
      phoneNumber:
        type: string
        pattern: "\\+[0-9 ]+"
        description: A phone number including country code
        example: "+4700000000"
      email:
        type: string
        pattern: ".+@.+"
      weight:
        maximum: 2000
        type: integer
      shipmentNumber:
        type: string
        description: The shipment number for this package.
      packageNumber:
        type: string
        description: The package number for this package.
      agreementNumber:
        type: boolean
        description: Whether you got an agreement price for this package.
  ValidatedOrder:
    properties:
      id:
        type: number
      customerName:
        type: string
      customerOrganizationNumber:
        type: string
      customerNumber:
        type: string
      senderName:
        type: string
      streetAddress:
        type: string
      postalCode:
        type: string
        description: A valid Norwegian postal code.
      postalPlace:
        type: string
      email:
        type: string
        pattern: ".+@.+"
      reference:
        type: string
      priceWithoutVat:
        type: number
      priceWithVat:
        type: number
      vat:
        type: number
      currency:
        type: string
        default: NOK
      orderTime:
        type: datetime
      packages:
        minItems: 1
        type: ValidatedPackage[]
  ValidatedPackage:
    properties:
      priority:
        enum: [ A, B ]
        description: Delivery speed (A-post or B-post).
      rfid:
        type: boolean
        description: Whether to [tracking for the package](#tracking-with-rfid) was activated.
      recipientName:
        type: string
      streetAddress:
        type: string
      postalCode:
        type: string
        description: A valid Norwegian postal code.
      postalPlace:
        type: string
      phoneNumber:
        type: string
        pattern: "\\+[0-9 ]+"
        description: A phone number including country code
        example: "+4700000000"
      email:
        type: string
        pattern: ".+@.+"
      weight:
        maximum: 2000
        type: integer
      agreementNumber:
        type: boolean
        description: Whether you got an agreement price for this package.
  OrderRequest:
    type: object
    properties:
      data:
        type: object
        properties:
          type:
            type: string
            pattern: "orders"
          attributes: Order
  OrderResponse:
    type: object
    properties:
      data:
        type: object
        properties:
          type:
            type: string
            pattern: "order"
          id: string
          attributes: SuccessfulOrder
  ValidatedOrderResponse:
    type: object
    properties:
      data:
        type: object
        properties:
          type:
            type: string
            pattern: "order"
          id: string
          attributes: ValidatedOrder
  ErrorResponse:
    type: object
    properties:
      errors:
        type: ErrorObject[]
        description: See the [JSON-API documentation](http://jsonapi.org/format/#error-objects).
  ErrorObject:
    type: object
    properties:
      code:
        type: string
        description: Machine-readable description of error.
      title:
        type: string
        description: Human-readable description of error.
      source:
        type: object
        properties:
          pointer:
            type: string
            description: A JSON pointer to the associated entity of

documentation:
- title: Introduction
  content: |
      This API is for ordering [Pakke i postkassen](http://www.bring.no/sende/pakker/private-i-norge/pakke-i-postkassen) (Mailbox Delivery) shipments.

      The Mailbox Delivery service is available domestically in Norway, and will replace "Minipakke" and "Småpakker".

- title: Tracking with RFID
  content: |
      Mailbox Delivery shipments can optionally be ordered with tracking using RFID.

      #### How does tracking with RFID work?

      Normally, we create PDF labels that can be printed on any printer.

      If you opt for tracking, we create ZPL labels instead. ZPL stands for [Zebra Programming Language (ZPL)](https://en.wikipedia.org/wiki/Zebra_(programming_language)).

      The labels will be ZPL code containing instructions for programming the passive RFID antenna in the printer's labels with package numbers.

      In addition to the RFID programming instructions, the ZPL code contains instructions for rendering the rest of the label (addresses, icons, barcode, etc.).

      #### Special hardware required

      RFID-tagged labels require special printer hardware. Currently we support the following printers:

      - Zebra R410
      - Zebra 500R

- title: Without tracking
  content: |
      If you don't have a supported printer, you cannot order shipments with tracking. In this case, we will create normal PDF labels that can be printed using any printer.

- title: Authentication
  content: |
    The 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 |

    Those headers must be present for authenticating requests.

- title: JSON API
  content: |
      This API adheres to the [JSON API](http://jsonapi.org/) specification.

/:
  displayName: Order shipment
  description: |
      Order (or validate) a shipment.

      #### Error codes

      From the [JSON API specification](http://jsonapi.org/format/#error-objects),
      we use `code`, `title`, and `source.pointer` to describe errors.

      | Code | Meaning | Example pointer |
      | 500 | Internal, unknown aplpication error | `/` |
      | 1000 | Missing field value | `/streetAddress` |
      | 2000 | Order must contain at least one package | `/packages` |
      | 3000 | Invalid email address | `/packages/0/email` |
      | 4000 | Invalid postal code |  `/packages/1/postalCode` |
      | 5000 | User does not have access to customer number | `/customerNumber` |
      | 5500 | Customer hasn't made agreement with Posten to send "Pakke i postkassen" | `/customerNumber` |
      | 6000 | Weight cannot be more than 2000 grams | `/packages/2/weight` |
      | 7000 | Priority must be A or B | `/packages/3/priority` |
      | 8000 | Invalid phone number | `/pacakges/4/phoneNumber` |
      | 9000 | Invalid JSON API resource type (must be `orders`) | `/data/type` |

  post:
    description: Order shipment
    headers:
      Content-Type:
        description: Specify request format (application/json)
        required: true
        enum: [ application/json ]
      Accept:
        description: Specify response format (application/json)
        required: true
        enum: [ application/json ]
    queryParameters:
        validate:
            description: If this is set to true, the order will only be validated, not ordered in our production systems.
            type: boolean
            required: false
    body:
      application/json:
        example: !include examples/without_tracking_request.json
        type: OrderRequest
    responses:
      200:
        description: On a successful request, the response gives information about the booking. Most importantly it contains a link to the label for the shipment.
        body:
          application/json:
            type: ValidatedOrderResponse
            example: !include examples/validate_order_response.json
      201:
        description: On a successful request, the response gives information about the booking. Most importantly it contains a link to the label for the shipment.
        body:
          application/json:
            type: OrderResponse
            example: !include examples/without_tracking_response.json
      422:
        description: Validation error
        body:
          application/json:
            type: ErrorResponse
            example: !include examples/422.json
      500:
        description: If we have an error in our backend, we'll return a 500 error.
        body:
          application/json:
            type: ErrorResponse
            example: !include examples/500.json

/{orderId}:
  displayName: Fetch order
  uriParameters:
    orderId:
      type: string
      description: Id from when placing an order.
  get:
    description: Fetch previously ordered shipment
    headers:
      Accept:
        description: Specify response format (application/json)
        required: true
        enum: [ application/json ]
    responses:
      200:
        body:
          application/json:
            type: OrderResponse
            example: !include examples/without_tracking_response.json

#%RAML 1.0
---
title: Order to Mailbox API
version: v1
baseUri: https://api.bring.com/order/to-mailbox
mediaType: application/json
types:
  Order:
    type: object
    properties:
      customerNumber:
        type: string
      senderName:
        type: string
      senderEmail:
        required: false
        type: string
        pattern: ".+@.+"
        description: Defaults to the user's email address.
      postalCode:
        type: string
        description: A valid Norwegian postal code.
      streetAddress:
        type: string
      reference:
        required: true
      packages:
        minItems: 1
        type: Package[]
  Package:
    type: object
    properties:
      priority:
        enum: [ A, B ]
        description: Delivery speed (A-post or B-post).
      rfid:
        type: boolean
        description: Whether to activate [tracking for the package](#tracking-with-rfid)
      weight:
        maximum: 2000
        type: integer
      recipientName: string
      postalCode:
        type: string
        description: A valid Norwegian postal code.
      streetAddress:
        type: string
      phoneNumber:
        type: string
        pattern: "\\+[0-9 ]+"
        description: A phone number including country code
        example: "+4700000000"
      email:
        type: string
        pattern: ".+@.+"
  SuccessfulOrder:
    properties:
      id:
        type: number
      customerName:
        type: string
      customerOrganizationNumber:
        type: string
      customerNumber:
        type: string
      senderName:
        type: string
      streetAddress:
        type: string
      postalCode:
        type: string
        description: A valid Norwegian postal code.
      postalPlace:
        type: string
      email:
        type: string
        pattern: ".+@.+"
      reference:
        type: string
      labelUri:
        type: string
        description: URL to PDF label if ordered without tracking.
      rfidLabelUri:
        type: string
        description: URL to ZPL label if ordered with tracking.
      waybillUri:
        type: string
        description: URL to waybill PDF that goes with the order.
      priceWithoutVat:
        type: number
      priceWithVat:
        type: number
      vat:
        type: number
      currency:
        type: string
        default: NOK
      orderTime:
        type: datetime
      userEmail:
        required: false
        type: string
        description: The email address for the user that placed the order.
      userPhone:
        required: false
        type: string
        description: The phone number for the user that placed the order.
      userFullName:
        required: false
        type: string
        description: The name for the user that placed the order.
      orderNumberReference:
        type: string
        description: The order number reference for the placed order. This is the number on the waybill.
      packages:
        minItems: 1
        type: OrderedPackage[]
  OrderedPackage:
    properties:
      priority:
        enum: [ A, B ]
        description: Delivery speed (A-post or B-post).
      rfid:
        type: boolean
        description: Whether to [tracking for the package](#tracking-with-rfid) was activated.
      specialist:
        type: string
        description: The type of customer for which the order was placed.
      recipientName:
        type: string
      streetAddress:
        type: string
      postalCode:
        type: string
        description: A valid Norwegian postal code.
      postalPlace:
        type: string
      phoneNumber:
        type: string
        pattern: "\\+[0-9 ]+"
        description: A phone number including country code
        example: "+4700000000"
      email:
        type: string
        pattern: ".+@.+"
      weight:
        maximum: 2000
        type: integer
      shipmentNumber:
        type: string
        description: The shipment number for this package.
      packageNumber:
        type: string
        description: The package number for this package.
      agreementNumber:
        type: boolean
        description: Whether you got an agreement price for this package.
  ValidatedOrder:
    properties:
      id:
        type: number
      customerName:
        type: string
      customerOrganizationNumber:
        type: string
      customerNumber:
        type: string
      senderName:
        type: string
      streetAddress:
        type: string
      postalCode:
        type: string
        description: A valid Norwegian postal code.
      postalPlace:
        type: string
      email:
        type: string
        pattern: ".+@.+"
      reference:
        type: string
      priceWithoutVat:
        type: number
      priceWithVat:
        type: number
      vat:
        type: number
      currency:
        type: string
        default: NOK
      orderTime:
        type: datetime
      userEmail:
        type: string
        description: The email address for the user that placed the order.
      userPhone:
        type: string
        description: The phone number for the user that placed the order.
      userFullName:
        type: string
        description: The name for the user that placed the order.
      orderNumberReference:
        type: string
        description: The order number reference for the placed order. This is the number on the waybill.
      packages:
        minItems: 1
        type: ValidatedPackage[]
  ValidatedPackage:
    properties:
      priority:
        enum: [ A, B ]
        description: Delivery speed (A-post or B-post).
      rfid:
        type: boolean
        description: Whether to [tracking for the package](#tracking-with-rfid) was activated.
      recipientName:
        type: string
      streetAddress:
        type: string
      postalCode:
        type: string
        description: A valid Norwegian postal code.
      postalPlace:
        type: string
      phoneNumber:
        type: string
        pattern: "\\+[0-9 ]+"
        description: A phone number including country code
        example: "+4700000000"
      email:
        type: string
        pattern: ".+@.+"
      weight:
        maximum: 2000
        type: integer
      agreementNumber:
        type: boolean
        description: Whether you got an agreement price for this package.
  OrderRequest:
    type: object
    properties:
      data:
        type: object
        properties:
          type:
            type: string
            pattern: "orders"
          attributes: Order
  OrderResponse:
    type: object
    properties:
      data:
        type: object
        properties:
          type:
            type: string
            pattern: "order"
          id: string
          attributes: SuccessfulOrder
  ErrorResponse:
    type: object
    properties:
      errors:
        type: ErrorObject[]
        description: See the [JSON-API documentation](http://jsonapi.org/format/#error-objects).
  ErrorObject:
    type: object
    properties:
      code:
        type: string
        description: Machine-readable description of error.
      title:
        type: string
        description: Human-readable description of error.
      source:
        type: object
        properties:
          pointer:
            type: string
            description: A JSON pointer to the associated entity of

documentation:
- title: Introduction
  content: |
      This API is for ordering [Pakke i postkassen](http://www.bring.no/sende/pakker/private-i-norge/pakke-i-postkassen) (Mailbox Delivery) shipments.

      The Mailbox Delivery service is available domestically in Norway, and will replace "Minipakke" and "Småpakker".

- title: Tracking with RFID
  content: |
      Mailbox Delivery shipments can optionally be ordered with tracking using RFID.

      #### How does tracking with RFID work?

      Normally, we create PDF labels that can be printed on any printer.

      If you opt for tracking, we create ZPL labels instead. ZPL stands for [Zebra Programming Language (ZPL)](https://en.wikipedia.org/wiki/Zebra_(programming_language)).

      The labels will be ZPL code containing instructions for programming the passive RFID antenna in the printer's labels with package numbers.

      In addition to the RFID programming instructions, the ZPL code contains instructions for rendering the rest of the label (addresses, icons, barcode, etc.).

      #### Special hardware required

      RFID-tagged labels require special printer hardware. Currently we support the following printers:

      - Zebra R410
      - Zebra 500R

- title: Without tracking
  content: |
      If you don't have a supported printer, you cannot order shipments with tracking. In this case, we will create normal PDF labels that can be printed using any printer.

- title: Authentication
  content: |
    The 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 |

    Those headers must be present for authenticating requests.

- title: JSON API
  content: |
      This API adheres to the [JSON API](http://jsonapi.org/) specification.

/:
  displayName: Order shipment
  description: |
      Order (or validate) a shipment.

      #### Error codes

      From the [JSON API specification](http://jsonapi.org/format/#error-objects),
      we use `code`, `title`, and `source.pointer` to describe errors.

      | Code | Meaning | Example pointer |
      | 500 | Internal, unknown aplpication error | `/` |
      | 1000 | Missing field value | `/streetAddress` |
      | 2000 | Order must contain at least one package | `/packages` |
      | 3000 | Invalid email address | `/packages/0/email` |
      | 4000 | Invalid postal code |  `/packages/1/postalCode` |
      | 5000 | User does not have access to customer number | `/customerNumber` |
      | 5500 | Customer hasn't made agreement with Posten to send "Pakke i postkassen" | `/customerNumber` |
      | 6000 | Weight cannot be more than 2000 grams | `/packages/2/weight` |
      | 7000 | Priority must be A or B | `/packages/3/priority` |
      | 8000 | Invalid phone number | `/pacakges/4/phoneNumber` |
      | 9000 | Invalid JSON API resource type (must be `orders`) | `/data/type` |

  post:
    description: Order shipment
    headers:
      Content-Type:
        description: Specify request format (application/json)
        required: true
        enum: [ application/json ]
      Accept:
        description: Specify response format (application/json)
        required: true
        enum: [ application/json ]
    queryParameters:
        validate:
            description: If this is set to true, the order will only be validated, not ordered in our production systems.
            type: boolean
            required: false
    body:
      application/json:
        example: !include examples/without_tracking_request.json
        type: OrderRequest
    responses:
      201:
        description: On a successful request, the response gives information about the booking. Most importantly it contains a link to the label for the shipment.
        body:
          application/json:
            type: OrderResponse
            example: !include examples/without_tracking_response.json
      422:
        description: Validation error
        body:
          application/json:
            type: ErrorResponse
            example: !include examples/422.json
      500:
        description: If we have an error in our backend, we'll return a 500 error.
        body:
          application/json:
            type: ErrorResponse
            example: !include examples/500.json

/{orderId}:
  displayName: Fetch order
  uriParameters:
    orderId:
      type: string
      description: Id from when placing an order.
  get:
    description: Fetch previously ordered shipment
    headers:
      Accept:
        description: Specify response format (application/json)
        required: true
        enum: [ application/json ]
    responses:
      200:
        body:
          application/json:
            type: OrderResponse
            example: !include examples/without_tracking_response.json


Fix MD error that made the page not render properly

#%RAML 1.0
---
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 product texts.

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

      ### Why upgrade?

      * [Unified request and response model](/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 product on REST](/api/shipping-guide_2/#get-shipment-prices-and-estimated-delivery): Now you can specify multiple products 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 current API’s will not support future changes in our service offering.

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

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

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

      * [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](/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.

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

      Get API key

      ### 2. Add authentication headers
      A description of the headers can be found in [Getting Started / Authentication](/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 product `SERVICEPAKKE` for a single package being sent from the postal code 0015 to 5518 in Norway.

      ```
      <soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/"
                        xmlns:ns="http://www.bring.no/logistics/shippingguide/2.0">
          <soapenv:Header/>
          <soapenv:Body>
              <ns:ShippingGuideRequest xmlns:ns="http://www.bring.no/logistics/shippingguide/2.0">
                  <ns:RequestProperties>
                      <ns:Language>no</ns:Language>
                      <ns:Trace>false</ns:Trace>
                  </ns:RequestProperties>
                  <ns:Consignments>
                      <ns:Consignment consignmentId="101">
                          <ns:ProductIds>
                              <ns:ProductId>SERVICEPAKKE</ns:ProductId>
                              <ns:ProductId>PA_DOREN</ns:ProductId>
                          </ns:ProductIds>
                          <ns:FromCountryCode>NO</ns:FromCountryCode>
                          <ns:FromPostalCode>0015</ns:FromPostalCode>
                          <ns:ToCountryCode>NO</ns:ToCountryCode>
                          <ns:ToPostalCode>5518</ns:ToPostalCode>
                          <ns:ShippingDate>
                              <ns:Year>2018</ns:Year>
                              <ns:Month>10</ns:Month>
                              <ns:Day>10</ns:Day>
                          </ns:ShippingDate>
                          <ns:Packages>
                              <ns:Package>
                                  <ns:Height>19</ns:Height>
                                  <ns:Width>12</ns:Width>
                                  <ns:Length>30</ns:Length>
                                  <ns:GrossWeight>120</ns:GrossWeight>
                              </ns:Package>
                              <ns:Package>
                                  <ns:Height>30</ns:Height>
                                  <ns:Width>15</ns:Width>
                                  <ns:Length>22</ns:Length>
                                  <ns:GrossWeight>240</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 product level

        When we are not able to process one of the product requested, we will respond with a error on product level. Details of possible error codes are documented in [XSD](https://api.bring.com/shippingguide/api/ws/shipping-guide-2.0.xsd) and [WDSL](https://api.bring.com/shippingguide/api/ws/shippingguide-2.0.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. The client framework used by client must not crash when unknown elements 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 products needed since the response time of some products can be slow as compared to others
      * If the request is only to find the lead time / prices of different product, the flag for withExpectedDelivery / withPrices should be set to true and others can be set to false. In case of REST these are different endpoints.
      * For net prices requests should include customer number and correct package details
      * Request can include limited number of consignments in each request for quick response.
      * New shipments request can be part of separate request

/v2/products:
  displayName: Get shipment prices and estimated delivery
  description: Use this endpoint to get expected delivery, product 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
      Content-Type:
        description: The API key needed to create a new job
    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 products requested. Multiple products can be requested in a single request. Requested product can also be specified with a customer number separated with delimiter (**:**). For example CARGO**:**CARGO-123456
        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 products 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
      additional:
        displayName: Additional service
        description: Multiple additional 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 product is not supplied with delimited customer number, then it will be applied on all request products
        type: string
        example: CARGO-123456
        required: false
      language:
        description: Language used for the product 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

    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, product categories and additional information.
  post:
    description: Use this endpoint to get expected delivery, product categories and additional information.
    headers:
      X-MyBring-API-Uid:
        description: Your Mybring login ID
      X-MyBring-API-Key:
        description: Your user's API key
      Content-Type:
        description: The API key needed to create a new job

#%RAML 1.0
---
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 product texts.

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

      ### Why upgrade?

      * [Unified request and response model](/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 product on REST](/api/shipping-guide_2/#get-shipment-prices-and-estimated-delivery): Now you can specify multiple products 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 current API’s will not support future changes in our service offering.

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

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

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

      * [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](/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.

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

      Get API key

      ### 2. Add authentication headers
      A description of the headers can be found in [Getting Started / Authentication](/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 product `SERVICEPAKKE` for a single package being sent from the postal code 0015 to 5518 in Norway.

      ```
      <soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/"
                        xmlns:ns="http://www.bring.no/logistics/shippingguide/2.0">
          <soapenv:Header/>
          <soapenv:Body>
              <ns:ShippingGuideRequest xmlns:ns="http://www.bring.no/logistics/shippingguide/2.0">
                  <ns:RequestProperties>
                      <ns:Language>no</ns:Language>
                      <ns:Trace>false</ns:Trace>
                  </ns:RequestProperties>
                  <ns:Consignments>
                      <ns:Consignment consignmentId="101">
                          <ns:ProductIds>
                              <ns:ProductId>SERVICEPAKKE</ns:ProductId>
                              <ns:ProductId>PA_DOREN</ns:ProductId>
                          </ns:ProductIds>
                          <ns:FromCountryCode>NO</ns:FromCountryCode>
                          <ns:FromPostalCode>0015</ns:FromPostalCode>
                          <ns:ToCountryCode>NO</ns:ToCountryCode>
                          <ns:ToPostalCode>5518</ns:ToPostalCode>
                          <ns:ShippingDate>
                              <ns:Year>2018</ns:Year>
                              <ns:Month>10</ns:Month>
                              <ns:Day>10</ns:Day>
                          </ns:ShippingDate>
                          <ns:Packages>
                              <ns:Package>
                                  <ns:Height>19</ns:Height>
                                  <ns:Width>12</ns:Width>
                                  <ns:Length>30</ns:Length>
                                  <ns:GrossWeight>120</ns:GrossWeight>
                              </ns:Package>
                              <ns:Package>
                                  <ns:Height>30</ns:Height>
                                  <ns:Width>15</ns:Width>
                                  <ns:Length>22</ns:Length>
                                  <ns:GrossWeight>240</ns:GrossWeight>
                              </ns:Package>
                          </ns:Packages>
                      </ns:Consignment>
                  </ns:Consignments>
              </ns:ShippingGuideRequest>
          </soapenv:Body>
      </soapenv:Envelope>
      ```

      ### 5. Submit the request

      Post at:

      ```

        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 product level

        When we are not able to process one of the product requested, we will respond with a error on product level. Details of possible error codes are documented in [XSD](https://api.bring.com/shippingguide/api/ws/shipping-guide-2.0.xsd) and [WDSL](https://api.bring.com/shippingguide/api/ws/shippingguide-2.0.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. The client framework used by client must not crash when unknown elements 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 products needed since the response time of some products can be slow as compared to others
      * If the request is only to find the lead time / prices of different product, the flag for withExpectedDelivery / withPrices should be set to true and others can be set to false. In case of REST these are different endpoints.
      * For net prices requests should include customer number and correct package details
      * Request can include limited number of consignments in each request for quick response.
      * New shipments request can be part of separate request

/v2/products:
  displayName: Get shipment prices and estimated delivery
  description: Use this endpoint to get expected delivery, product 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
      Content-Type:
        description: The API key needed to create a new job
    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 products requested. Multiple products can be requested in a single request. Requested product can also be specified with a customer number separated with delimiter (**:**). For example CARGO**:**CARGO-123456
        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 products 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
      additional:
        displayName: Additional service
        description: Multiple additional 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 product is not supplied with delimited customer number, then it will be applied on all request products
        type: string
        example: CARGO-123456
        required: false
      language:
        description: Language used for the product 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

    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, product categories and additional information.
  post:
    description: Use this endpoint to get expected delivery, product categories and additional information.
    headers:
      X-MyBring-API-Uid:
        description: Your Mybring login ID
      X-MyBring-API-Key:
        description: Your user's API key
      Content-Type:
        description: The API key needed to create a new job


add verify_reset_password_token api

add verify_reset_password_token api

#%RAML 0.8
---
title: Starhackit
baseUri: http://localhost:8080/api/v1
version: v1
mediaType: application/json
protocols: [ HTTP, HTTPS ]
documentation:
 - title: User REST API
   content: 'User REST API documentation'

/auth:
  /login:
    description: 'Authenticate with the given username/email and password'
    post:
      body:
        application/json:
          schema: !include login/login.in.schema.json
          example: !include login/login.in.sample.json
      responses:
        200:
          body:
            example: !include login/login.out.sample.json
        401:
          description: 'Unauthorized'
          body:
            example: !include login/login.error.sample.json

  /logout:
    description: Logout
    post:
      responses:
        200:
          body:
            example: !include success.out.json

  /register:
    description: Request the creation of a new account.
    post:
      body:
        application/json:
          schema: !include register/register.in.schema.json
          example: !include register/register.in.sample.json
      responses:
        200:
          body:
            example: !include success.out.json
        422:
          body:
            example: !include register/register.error.sample.json

  /verify_email_code:
    description: Verify the code that was sent by email during the account registration.
    post:
      body:
        application/json:
          schema: !include verifyEmailCode/verifyEmailCode.in.schema.json
          example: !include verifyEmailCode/verifyEmailCode.in.sample.json
      responses:
        200:
          body:
            example: !include success.out.json

  /reset_password:
    description: Start a request to reset the password.
    post:
      body:
        application/json:
          schema: !include resetPassword/resetPassword.in.schema.json
          example: !include resetPassword/resetPassword.in.sample.json
      responses:
        200:
          body:
            example: !include success.out.json

  /verify_reset_password_token:
    description: Verify the reset password token.
    post:
      body:
        application/json:
          schema: !include verifyResetPasswordToken/verifyResetPasswordToken.in.schema.json
          example: !include verifyResetPasswordToken/verifyResetPasswordToken.in.sample.json
      responses:
        200:
          body:
            example: !include success.out.json
        422:
          body:
            example: !include verifyResetPasswordToken/verifyResetPasswordToken.error.sample.json
/me:
  description: Get information about the current authenticated user
  get:
    responses:
      200:
        body:
          example: !include user.out.sample.json
  patch:
    responses:
      204:

/users:
  description: Get all users
  get:
    responses:
      200:
        body:
          example: !include users.out.sample.json
  /{userId}:
    description: Get one user
    get:
      responses:
        200:
          body:
            example: !include user.out.sample.json

#%RAML 0.8
---
title: Starhackit
baseUri: http://localhost:8080/api/v1
version: v1
mediaType: application/json
protocols: [ HTTP, HTTPS ]
documentation:
 - title: User REST API
   content: 'User REST API documentation'

/auth:
  /login:
    description: 'Authenticate with the given username/email and password'
    post:
      body:
        application/json:
          schema: !include login/login.in.schema.json
          example: !include login/login.in.sample.json
      responses:
        200:
          body:
            example: !include login/login.out.sample.json
        401:
          description: 'Unauthorized'
          body:
            example: !include login/login.error.sample.json

  /logout:
    description: Logout
    post:
      responses:
        200:
          body:
            example: !include success.out.json

  /register:
    description: Request the creation of a new account.
    post:
      body:
        application/json:
          schema: !include register/register.in.schema.json
          example: !include register/register.in.sample.json
      responses:
        200:
          body:
            example: !include success.out.json
        422:
          body:
            example: !include register/register.error.sample.json

  /verify_email_code:
    description: Verify the code that was sent by email during the account registration.
    post:
      body:
        application/json:
          schema: !include verifyEmailCode/verifyEmailCode.in.schema.json
          example: !include verifyEmailCode/verifyEmailCode.in.sample.json
      responses:
        200:
          body:
            example: !include success.out.json

  /reset_password:
    description: Start a request to reset the password.
    post:
      body:
        application/json:
          schema: !include resetPassword/resetPassword.in.schema.json
          example: !include resetPassword/resetPassword.in.sample.json
      responses:
        200:
          body:
            example: !include success.out.json

/me:
  description: Get information about the current authenticated user
  get:
    responses:
      200:
        body:
          example: !include user.out.sample.json
  patch:
    responses:
      204:

/users:
  description: Get all users
  get:
    responses:
      200:
        body:
          example: !include users.out.sample.json
  /{userId}:
    description: Get one user
    get:
      responses:
        200:
          body:
            example: !include user.out.sample.json


Define Base RAML path relatively.

Define Base RAML path relatively.

#%RAML 0.8

title: Marathon REST
version: 2.0
mediaType: application/json
baseUri: ../
schemas:
  - AppDefinition: !include v2/schema/AppDefinition.json
  - Group: !include v2/schema/Group.json

traits: !include traits.raml

#documentation:
# - title: Using the Marathon REST API
#   content: Make me real!

# considered ofthen used endpoints in alphabetical order
/v2/apps: !include v2/apps.raml
/v2/deployments: !include v2/deployments.raml
/v2/groups: !include v2/groups.raml
/v2/groups/{group_id}: !include v2/groups.raml
/v2/tasks: !include v2/tasks.raml

# considered less used endpoints in alphabetical order
/v2/artifacts: !include v2/artifacts.raml
/v2/events: !include v2/events.raml
/v2/eventSubscriptions: !include v2/eventSubscriptions.raml
/v2/info: !include v2/info.raml
/v2/leader: !include v2/leader.raml
/v2/queue: !include v2/queue.raml

# no real API endpoints
/ping: !include general/ping.raml
/metrics: !include general/metrics.raml

#%RAML 0.8

title: Marathon REST
version: 2.0
mediaType: application/json
baseUri: /
schemas:
  - AppDefinition: !include v2/schema/AppDefinition.json
  - Group: !include v2/schema/Group.json

traits: !include traits.raml

#documentation:
# - title: Using the Marathon REST API
#   content: Make me real!

# considered ofthen used endpoints in alphabetical order
/v2/apps: !include v2/apps.raml
/v2/deployments: !include v2/deployments.raml
/v2/groups: !include v2/groups.raml
/v2/groups/{group_id}: !include v2/groups.raml
/v2/tasks: !include v2/tasks.raml

# considered less used endpoints in alphabetical order
/v2/artifacts: !include v2/artifacts.raml
/v2/events: !include v2/events.raml
/v2/eventSubscriptions: !include v2/eventSubscriptions.raml
/v2/info: !include v2/info.raml
/v2/leader: !include v2/leader.raml
/v2/queue: !include v2/queue.raml

# no real API endpoints
/ping: !include general/ping.raml
/metrics: !include general/metrics.raml