docs: fix sentence with typo than -> then

get:
  description:
    List all running deployments.
    A deployment is a change in the service setup.

    A deployment is identified by an id, affects a set of applications and is composed of deployment steps.

    Every step contains a list of actions with following types

    * StartApplication starts an application, which is currently not running.

    * StopApplication stops an already running application.

    * ScaleApplication changes the number of instances of an application and allows to kill specified instances while scaling.

    * RestartApplication upgrades an already deployed application with a new version.

    * ResolveArtifacts Resolve all artifacts of an application

  is: [ secured ]
  responses:
    200:
      description: "The list of all running deployments."
      body:
        application/json:
          example: !include examples/deployments.json

/{deployment_id}:
  delete:
    description: Revert the deployment with `deployment_id` by creating a new deployment which reverses
                 all changes.
    is: [ secured ]
    queryParameters:
      force:
        description: If set to false (the default) then the deployment is
                canceled and a new deployment is created to revert the changes of this
                deployment. Without concurrent deployments, this restores the configuration before this
                deployment. If set to true, then the deployment
                is still canceled but no rollback deployment is created.
        type: boolean
        default: false
    responses:
      200:
        description:
          A deployment is started which has a unique deployment identifier.
          The related deployment can be fetched from the /v2/deployments endpoint.
          If the deployement is gone from the list of deployments, it means that it is finished.
          As long as the deployment runs, the effect of that change operation is visible only partially.
        body:
          application/json:
            example: !include examples/deployments_result.json
      202:
        description:
          If the force flag is set to true, the deployment is canceled and no new deployment is triggered.
          In this case no body is returned.
      404:
        description: "The deployment plan with the given id can not be found."
        body:
          application/json:
            example: |
              { "message": "DeploymentPlan unknown_deployment does not exist" }

get:
  description:
    List all running deployments.
    A deployment is a change in the service setup.

    A deployment is identified by an id, affects a set of applications and is composed of deployment steps.

    Every step contains a list of actions with following types

    * StartApplication starts an application, which is currently not running.

    * StopApplication stops an already running application.

    * ScaleApplication changes the number of instances of an application and allows to kill specified instances while scaling.

    * RestartApplication upgrades an already deployed application with a new version.

    * ResolveArtifacts Resolve all artifacts of an application

  is: [ secured ]
  responses:
    200:
      description: "The list of all running deployments."
      body:
        application/json:
          example: !include examples/deployments.json

/{deployment_id}:
  delete:
    description: Revert the deployment with `deployment_id` by creating a new deployment which reverses
                 all changes.
    is: [ secured ]
    queryParameters:
      force:
        description: If set to false (the default) then the deployment is
                canceled and a new deployment is created to revert the changes of this
                deployment. Without concurrent deployments, this restores the configuration before this
                deployment. If set to true, then the deployment
                is still canceled but no rollback deployment is created.
        type: boolean
        default: false
    responses:
      200:
        description:
          A deployment is started which has a unique deployment identifier.
          The related deployment can be fetched from the /v2/deployments endpoint.
          If the deployement is gone from the list of deployments, than this means it is finished.
          As long as the deployment runs, the effect of that change operation is visible only partially.
        body:
          application/json:
            example: !include examples/deployments_result.json
      202:
        description:
          If the force flag is set to true, the deployment is canceled and no new deployment is triggered.
          In this case no body is returned.
      404:
        description: "The deployment plan with the given id can not be found."
        body:
          application/json:
            example: |
              { "message": "DeploymentPlan unknown_deployment does not exist" }


Pluralize all examples

Pluralize all examples

Makes it easier to write the documentation code, since we don't have to
support both a single `example` or multiple `examples`.

#%RAML 1.0
---
title: Order to Mailbox API
version: v1
baseUri: https://api.bring.com/order/to-mailbox
mediaType: application/json
annotationTypes:
  hideInDocumentation: boolean
  hideRequired: boolean
types:
  Order:
    type: object
    description: An order to place in Mybring.
    properties:
      customerNumber:
        type: string
        description: API customer number for which to place the order.
      senderName:
        type: string
        description: Sender's name.
        example: Min Bedrift
      senderEmail:
        required: false
        type: string
        pattern: ".+@.+"
        description: Sender's email address. Defaults to the user's email address.
      postalCode:
        type: string
        description: Sender's postal code. Must be a valid Norwegian postal code.
      streetAddress:
        type: string
        description: Sender's street address.
      reference:
        required: true
        description: A reference for the shipment (all packages).
      packages:
        minItems: 1
        type: Package[]
        description: The packages to send in this shipment.
  Package:
    type: object
    description: A single package in a shipment.
    properties:
      priority:
        enum: [ A, B ]
        description: Delivery speed (A-post or B-post).
      rfid:
        type: boolean
        description: Whether to activate [tracking with RFID](#tracking-with-rfid) for the package.
      weight:
        maximum: 2000
        type: integer
        description: Weight in grams.
      recipientName:
        type: string
        description: Recipient name.
      postalCode:
        type: string
        description: A valid Norwegian postal code.
      streetAddress:
        type: string
        description: Recipient's street address.
      phoneNumber:
        type: string
        pattern: "\\+[0-9 ]+"
        description: Recipient's phone number, including country code.
        example: "+4700000000"
      email:
        type: string
        pattern: ".+@.+"
        description: Recipient's email address.
  SuccessfulOrder:
    (hideRequired): true
    displayName: Successful Order
    description: A successfully placed order that contains links to labels and waybill.
    properties:
      id:
        type: number
        description: The ID of the order that was placed.
      customerNumber:
        type: string
        description: The API customer number for which the order was placed.
      customerName:
        type: string
        description: The name of the customer for which the order was placed.
      customerOrganizationNumber:
        type: string
        description: The organization number of the customer for which the order was placed.
      senderName:
        type: string
        description: Sender's name.
      streetAddress:
        type: string
        description: Sender's street address.
      postalCode:
        type: string
        description: Sender's postal code.
      postalPlace:
        type: string
        description: The city/place for the postal code.
      email:
        type: string
        pattern: ".+@.+"
        description: Sender's email address that for the order that was placed.
      reference:
        type: string
        description: A reference for the shipment (all packages)
      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
        description: Price of shipment without VAT (MVA).
      priceWithVat:
        type: number
        description: Price of shipment with VAT (MVA).
      vat:
        type: number
        description: How much of the price was VAT (MVA).
      currency:
        type: string
        default: NOK
        description: The currency for the price.
      orderTime:
        type: datetime
        example: 2017-09-01T14:00:00.000Z
        description: Timestamp for when the order was placed.
      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
        description: Packages in this shipment.
        type: OrderedPackage[]
  OrderedPackage:
    (hideRequired): true
    displayName: Ordered Package
    description: A single package in a successfully ordered shipment.
    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
        description: Recipient name.
      streetAddress:
        type: string
        description: Recipient's street address.
      postalCode:
        type: string
        description: Recipient's postal code.
      postalPlace:
        type: string
        description: The city/place for the postal code.
      phoneNumber:
        type: string
        pattern: "\\+[0-9 ]+"
        description: Recipient's phone number.
      email:
        type: string
        pattern: ".+@.+"
        description: Recipient's email address.
      weight:
        maximum: 2000
        type: integer
        description: Package weight in grams.
      shipmentNumber:
        type: string
        description: The shipment number for this package. A package in a PIP shipment will have both a shipment number and a package number.
      packageNumber:
        type: string
        description: The package number for this package. This goes on the label.
      agreementNumber:
        type: boolean
        description: Whether the customer has an agreement price for this package.
  ValidatedOrder:
    (hideRequired): true
    displayName: Validated Order
    description: A valid order that can be placed.
    properties:
      customerNumber:
        type: string
        description: The API customer number for the validated order.
      customerName:
        type: string
        description: The name of the customer for the validated order.
      customerOrganizationNumber:
        type: string
        description: The organization number of the customer for the validated order.
      senderName:
        type: string
        description: The sender's name.
      streetAddress:
        type: string
        description: The sender's street address.
      postalCode:
        type: string
        description: The sender's postal code.
      postalPlace:
        type: string
        description: The city/place for the postal code.
      email:
        type: string
        description: The sender's email address.
      reference:
        type: string
        description: A reference for the shipment (all packages).
      priceWithoutVat:
        type: number
        description: Calculated price without VAT (MVA).
      priceWithVat:
        type: number
        description: Calulated price with VAT (MVA).
      vat:
        type: number
        description: Calculated VAT (MVA).
      currency:
        type: string
        description: The price's currency.
      orderTime:
        type: datetime
        description: Timestamp for when the order was validated.
      packages:
        minItems: 1
        description: Packages in this validated shipment.
        type: ValidatedPackage[]
  ValidatedPackage:
    (hideRequired): true
    displayName: Validated Package
    description: A single, valid package in a valid shipment.
    properties:
      priority:
        enum: [ A, B ]
        description: Delivery speed (A-post or B-post).
      rfid:
        type: boolean
        description: Whether to [tracking with RFID](#tracking-with-rfid) was activated for the package.
      recipientName:
        type: string
        description: Recipient's name.
      streetAddress:
        type: string
        description: Recipient's email address.
      postalCode:
        type: string
        description: Recipient's postal code.
      postalPlace:
        type: string
        description: The city/place for the postal code.
      phoneNumber:
        type: string
        description: Recipient's phone number.
      email:
        type: string
        description: Recipient's email address.
      weight:
        type: integer
        description: Package weight in grams.
      agreementNumber:
        type: boolean
        description: Whether the customer has an agreement price for this package.
  OrderRequest:
    (hideInDocumentation): true
    type: object
    properties:
      data:
        type: object
        description: JSON-API data object.
        properties:
          type:
            type: string
            pattern: "orders"
            description: JSON-API type.
          attributes:
            type: Order
            description: Order properties.
  SuccessfulOrderResponse:
    (hideRequired): true
    (hideInDocumentation): true
    type: object
    properties:
      data:
        type: object
        description: JSON-API data object.
        properties:
          type:
            type: string
            description: JSON-API type.
          id: string
          attributes:
            type: SuccessfulOrder
            description: Order properties.
  ValidatedOrderResponse:
    (hideRequired): true
    (hideInDocumentation): true
    type: object
    properties:
      data:
        type: object
        description: JSON-API data object.
        properties:
          type:
            type: string
            pattern: "order"
            description: JSON-API type.
          attributes:
            type: ValidatedOrder
            description: Order properties.
  ErrorResponse:
    (hideRequired): true
    (hideInDocumentation): true
    type: object
    properties:
      errors:
        type: ErrorObject[]
        description: See the [JSON-API documentation](http://jsonapi.org/format/#error-objects).
  ErrorObject:
    (hideRequired): true
    (hideInDocumentation): true
    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
            examples:
              valid_order:
                displayName: Valid order
                value: !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: SuccessfulOrderResponse
            examples:
              with_tracking:
                displayName: With tracking
                value: !include examples/with_tracking_response.json
              without_tracking:
                displayName: Without tracking
                value: !include examples/without_tracking_response.json
      422:
        description: Validation error
        body:
          application/json:
            type: ErrorResponse
            examples:
              invalid_order:
                displayName: Invalid order
                value: !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
            examples:
              server_error:
                displayName: Server error
                value: !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:
        description: Success!!!!
        body:
          application/json:
            displayName: JSON response
            description: A response in the form of application/json
            type: SuccessfulOrderResponse
            examples:
              without_tracking:
                displayName: Without tracking
                value: !include examples/without_tracking_response.json
          application/vnd.api+json:
            displayName: Also JSON response
            description: A response in the form of application/vnd.api+json
            type: SuccessfulOrderResponse
            examples:
              without_tracking:
                displayName: Without tracking
                value: !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
annotationTypes:
  hideInDocumentation: boolean
  hideRequired: boolean
types:
  Order:
    type: object
    description: An order to place in Mybring.
    properties:
      customerNumber:
        type: string
        description: API customer number for which to place the order.
      senderName:
        type: string
        description: Sender's name.
        example: Min Bedrift
      senderEmail:
        required: false
        type: string
        pattern: ".+@.+"
        description: Sender's email address. Defaults to the user's email address.
      postalCode:
        type: string
        description: Sender's postal code. Must be a valid Norwegian postal code.
      streetAddress:
        type: string
        description: Sender's street address.
      reference:
        required: true
        description: A reference for the shipment (all packages).
      packages:
        minItems: 1
        type: Package[]
        description: The packages to send in this shipment.
  Package:
    type: object
    description: A single package in a shipment.
    properties:
      priority:
        enum: [ A, B ]
        description: Delivery speed (A-post or B-post).
      rfid:
        type: boolean
        description: Whether to activate [tracking with RFID](#tracking-with-rfid) for the package.
      weight:
        maximum: 2000
        type: integer
        description: Weight in grams.
      recipientName:
        type: string
        description: Recipient name.
      postalCode:
        type: string
        description: A valid Norwegian postal code.
      streetAddress:
        type: string
        description: Recipient's street address.
      phoneNumber:
        type: string
        pattern: "\\+[0-9 ]+"
        description: Recipient's phone number, including country code.
        example: "+4700000000"
      email:
        type: string
        pattern: ".+@.+"
        description: Recipient's email address.
  SuccessfulOrder:
    (hideRequired): true
    displayName: Successful Order
    description: A successfully placed order that contains links to labels and waybill.
    properties:
      id:
        type: number
        description: The ID of the order that was placed.
      customerNumber:
        type: string
        description: The API customer number for which the order was placed.
      customerName:
        type: string
        description: The name of the customer for which the order was placed.
      customerOrganizationNumber:
        type: string
        description: The organization number of the customer for which the order was placed.
      senderName:
        type: string
        description: Sender's name.
      streetAddress:
        type: string
        description: Sender's street address.
      postalCode:
        type: string
        description: Sender's postal code.
      postalPlace:
        type: string
        description: The city/place for the postal code.
      email:
        type: string
        pattern: ".+@.+"
        description: Sender's email address that for the order that was placed.
      reference:
        type: string
        description: A reference for the shipment (all packages)
      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
        description: Price of shipment without VAT (MVA).
      priceWithVat:
        type: number
        description: Price of shipment with VAT (MVA).
      vat:
        type: number
        description: How much of the price was VAT (MVA).
      currency:
        type: string
        default: NOK
        description: The currency for the price.
      orderTime:
        type: datetime
        example: 2017-09-01T14:00:00.000Z
        description: Timestamp for when the order was placed.
      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
        description: Packages in this shipment.
        type: OrderedPackage[]
  OrderedPackage:
    (hideRequired): true
    displayName: Ordered Package
    description: A single package in a successfully ordered shipment.
    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
        description: Recipient name.
      streetAddress:
        type: string
        description: Recipient's street address.
      postalCode:
        type: string
        description: Recipient's postal code.
      postalPlace:
        type: string
        description: The city/place for the postal code.
      phoneNumber:
        type: string
        pattern: "\\+[0-9 ]+"
        description: Recipient's phone number.
      email:
        type: string
        pattern: ".+@.+"
        description: Recipient's email address.
      weight:
        maximum: 2000
        type: integer
        description: Package weight in grams.
      shipmentNumber:
        type: string
        description: The shipment number for this package. A package in a PIP shipment will have both a shipment number and a package number.
      packageNumber:
        type: string
        description: The package number for this package. This goes on the label.
      agreementNumber:
        type: boolean
        description: Whether the customer has an agreement price for this package.
  ValidatedOrder:
    (hideRequired): true
    displayName: Validated Order
    description: A valid order that can be placed.
    properties:
      customerNumber:
        type: string
        description: The API customer number for the validated order.
      customerName:
        type: string
        description: The name of the customer for the validated order.
      customerOrganizationNumber:
        type: string
        description: The organization number of the customer for the validated order.
      senderName:
        type: string
        description: The sender's name.
      streetAddress:
        type: string
        description: The sender's street address.
      postalCode:
        type: string
        description: The sender's postal code.
      postalPlace:
        type: string
        description: The city/place for the postal code.
      email:
        type: string
        description: The sender's email address.
      reference:
        type: string
        description: A reference for the shipment (all packages).
      priceWithoutVat:
        type: number
        description: Calculated price without VAT (MVA).
      priceWithVat:
        type: number
        description: Calulated price with VAT (MVA).
      vat:
        type: number
        description: Calculated VAT (MVA).
      currency:
        type: string
        description: The price's currency.
      orderTime:
        type: datetime
        description: Timestamp for when the order was validated.
      packages:
        minItems: 1
        description: Packages in this validated shipment.
        type: ValidatedPackage[]
  ValidatedPackage:
    (hideRequired): true
    displayName: Validated Package
    description: A single, valid package in a valid shipment.
    properties:
      priority:
        enum: [ A, B ]
        description: Delivery speed (A-post or B-post).
      rfid:
        type: boolean
        description: Whether to [tracking with RFID](#tracking-with-rfid) was activated for the package.
      recipientName:
        type: string
        description: Recipient's name.
      streetAddress:
        type: string
        description: Recipient's email address.
      postalCode:
        type: string
        description: Recipient's postal code.
      postalPlace:
        type: string
        description: The city/place for the postal code.
      phoneNumber:
        type: string
        description: Recipient's phone number.
      email:
        type: string
        description: Recipient's email address.
      weight:
        type: integer
        description: Package weight in grams.
      agreementNumber:
        type: boolean
        description: Whether the customer has an agreement price for this package.
  OrderRequest:
    (hideInDocumentation): true
    type: object
    properties:
      data:
        type: object
        description: JSON-API data object.
        properties:
          type:
            type: string
            pattern: "orders"
            description: JSON-API type.
          attributes:
            type: Order
            description: Order properties.
  SuccessfulOrderResponse:
    (hideRequired): true
    (hideInDocumentation): true
    type: object
    properties:
      data:
        type: object
        description: JSON-API data object.
        properties:
          type:
            type: string
            description: JSON-API type.
          id: string
          attributes:
            type: SuccessfulOrder
            description: Order properties.
  ValidatedOrderResponse:
    (hideRequired): true
    (hideInDocumentation): true
    type: object
    properties:
      data:
        type: object
        description: JSON-API data object.
        properties:
          type:
            type: string
            pattern: "order"
            description: JSON-API type.
          attributes:
            type: ValidatedOrder
            description: Order properties.
  ErrorResponse:
    (hideRequired): true
    (hideInDocumentation): true
    type: object
    properties:
      errors:
        type: ErrorObject[]
        description: See the [JSON-API documentation](http://jsonapi.org/format/#error-objects).
  ErrorObject:
    (hideRequired): true
    (hideInDocumentation): true
    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: SuccessfulOrderResponse
            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:
        description: Success!!!!
        body:
          application/json:
            displayName: JSON response
            description: A response in the form of application/json
            type: SuccessfulOrderResponse
            example: !include examples/without_tracking_response.json
          application/vnd.api+json:
            displayName: Also JSON response
            description: A response in the form of application/vnd.api+json
            type: SuccessfulOrderResponse
            example: !include examples/without_tracking_response.json


Add details on how to handle errors in new API version

#%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 will allow you to easily get shipping methods for your new shipments. If you request applicable shipping methods with all 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 methods, meaning that the actual response can be shown in e.g. a web-shop checking without any sorting or filtering and with human readable service texts.

      The Shipping Guide API 2.0 has both a JSON and a SOAP interface. The JSON interface is typically used for a single service or similar services and is only for a single consignment. The SOAP interface can be used for multiple consignments and has the complete functionality of Shipping Guide API.

      ### Why upgrade?
      TODO: Create a text that sells this version to the end users

      * [Easier to handle errors](/api/shipping-guide_2/upgrade-to-version-2/#restructured-error-response)

      ### 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](/api/shipping-guide_2/upgrade-to-version-2) will help you on your way to version 2 of the Shipping Guide API.

- title: Getting started
  content: |
      This guide will walk you through getting shipment methods for your first package using Shipping Guide API. In this example, we will be calling the SOAP interface with a HTTP client and query for the services `SERVICEPAKKE` and `PA_DOREN` for two packages.

      ### Before you start
      Before you can begin integrating with or testing 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
      * [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 will be used when creating you request is available here.

      Get API key

      ### 2. Add authentication headers
      Authenticate your request by adding the three headers: Your Mybring username, API key and a client URL. A description of the headers can be found in [Getting Started / Authentication](/api/#authentication).

      ### 3. Add additional headers
      Since we're using the SOAP interface we'll have to add the following header:

      - `Content-type: text/xml` TODO: Is this right?

      If you're using a SOAP client it may be that this is done for you, meaning you can skip this step.

      ### 4. Add the body to the request
      In this request we'll be querying 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:RequestProperties>
                      <ns:Language>no</ns:Language>
                  </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
      The request should now be complete, so now it is time to submit it.

      TODO: Write better text
      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:TraceMessages>
                      <ns2:Message>Defaulting to current time of day as no hour and minute component present in date time element.</ns2:Message>
                      <ns2:Message>Added fee 'brev-varsling' (NOK 13.00) to base price of SERVICEPAKKE since request did not have additional service 'eVarsling' specified.</ns2:Message>
                  </ns2:TraceMessages>
                  <ns2:Consignments>
                      <ns2:Consignment consignmentId="101">
                          <ns2:Products>
                              <ns2:Product>
                                  <ns2:ProductId>SERVICEPAKKE</ns2:ProductId>
                                  <ns2:ProductCodeInProductionSystem>1202</ns2:ProductCodeInProductionSystem>
                                  <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:Tip/>
                                      <ns2:MaxWeightInKgs>35</ns2:MaxWeightInKgs>
                                  </ns2:GuiInformation>
                                  <ns2:Price currencyIdentificationCode="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: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:ProductId>PA_DOREN</ns2:ProductId>
                                  <ns2:ProductCodeInProductionSystem>1736</ns2:ProductCodeInProductionSystem>
                                  <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:Tip/>
                                      <ns2:MaxWeightInKgs>35</ns2:MaxWeightInKgs>
                                  </ns2:GuiInformation>
                                  <ns2:Price currencyIdentificationCode="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:Price>
                                  <ns2:ExpectedDelivery>
                                      <ns2:WorkingDays/>
                                      <ns2:UserMessage>Ingen fremsendingstidsgaranti for oppgitt tilpostnummer.</ns2:UserMessage>
                                      <ns2:FormattedExpectedDeliveryDate/>
                                      <ns2:AlternativeDeliveryDates/>
                                      <ns2:FormattedEarliestPickupDate/>
                                  </ns2:ExpectedDelivery>
                              </ns2:Product>
                          </ns2:Products>
                      </ns2:Consignment>
                  </ns2:Consignments>
              </ns2:ShippingGuideResponse>
          </SOAP-ENV:Body>
      </SOAP-ENV:Envelope>
      ```

- title: Shipping Guide topics
  content: |
      TODO: If you want to know more about cornercases/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 e.g. a timeout occurs.

      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 code. In case of SOAP, we gives out detailed info of error along with error code which can be parsed easily programmatically, making it easier to understand the reason of failure.
        No longer need to depend on messages in fault to identify reason of failure.

        ```
        <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 a service 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 code are well 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: Response structure
  content: |
      If you request shipping methods via API, you will receive an object which complies to the following schemas:

      #### SOAP

      [https://api.bring.com/shippingguide/api/ws/shipping-guide-2.0.xsd](https://api.bring.com/shippingguide/api/ws/shipping-guide-2.0.xsd)

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

      #### JSON

      [https://api.bring.com/shippingguide/v2/products/schema](https://api.bring.com/shippingguide/v2/products/schema)

- 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 services, the flag for withExpectedDelivery / withPrices should be set to true and others can be set to false
      * 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/services:
  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
      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
      additional:
        displayName: Additional service
        description: Multiple additional services can be requested by repeating this parameter
        required: false
        type: string
      service:
        description: Multiple services can be requested by repeating this parameter
        type: string
        required: true
      customernumber:
        description: Lets you specify which customer number to use in the request
        type: string
        example: CARGO-123456
      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

    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/services/price:
  displayName: Get shipment prices
  description: |
      Use this endpoint to get prices, product categories and additional information. The request parameters are the same as for [Get shipment prices and estimated delivery](/api/shipping-guide_v2/#get-shipment-prices-and-estimated-delivery)
  get:
    description: Use this endpoint to get price, product categories and additional information such as an indication of which alternative has the least environmental impact. 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/services/expectedDelivery:
  displayName: Get expected delivery times
  description: |
      Use this endpoint to get expected delivery, product categories and additional information. The request parameters are the same as for [Get shipment prices and estimated delivery](/api/shipping-guide_v2/#get-shipment-prices-and-estimated-delivery)
  get:
    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 will allow you to easily get shipping methods for your new shipments. If you request applicable shipping methods with all 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 methods, meaning that the actual response can be shown in e.g. a web-shop checking without any sorting or filtering and with human readable service texts.

      The Shipping Guide API 2.0 has both a JSON and a SOAP interface. The JSON interface is typically used for a single service or similar services and is only for a single consignment. The SOAP interface can be used for multiple consignments and has the complete functionality of Shipping Guide API.

      ### Why upgrade?
      TODO: Create a text that sells this version to the end users

      * [Easier to handle errors](/api/shipping-guide_2/upgrade-to-version-2/#restructured-error-response)

      ### 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](/api/shipping-guide_2/upgrade-to-version-2) will help you on your way to version 2 of the Shipping Guide API.

- title: Getting started
  content: |
      This guide will walk you through getting shipment methods for your first package using Shipping Guide API. In this example, we will be calling the SOAP interface with a HTTP client and query for the services `SERVICEPAKKE` and `PA_DOREN` for two packages.

      ### Before you start
      Before you can begin integrating with or testing 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
      * [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 will be used when creating you request is available here.

      Get API key

      ### 2. Add authentication headers
      Authenticate your request by adding the three headers: Your Mybring username, API key and a client URL. A description of the headers can be found in [Getting Started / Authentication](/api/#authentication).

      ### 3. Add additional headers
      Since we're using the SOAP interface we'll have to add the following header:

      - `Content-type: text/xml` TODO: Is this right?

      If you're using a SOAP client it may be that this is done for you, meaning you can skip this step.

      ### 4. Add the body to the request
      In this request we'll be querying 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:RequestProperties>
                      <ns:Language>no</ns:Language>
                  </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
      The request should now be complete, so now it is time to submit it.

      TODO: Write better text
      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:TraceMessages>
                      <ns2:Message>Defaulting to current time of day as no hour and minute component present in date time element.</ns2:Message>
                      <ns2:Message>Added fee 'brev-varsling' (NOK 13.00) to base price of SERVICEPAKKE since request did not have additional service 'eVarsling' specified.</ns2:Message>
                  </ns2:TraceMessages>
                  <ns2:Consignments>
                      <ns2:Consignment consignmentId="101">
                          <ns2:Products>
                              <ns2:Product>
                                  <ns2:ProductId>SERVICEPAKKE</ns2:ProductId>
                                  <ns2:ProductCodeInProductionSystem>1202</ns2:ProductCodeInProductionSystem>
                                  <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:Tip/>
                                      <ns2:MaxWeightInKgs>35</ns2:MaxWeightInKgs>
                                  </ns2:GuiInformation>
                                  <ns2:Price currencyIdentificationCode="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: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:ProductId>PA_DOREN</ns2:ProductId>
                                  <ns2:ProductCodeInProductionSystem>1736</ns2:ProductCodeInProductionSystem>
                                  <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:Tip/>
                                      <ns2:MaxWeightInKgs>35</ns2:MaxWeightInKgs>
                                  </ns2:GuiInformation>
                                  <ns2:Price currencyIdentificationCode="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:Price>
                                  <ns2:ExpectedDelivery>
                                      <ns2:WorkingDays/>
                                      <ns2:UserMessage>Ingen fremsendingstidsgaranti for oppgitt tilpostnummer.</ns2:UserMessage>
                                      <ns2:FormattedExpectedDeliveryDate/>
                                      <ns2:AlternativeDeliveryDates/>
                                      <ns2:FormattedEarliestPickupDate/>
                                  </ns2:ExpectedDelivery>
                              </ns2:Product>
                          </ns2:Products>
                      </ns2:Consignment>
                  </ns2:Consignments>
              </ns2:ShippingGuideResponse>
          </SOAP-ENV:Body>
      </SOAP-ENV:Envelope>
      ```

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

- title: Handle API errors
  content: |
      The Shipping Guide API return two levels of error information:

      * HTTP error codes or SOAP fault with a message in the body
      * An error object in the response that is on a service level

      TODO: Write about the 2 and when they typically occur

      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 e.g. a timeout occurs.

      TODO: Write about error ID (code) and that texts (trace and error descriptions) should not be parsed...blablabla

- title: Response structure
  content: |
      If you request shipping methods via API, you will receive an object which complies to the following schemas:

      #### SOAP

      [https://api.bring.com/shippingguide/api/ws/shipping-guide-2.0.xsd](https://api.bring.com/shippingguide/api/ws/shipping-guide-2.0.xsd)

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

      #### JSON

      [https://api.bring.com/shippingguide/v2/products/schema](https://api.bring.com/shippingguide/v2/products/schema)

- 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 services, the flag for withExpectedDelivery / withPrices should be set to true and others can be set to false
      * 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/services:
  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
      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
      additional:
        displayName: Additional service
        description: Multiple additional services can be requested by repeating this parameter
        required: false
        type: string
      service:
        description: Multiple services can be requested by repeating this parameter
        type: string
        required: true
      customernumber:
        description: Lets you specify which customer number to use in the request
        type: string
        example: CARGO-123456
      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

    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/services/price:
  displayName: Get shipment prices
  description: |
      Use this endpoint to get prices, product categories and additional information. The request parameters are the same as for [Get shipment prices and estimated delivery](/api/shipping-guide_v2/#get-shipment-prices-and-estimated-delivery)
  get:
    description: Use this endpoint to get price, product categories and additional information such as an indication of which alternative has the least environmental impact. 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/services/expectedDelivery:
  displayName: Get expected delivery times
  description: |
      Use this endpoint to get expected delivery, product categories and additional information. The request parameters are the same as for [Get shipment prices and estimated delivery](/api/shipping-guide_v2/#get-shipment-prices-and-estimated-delivery)
  get:
    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