Update api.raml

Update api.raml

#%RAML 0.8
---
title: Booking API
baseUri: https://api.bring.com/booking/api

documentation:
- title: Introduction
  content: |

        Important notice: Mailbox Packet API will be decomissioned on 13.01.2020

        A simplified and enhanced version of Mailbox parcel (Pakke i postkassen) will be launched on 13.01.2020. From the same date, the Mailbox Packet API will be decomissioned, and the revitalized Mailbox parcel service will be booked via Booking API like other Bring-services. If you don't already use the Booking API, we strongly recommend that you start setting up the integration now.

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

      The Bring Booking API is a logged-in service that lets Mybring users (customers of Mybring) programatically create a booking by invoking a Web Service over SOAP or by posting XML/JSON over HTTP. The API uses the same backend as [Mybring Booking](https://www.mybring.com/booking/) and the same PDF labels.

      We support two types of integration with the Booking API. XML/JSON over HTTP and SOAP (over HTTP).

      Booking uses Shipping Guide as the source for price and availability for the different services. We advise clients of the Booking API to use [Shipping Guide API](/api/shipping-guide_2/) for getting the list price and checking availability before sending a booking request. Note that invoice payment is the only available payment option for the Booking API. This means that the Mybring user ID used in the booking request must have access to the customer number specified as payer of the booking.

      This API has similarities with the Shipment API, but there are differences. Read more about the [differences between the Booking API and the Shipment API](/api/booking-shipment/).

- title: Versioning strategy
  content: |
      Each request has a `schemaVersion` element indicating which release of the schema is being used in the request and expected schema format in the response. 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 thus not crash when unknown elements are encountered. Note that this requirement excludes the (old, but still widely used) Apache Axis 1.x Web Service client framework.

- title: Encoding
  content: |
    Booking endpoints will assume all requests are UTF-8 encoded

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

- title: Authorization
  content: |
    In addition to authentication, you need to be authorized with the _booking_ right in order to perform bookings. This is done in [customer administration in Mybring](https://www.mybring.com/useradmin/external/administration):

    ![Authorized for booking](booking_authorization.png)

    To perform a booking, you must specify which customer number to use. For your convenience, there is an [API for getting the customer numbers](#list-customer-numbers) associated with your API user. The Customer Number API also links customer numbers with the services the customer number is valid for.

- title: Making labels
  content: |
    The Booking API generates and sends all necessary EDI messages to carry out the shipment. A URL to a PDF label is returned in responses. This label must be printed and be attached to the shipment. A URL that points to tracking information is also returned.

    A GET request to the label URL will result in a HTTP 302 redirect to the concrete storage facility (e.g. redirect to Amazon S3). Ensure that your client follows these redirects.

- title: Performance
  content: |
    Different service groups have different response times in booking:

    - Parcels and courier services
      - A booking will typically take < 2 seconds
    - Express UPS services and Cargo
      - A booking will typically take < 3 seconds
    - Express Nordic SameDay
      - A booking will typically take < 10 seconds (query in flight schedules). We are working on improving the response times for QuickPack SameDay, making popular city-pairs much faster.

- title: Mailbox Parcel (Pakke i Postkassen)
  content: |
    From January 13. 2020, Mailbox Parcel is booked via the Booking API.

    Until then, the service will be possible to test-book (i.e. no real booking will happen and charges will not occur) to verify the API integration. We recommend doing this, especially if this is the first time integrating with the Booking API. Please note that it is possible to book Mailbox Parcel via Mybring's web solution if, for any reason, your integration with Booking API is not in place by January 13. 2020.

    #### What is new compared with today's Mailbox Parcel service?

    - Booking Mailbox Parcel in Booking API is a single-step process with one label per booking (as today's service, multi-kolli is not supported). Each parcel will be invoiced separately. A link to the label is returned in the response.
    - No waybill is generated, as each parcel is invoiced based on the weight registered at the terminal. The minimum price of 150,- per order is removed.
    - When booking Mailbox Parcel in Booking API, the new API customer number is used. This is identical to your company's main customer number (without prefix PARCELS_NORWAY and without padded zeros if any).
    - When booking Mailbox Parcel in Booking API, the service is defined by setting 3584 or 3570 in the product id.

    To book, order one of the two product ids:

    ### 3584 (tracking with RFID)
    Mailbox Parcel 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

    ### 3570 (no tracking)
    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.

    ### Additional Service : Bag on door (Pose på døren)
    A delivery alternative for Mailbox Parcels that cannot be delivered to the mailbox.

    Mailbox Parcel (Pakke i postkassen) is a parcel that will be delivered in the recipient’s mailbox. If the parcel for various reasons does not fit in the mailbox, the sender may, against a surcharge of NOK 15 per shipment, choose to leave the parcel on the door handle (in a special bag) to avoid it being sent to the pickup point (surcharge of NOK 23 per shipment). This delivery option will have to be confirmed by the receiver upon booking in the sender's webshop. When the parcel is delivered as a bag on the door, the bar code is scanned and the recipient will receive an SMS/email. Note that if the parcel is delivered in the mailbox the additional fee will not occur.

    #### Terms of delivery

    The sender must clearly inform the recipient about the criteria of Bag on door when displaying this service in the check out (e.g. via Shipping Guide API):

    - The distance from the mailbox to the recipient's door must not exceed 250 m
    - House no. must be clearly marked
    - The door must be clearly marked with the recipient's name
    - Posten must have access to the recipient's door, even when the main entrance is locked, for instance when recipient live in an apartment.

    Knowing these critera, the recipient must actively accept Bag on door as a delivery option.

    In cases where the criterias are not met, i.e. bad weather (risk of damage) or where for security reason the risk is considered too high to use Bag on door, the parcel will still be delivered to the recipient's pickup point for delivery.

    ### Example request
    There is an example request for 3584 in "More examples" section below. Booking 3570 is just a matter of changing the service code from 3584 to 3570.

- title: Customs information
  content: |
    It is required to pass customs information when booking the following services from Norway -> abroad:

    - Business Parcel
    - PickUp Parcel

    When included during booking, the customs information will be sent electronically from Bring to the destination country.

    If sending customs information, the following elements are to be used:

    - quantity (required)
    - goodsDescription (required)
    - customsArticleNumber (optional)
    - itemNetWeightInKg (required)
    - tarriffLineAmount (required)
    - currency (required)
    - countryOfOrigin (optional)
    - natureOfTransaction (required)

    Please refer to the _Request params_ section below for more details about the elements. Customs tariff codes (tolltariffnummer) can be found [here](http://tolltariffen.toll.no/).

    #### Example

    In this example, you are sending a parcel/shipment with 2 shampoos, 5 cotton t-shirts and 1 wool jacket. The number of pieces is 8 (2 shampoos + 5 cotton
    t-shirts + 1 wool jacket), and the number of articles is 3 (shampoo, cotton t-shirt, wool jacket). The whole shipment is referred to as an item.

    | Quantity | Description of contents | Customs tariff code | Total content net weight (kg) | Total content value | Currency | Country of origin |
    |:--------:|:-----------------------:|:-------------------:|:----------------------------:|:-------------------:|:--------:|:-----------------:|
    | `2` | `shampoo` | `33.05.1000` | `3.0` | `200` | `NOK` | `CH`|
    | `5` | `cotton t-shirts` | `61.09.1000` | `2.5` | `1000`| `NOK`| `PL` |
    | `1` | `wool jacket` | `61.04.3100` | `2.0` | `750` | `NOK`| `DE` |

    Nature of Transaction: Gift or Sale of Goods or Returned Goods or Commercial Sample or Documents or Other

    Sending `Importer` party in the request is not mandatory. But if there is no importer sent then system will consider recipient as importer.

    Another additional field captured for customs is `vatNumber` for the parties. This is an optional field. If you are setting importer party then you can add `vatNumber` in it,
    else you can set `vatNumber` in the existing recipient party.

    There are two examples in the _More Examples_ section below that show requests containing customs information.
    * In one of these examples, importer not sent in request, hence the recipient is the importing party with (optional) `vatNumber`.
    * In the other example, there is importer party set in the request with the (optional) `vatNumber`.

/customers{mediaTypeExtension}:
  displayName: List customer numbers
  description: |
      The customer numbers are prefixed with the specialist, followed by the number. For Courier and Bring Express-services, we use a UUID to identify users.

      The customer API will return for each specialist a list with the services that you can order through the booking API.

      You can also get the API customer numbers from [this page in Mybring](https://www.mybring.com/useradmin/account/settings#customerApiKeyContainer).

      | Specialist | Example services | Example customer number |
      |:-----------|:-----------------|:------------------------|
      | Bring Parcels, Norway | `BPAKKE_DOR-DOR`, `PA_DOREN`, `EKSPRESS09`, `3584` | `PARCELS_NORWAY-10001123123` |
      | Bring Cargo, Norway | `CARGO_GROUPAGE` | `CARGO-329511` |
      | Bring Cargo, International | `CARGO_INTERNATIONAL` | `CARGO-803739` |
      | Bring Express, Norway | `COURIER_4H`, `EXPRESS_NORDIC_SAME_DAY`, `EXPRESS_INTERNATIONAL` | `EXPRESS_NORWAY-2caedf20-27da-012f-3858-58b0357c4f66` |
      | Bring Express, Sweden | `COURIER_4H`, `EXPRESS_NORDIC_SAME_DAY`, `EXPRESS_INTERNATIONAL` | `EXPRESS_SWEDEN-406077f0-27da-012f-3859-58b0357c4f66` |
      | Oil Express, Norway | `OIL_EXPRESS` | `SYSPED_NORWAY-12345` |
      | Frigo, Norway | `FRIGO` | `FRIGO-123456` |

      [Check out this page](/api/services/#booking) to see the whole list of services for each customer type.

  uriParameters:
    mediaTypeExtension:
      enum: [ .json, .xml ]
      description: Use .json to specify application/json or .xml to specify application/xml
  get:
    description: List customer numbers and services
    responses:
      200:
        displayName: List of available customers and services
        body:
          application/json:
            example: !include examples/customers.json
          application/xml:
            example: !include examples/customers.xml

/booking:
  displayName: Book shipments
  description: |
      This is the endpoint where you can book a shipment and get a printable label in return.

      #### Value added services

      The following services have available value added services:

      | Services | Value added services |
      |:--------|:--------------------|
      | SERVICEPAKKE | POSTOPPKRAV, EVARSLING |
      | BPAKKE_DOR-DOR | EVARSLING, SIMPLE_DELIVERY, deliveryOption |
      | PA_DOREN | EVARSLING, SIMPLE_DELIVERY |
      | EKSPRESS09 | EVARSLING, LORDAGSUTKJORING |
      | PICKUP_PARCEL | POSTOPPKRAV, FLEX_DELIVERY, EVARSLING, deliveryOption |
      | PICKUP_PARCEL_BULK | POSTOPPKRAV, FLEX_DELIVERY, EVARSLING, deliveryOption |
      | HOME_DELIVERY_PARCEL | POSTOPPKRAV, FLEX_DELIVERY, EVARSLING |
      | BUSINESS_PARCEL | POSTOPPKRAV, FLEX_DELIVERY, EVARSLING, PHONENOTIFICATION, DELIVERY_INDOOR |
      | BUSINESS_PARCEL_BULK | POSTOPPKRAV, FLEX_DELIVERY, EVARSLING, PHONENOTIFICATION, DELIVERY_INDOOR |
      | EXPRESS_NORDIC_0900_BULK | POSTOPPKRAV, FLEX_DELIVERY, EVARSLING, PHONENOTIFICATION, DELIVERY_INDOOR |
      | BUSINESS_PALLET | FLEX_DELIVERY, EVARSLING, PHONENOTIFICATION, DELIVERY_INDOOR |
      | BUSINESS_HALFPALLET | FLEX_DELIVERY, EVARSLING, PHONENOTIFICATION, DELIVERY_INDOOR |
      | BUSINESS_QUARTERPALLET | FLEX_DELIVERY, EVARSLING, PHONENOTIFICATION, DELIVERY_INDOOR |
      | EXPRESS_NORDIC_0900 | FLEX_DELIVERY, EVARSLING, PHONENOTIFICATION, DELIVERY_INDOOR |
      | 3570 | SIMPLE_DELIVERY |
      | 3584 | SIMPLE_DELIVERY |

      See the "More examples" section below to see examples on how to use value added services.

      We have added a new tag and by that a new way of requesting value added services. Both ways are still supported, but they can not be combined.

      * All the new value added services will be added supporting only the new way.

      * The old way will be decommissioned after some time.

      Where you before had to send each additional service as a tag under the services tag, the new way has a list of additionalService tags under the additionalServices tag, where the id element identify the additonal service to request.

       XML

      ```
       <additionalServices>
          <additionalService>
            <id>EVARSLING</id>
            <email>sender@sender.com</email>
            <mobile>12345</mobile>
          </additionalService>
          <additionalService>
            <id>DANGEROUS_GOODS</id>
            <mobile>777777</mobile>
            <unNumber>ABC</unNumber>
          </additionalService>
       </additionalServices>
      ```

       JSON

      ```
        "additionalServices": [
                  {
                    "id": "DANGEROUS_GOODS",
                    "unNumber": "ABC"
                  },
                  {
                    "id": "EVARSLING",
                    "email": "recipient@recipient.com",
                    "mobile": "97777777"
                  }
        ]
      ```

       The old way of requesting additional servies:

      ```
        <services>
           <simpleDelivery>true</simpleDelivery>
           <flexDelivery>
              <message>
                 Legg pakken i garasjen.
              </message>
           </flexDelivery>
        </services>

      ```

      #### Error handling

      If an error occurs, the following will be provided:

      - `uniqueId`: A unique log ID (UUID) that can be used as a reference for the error
      - `code`: An error code describing the error
      - `message`: Internationalized messages (with <message lang="”xx”"> elements). First version will be with lang=”en” (English) only. </message>

      See the [error codes](#error-codes) below to get an overview of error codes and what they mean.

      #### Testing

      This service will send actual production orders unless it is set to testing mode.

      To use the test mode, you need to set the `testIndicator` flag to `true` on the root node.

      Note that the examples below use `testIndicator=true`, so remove this when implementing the Booking API in your production system.

  post:
    description: Make a booking
    headers:
      Content-Type:
        description: Specify request format (application/json, application/xml)
        required: true
        enum: [ application/json, application/xml ]
      Accept:
        description: Specify response format (application/json, application/xml)
        required: false
        default: same as Content-Type
        enum: [ application/json, application/xml ]
    queryParameters:
        testIndicator:
            description:  It is true for test orders.
            type: boolean
            example: false
            required: true
        schemaVersion:
            description: Currently, it is 1
            type: integer
            example: 1
            required: true
        shippingDateTime:
            description: The date and time when an order is ready to be transported. The label generated against a booking will be valid for 52 weeks when Bring receives the request for an order.
            type: dateTime
            example: 2016-07-26T06:24:09 or 1469494449000 (for json req)
            required: true
        customerNumber:
            description: Specify API customer number. This parameter can be maximum 35 character long.
            type: string
            example: PARCELS_NORWAY-*********
            required: true
        addressLine:
            description: Specify address. This parameter can be maximum 35 character long.
            type: string
            example: Testsvingen 12
            required: true
        addressLine2:
            description: Specify address line 2. This parameter can be 35 character long.
            type: string
        purchaseOrderNumber:
            type: string
            description: Specify when there is any purchase orders associated with the booking. This parameter can be maximum 35 character long.
        weightInKg:
            description: Specify weight in kilograms
            type: double
            example: 15.2
            required: true
        goodsDescription:
            description: This can be used in three different elements; `package`(optional), `packageGroup`(optional), and `ediCustomsDeclaration`(required). It describes what is inside the package. This parameter can be maximum 35 characters long.
            type: string
        heightInCm:
            description: Specify height in cm. Dimension is optional when volumeInDm3 is specified in the request for cargo.
            type: integer
            example: 100
            required: true
        widthInCm:
            description: Specify width in cm. Dimension is optional when volumeInDm3 is specified in the request for cargo.
            type: integer
            example: 100
            required: true
        lengthInCm:
             description: Specify length in cm. Dimension is optional when volumeInDm3 is specified in the request for cargo.
             type: integer
             example: 100
             required: true
        numberOfItems:
             description: Specify number of items within a package
             type: integer
             example: 5
             required: true
        volumeInDm3:
             description: Specify volume in cubic decimeter. This is optional when dimension is specified in the request for cargo.
             type: decimal
             required: true
        numberOfPallets:
             description: Specify Number of pallets when request is for Cargo
             type: integer
             required: false
             example: 3
        loadMeters:
             description: Specify Load meters when request is for Cargo. Maximum value is 49.9
             type: double
             required: false
             example: 2.0
        whoPaysInvoice:
             description: Specify which party will pay the invoice for the booking. This parameter can be maximum 35 character long.
             type: string
             enum: [sender, recipient, thirdParty]
        accountNumber:
             description: Specify account number for cash on delivery. This parameter can be maximum 35 character long.
             type: string
             example: 12345678903
             required: true
        accountType:
             description: Specify account type. This parameter can be maximum 35 character long.
             type: string
             enum: [bankgiro,plusgiro]
        amount:
             description: Specify amount
             type: double
        currencyCode:
             description: Specify currency code
             type: string
             example: NOK
        correlationId:
             description: Specify something to correlate packages which belong to same order
             type: string
        containerId:
             description: Specify the container identification in which dangerous good is packed. This parameter can be maximum 35 character long.
             type: string
             example: 1236
        unNumber:
             description: Specify UN number of dangerous good. This parameter can be maximum 35 character long.
             type: string
             example: 1560
             required: true
        commodity:
             description: Specify name of the dangerous good. This parameter can be maximum 35 character long.
             type: string
             example: ARSENTRIKLORID
             required: true
        dangerClass:
             description: Specify the class of dangerous good. This parameter can be maximum 35 character long.
             type: string
             example: 1
             required: true
        postalCode:
             description: Specify the postal code. This parameter can be maximum 35 character long.
             type: string
             required: true
        city:
            description: Specify the city. This parameter can be maximum 35 character long.
            type : string
            required: true
        countryCode:
            description: Specify the country code. This parameter must be 2 characters long.
            type: string
            example: NO
            required: true
        reference:
            description: Specify shipper or consignee reference. This parameter can be maximum 35 character long.
            type: string
        additionalAddressInfo:
            description: Pickup instruction and delivery instruction. This parameter can be maximum 35 character long.
            type: string
        vatNumber:
            description: Specify organisation number. This parameter can be maximum 30 character long.
            type: string
        email:
            description: Specify email address. This parameter can be maximum 35 character long.
            type: string
            pattern: ^((\w*_)?(p|m|)\d*(\.\d|)|(\w*_)?(p|m)\d*(\.\d|)p)$
        phoneNumber:
            description: Specify phone number.
            type: string
        messageForRecipient:
            description: Specify message to recipient. This parameter can be maximum 35 character long.
            type: string
        quantity:
            description: The number of articles in an `ediCustomsDeclaration` line
            type: integer
            required: true
        customsArticleNumber:
            description: The customs article number in an `ediCustomsDeclaration` line
            type: string
            example: 33.05.1000
            required: false
        itemNetWeightInKg:
            description: The weight (in kg) of all the articles declared in an `ediCustomsDeclaration` line
            type: double
            required: true
        tarriffLineAmount:
            description: The value of all the articles declared in an `ediCustomsDeclaration` line
            type: double
            required: true
        currency:
            description: The currency code used in an `ediCustomsDeclaration` line. This parameter must be 3 characters long.
            type: string
            example: SEK
            required: true
        countryOfOrigin:
            description: The country code of origin of the articles in an `ediCustomsDeclaration` line. This parameter must be 2 characters long.
            type: string
            example: SE
            required: false
        natureOfTransaction:
            description: Specifies the purpose of transaction. This field is mandatory when sending customs information in the request.
            type: string
            enum: [SALE_OF_GOODS, RETURNED_GOODS, GIFT, COMMERCIAL_SAMPLE, DOCUMENTS, OTHER]
            required: true

    body:
      application/json:
        example: !include examples/basicRequestNew.json
      application/xml:
        schema: !include schemas/booking-v1.xsd
        example: !include examples/basicRequestNew.xml
    responses:
      200:
        displayName: Successful booking
        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:
            example: !include examples/successfulResponse.json
          application/xml:
            example: !include examples/successfulResponse.xml

      250:
        displayName: Recipient Notification. The old way of requesting value added services
        description: The `recipientNotification` attribute/element must be set for all services that allow electronic notification, in order for the recipient to receive electronic notification. This element must contain the recipient's mobile phone number and/or e-mail address.
        body:
          application/json:
            example: !include examples/recipientNotificationRequest.json
          application/xml:
            example: !include examples/recipientNotificationRequest.xml
      251:
        displayName: Recipient notification.
        description: The `recipientNotification` attribute/element must be set for all services that allow electronic notification, in order for the recipient to receive electronic notification. This element must the recipient's mobile phone number and/or e-mail address.
        body:
          application/json:
            example: !include examples/recipientNotificationRequestNew.json
          application/xml:
            example: !include examples/recipientNotificationRequestNew.xml

      252:
         displayName: Cash On Delivery. The old way of requesting value added services
         description: |
           The `cashOnDelivery` element/attribute can be set for services that allow cash on delivery. This element must contain the account number, the amount, the currency code and a `kid`, which is a customer identification number.

           `Amount` field only accepts numeric values without comma in it and with two decimal places.
         body:
           application/json:
             example: !include examples/cashOnDelivery.json
           application/xml:
             example: !include examples/cashOnDelivery.xml

      253:
         displayName: Cash On Delivery
         description: |
           The `cashOnDelivery` element/attribute can be set for services that allow cash on delivery. This element must contain the account number, the amount, the currency code and a `kid`, which is a customer identification number.

           `Amount` field only accepts numeric values without comma in it and with two decimal places.
         body:
           application/json:
             example: !include examples/cashOnDeliveryNew.json
           application/xml:
             example: !include examples/cashOnDeliveryNew.xml
      255:
        displayName: QuickPack Envelope
        description: |
          The `quickPackEnvelope` element/attribute is of type boolean, and can be set for services that allow quickpack envelope shipment. We recommend using the weight and measurements shown in the example, for correct mapping.
        body:
          application/json:
            example: !include examples/quickPackEnvelopeNew.json
          application/xml:
            example: !include examples/quickPackEnvelopeNew.xml
      262:
        displayName: Delivery Option
        description: |

          #### Attempted delivery

          If a sender want their package delivered to the door, and it cannot be delivered (i.e. Business closed or recipient is not present), then you can now choose what will happen with your package.

          If this option is not set, then the default behaviour is `TWO_DELIVERIES_THEN_RETURN`.

          If you want Bring to try deliver only once and/or deliver package to nearest PiB, then you must tell us by setting this option. These options cost extra money but the customer/sender will only be charged if the event happen.

          Example:

          You send a package to a business with the `deliveryOption=TWO_DELIVERIES_THEN_PIB`.

          - If Bring manage to deliver the package to the recipient on first try, then no extra charges is made.
          - If first attempt to deliver fails, then Bring will do a second attempt. The customer/sender will be charged extra.
          - If the second attempt also fails, then the package will be delivered to nearest PiB. The customer/sender will be charged extra.

          Possible options:

          - Not set = `TWO_DELIVERIES_THEN_RETURN`
          - `ONE_DELIVERY_THEN_PIB`
          - `TWO_DELIVERIES_THEN_PIB`
          - `TWO_DELIVERIES_THEN_RETURN`
        body:
          application/json:
            example: !include examples/deliveryOption.json
          application/xml:
            example: !include examples/deliveryOption.xml
      264:
        displayName: Flex Delivery
        description: |
          The `flexDelivery` element/attribute can be set for services that allow flex delivery. This element must contain an instruction message for the driver.
        body:
          application/json:
            example: !include examples/flexDelivery.json
          application/xml:
            example: !include examples/flexDelivery.xml
      266:
        displayName: Select Pickup Point in Norway
        description: |
          You can specify pickup point Id in request for `SERVICEPAKKE` and `PICKUP_PARCEL_BULK` services for delivery of parcels within Norway and to Norway from other countries. Use [Pickup Point API](/api/pickup-point/) to get list of nearest pickup points.

          The parcel will be delivered to the pickup point specified in the request with SMS/Email notification. Pickup point delivery requires that the *recipient has email and/or phone number set*, so that he can receive notification when the package arrives at the pickup point.

          Pickup point id and country code has to be specified under `pickupPoint` within `parties` as shown below.
        body:
          application/json:
            example: !include examples/selectPickupPoint_NO.json
          application/xml:
            example: !include examples/selectPickupPoint_NO.xml
      268:
        displayName: Select Pickup Point in Sweden
        description: |
          You can specify pickup point Id in request for `PICKUP_PARCEL_BULK` services for delivery of parcels within Sweden and to Sweden from other countries. Use [Pickup Point API](/api/pickup-point/) to get list of nearest pickup points.

          The parcel will be delivered to the pickup point specified in the request with SMS/Email notification. Pickup point delivery requires that the *recipient has email and/or phone number set*, so that he can receive notification when the package arrives at the pickup point.

          Pickup point id and country code has to be specified under `pickupPoint` in `parties` as shown below.
        body:
          application/json:
            example: !include examples/selectPickupPoint_SE.json
          application/xml:
            example: !include examples/selectPickupPoint_SE.xml
      270:
        displayName: Select Pickup Point in Denmark
        description: |
          The services `PICKUP_PARCEL` and `PICKUP_PARCEL_BULK` support the `deliveryOption=PICKUP_POINT` for shipments within Denmark and to Denmark, respectively. The parcel will be delivered to the pickup point closest to the recipient address and the recipient will receive a notification when the parcel arrives. If you do not specify a delivery option for these services in Denmark, the package will be delivered to the door.

          You can also specify a pickup point id to get the package delivered at a specific pickup point. Use [Pickup Point API](/api/pickup-point/) to get list of nearest pickup points. Pickup point id and country code has to be specified under `pickupPoint` within `parties` as shown below.

          `pickupPoint` is optional but both `id` and `countryCode` inside it are mandatory. This element has precedence over `deliveryOption=PICKUP_POINT` i.e. if this element is present then pickup point specified in it will be selected irrespective of value set in `deliveryOption`.

          Pickup point delivery requires that the *recipient has email and/or phone number set*, so that he can receive notification when the package arrives at the pickup point.
        body:
          application/json:
            example: !include examples/selectPickupPoint_DK.json
          application/xml:
            example: !include examples/selectPickupPoint_DK.xml
      272:
        displayName: Select Pickup Point in Finland
        description: |
          You can specify pickup point Id in request for `PICKUP_PARCEL_BULK` services for delivery of parcels to Finland from other countries. Use [Pickup Point API](/api/pickup-point/) to get list of nearest pickup points.

          The parcel will be delivered to the pickup point specified in the request with SMS/Email notification. Pickup point delivery requires that the *recipient has email and/or phone number set*, so that he can receive notification when the package arrives at the pickup point.

          Pickup point id and country code has to be specified under `pickupPoint` within `parties` as shown below.
        body:
          application/json:
            example: !include examples/selectPickupPoint_FI.json
          application/xml:
            example: !include examples/selectPickupPoint_FI.xml
      274:
        displayName: Express
        description: |
          ### Express service for Oil Express

          You can use Express service if you want to send your goods urgently (this service is *applicable only for Oil Express* service). In case of express delivery, goods are picked up as soon as possible and delivered to its destination.

          For using Express service send `true` value in `express` as shown in below example.
        body:
          application/json:
            example: !include examples/express.json
          application/xml:
            example: !include examples/express.xml
      276:
        displayName: Delivery Indoors
        description: The `deliveryIndoors` element/attribute can be set for services that allow delivery indoors. This element must contain an instruction message for the driver.
        body:
          application/json:
            example: !include examples/deliveryIndoors.json
          application/xml:
            example: !include examples/deliveryIndoors.xml
      278:
        displayName: Temperature Zone
        description: The `temperatureZone` element/attribute can be set for Frigo service for the goods which requires temperature controlled environment. This element allows either of 4 values `FROZEN`, `COOL`, `DRY` and `FISH`.
        body:
          application/json:
            example: !include examples/temperatureZone.json
          application/xml:
            example: !include examples/temperatureZone.xml
      280:
              displayName: Cargo International - Incoterms
              description: The `incotermRule` element/attribute can be set for Cargo International service. This is a mandatory element while creating an order for Cargo International. API request will return error code i.e., `BOOK-INPUT-065` in case of no IncotermRule is provided in request. This element allows either of 13 values `DDP`, `DAP`, `FCA`, `FAS`, `FOB`, `CFR`, `CIF`, `CPT`, `CIP`, `DAT`, `DAF`, `DES` and `EXW`.
              body:
                application/json:
                  example: !include examples/incotermRule.json
                application/xml:
                  example: !include examples/incotermRule.xml
      282:
              displayName: Cargo International - Dangerous Goods
              description: The `dangerousGoods` attribute/element block should be there in request for Cargo International to create an order with dangerous goods.
              body:
                application/json:
                  example: !include examples/bciDangerousGoods.json
                application/xml:
                  example: !include examples/bciDangerousGoods.xml
      284:
                    displayName: Cargo Norway - Dangerous Goods
                    description: The `dangerousGoods` attribute/element block should be there in request for Cargo Norway to create an order with dangerous goods.
                    body:
                      application/json:
                        example: !include examples/cargoDangerousGoods.json
                      application/xml:
                        example: !include examples/cargoDangerousGoods.xml
      286:
              displayName: Simple Delivery
              description: |
                The `simpleDelivery` element/attribute can be set for services that allow simple delivery.
              body:
                application/json:
                  example: !include examples/simpleDelivery.json
                application/xml:
                  example: !include examples/simpleDelivery.xml
      288:
              displayName: Cargo Norway - Number of Pallets & Load Meters
              description: The `numberOfPallets` element can be set for Number of pallets & `loadMeters` can be set for Load Metres
              body:
                application/json:
                  example: !include examples/cargowithPallets.json
                application/xml:
                  example: !include examples/cargoWithPallets.xml

      290:
              displayName: Customs declaration - with recipient as the importing party
              description: The `ediCustomsDeclarations` element needs one `ediCustomsDeclaration` line per declared item. No importer party in the request.
              body:
                application/json:
                  example: !include examples/customsDeclaration.json
                application/xml:
                  example: !include examples/customsDeclaration.xml

      292:
              displayName: Customs declaration - with importer
              description: The `ediCustomsDeclarations` element needs one `ediCustomsDeclaration` line per declared item. An importer party is also in the request.
              body:
                application/json:
                  example: !include examples/customsDeclarationWithImporter.json
                application/xml:
                  example: !include examples/customsDeclarationWithImporter.xml

      294:
              displayName: Mailbox parcel with tracking
              description: Recipient `phoneNumber` and/or recipient `email` is required
              body:
                application/json:
                  example: !include examples/mailboxParcel.json
                application/xml:
                  example: !include examples/mailboxParcel.xml

/errors{mediaTypeExtension}:
  displayName: Error codes
  description: |
    Programming is hard. Something will always go wrong. See below for the current enumeration of error codes. A value of "true" for the attribute "suffixable" means that the error code is suffixed with "-SENDER" if the error is for the sending party data and "-RECIPIENT" if the error is for the recipient party data.
  uriParameters:
    mediaTypeExtension:
      enum: [ .json, .xml ]
      description: Use .json to specify application/json or .xml to specify application/xml
  get:
    body:
      application/json:
        example: !include examples/errors.json
      application/xml:
        example: !include examples/errors.xml

/pickupOrder:
  displayName: Order pickups
  description: |
    The Pickup Order Api is for ordering a single pickup at a particular address.

    Parcels Norway, Parcels Sweden, Parcels Denmark and Cargo Customers with a Mybring user ID can use this service. Customer numbers in this API is the same as to booking API, obtained either through your Mybring profile or the customer number API.

    We have added new tags for new way of requesting pickup . Both ways are still supported, but they can not be combined.

    * All the new pickup services will be added supporting only the new way.

    * The old way will be decommissioned after some time.

    Where  before you had to send different tags under the `pickupOrderRequest` tag for ordering different types of Pickup .
    Now the new way introduced two tags  `service` and `pickupDetails` under `pickupOrderRequest` tag , one to capture type of service you wanted to book and one to capture what will be picked up.

    Example: Ordering pickup for Parcels in Norway

    The new way of requesting pickup

    ```
     <service>PARCEL</service>
     <pickupDetails>
             <numberOfPackages>1</numberOfPackages>
             <numberOfPostContainers>1</numberOfPostContainers>
             <numberOfPallets>1</numberOfPallets>
     </pickupDetails>
    ```
    The old way of requesting pickup

    ```
     <parcelsInformation>
            <numberOfPackages>1</numberOfPackages>
            <numberOfPostContainers>1</numberOfPostContainers>
            <numberOfPallets>1</numberOfPallets>
     </parcelsInformation>
    ```

    Pickup in the different countries requires different customer numbers:

    | Customer number prefix | Pickup in country | Required information element     |
    |:-----------------------|:------------------|:---------------------------------|
    | PARCELS_NORWAY         | Norway (parcels)  |  `<service>PARCEL</service>` & `<pickupDetails></pickupDetails>`  parcelsInformation |
    | CARGO                  | Norway (cargo)    | `<service>CARGO</service>` & `<pickupDetails></pickupDetails>` cargoInformation |
    | PARCELS_SWEDEN, PARCELS_DENMARK | Sweden, Denmark | `<service>PARCEL</service>` & `<pickupDetails></pickupDetails>` parcelsInternationalInformation |

    #### Pickup ordered by default with service CARGO_GROUPAGE from Bring Cargo

    A pickup order is necessary to get the goods collected for transportation by Bring Cargo but you don't have to worry about it when ordering with the API .

    A pickup will be automatically ordered together with the shipment when ordering a `CARGO_GROUPAGE` shipment.

    If you order many shipments the pickups will be aggregated by Bring Cargo to one pickup by place and date.
  post:
    description: Order a pickup
    body:
      application/json:
        example: !include examples/pickuporder_NO_new_way.json
      application/xml:
        example: !include examples/pickuporder_NO_new_way.xml
    responses:
      200:
        displayName: Successful pickup order
        body:
          application/json:
            example: !include examples/pickuporder_response.json
          application/xml:
            example: !include examples/pickuporder_response.xml
      250:
        displayName: Parcels Norway request (Old Way)
        body:
          application/json:
            example: !include examples/pickuporder_NO.json
          application/xml:
            example: !include examples/pickuporder_NO.xml

      251:
        displayName: Parcels Sweden request
        body:
          application/json:
            example: !include examples/pickuporder_SE_new_way.json
          application/xml:
            example: !include examples/pickuporder_SE_new_way.xml
      252:
        displayName: Parcels Sweden request (Old Way)
        body:
          application/json:
            example: !include examples/pickuporder_SE.json
          application/xml:
            example: !include examples/pickuporder_SE.xml
      253:
        displayName: Cargo request
        body:
          application/json:
            example: !include examples/pickuporder_CARGO_new_way.json
          application/xml:
            example: !include examples/pickuporder_CARGO_new_way.xml
      254:
        displayName:  Cargo request (Old Way)
        body:
          application/json:
            example: !include examples/pickuporder_CARGO.json
          application/xml:
            example: !include examples/pickuporder_CARGO.xml

/ws:
  displayName: SOAP
  description: |
    The SOAP Body follows the same XML Schema Definition (XSD) as the XML API.

    The SOAP endpoint has the same operations as the endpoints listed above:

    - list customers
    - book shipments
    - order pikcups

    #### WSDL

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

    #### XSD

    [https://api.bring.com/booking/api/schema/booking-v1.xsd](https://api.bring.com/booking/api/schema/booking-v1.xsd)

  post:
    description: SOAP

#%RAML 0.8
---
title: Booking API
baseUri: https://api.bring.com/booking/api

documentation:
- title: Introduction
  content: |

        Important notice: Mailbox Packet API will be decomissioned on 13.01.2020

        A simplified and enhanced version of Mailbox parcel (Pakke i postkassen) will be launched on 13.01.2020. From the same date, the Mailbox Packet API will be decomissioned, and the revitalized Mailbox parcel service will be booked via Booking API like other Bring-services. If you don't already use the Booking API, we strongly recommend that you start setting up the integration now.

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

      The Bring Booking API is a logged-in service that lets Mybring users (customers of Mybring) programatically create a booking by invoking a Web Service over SOAP or by posting XML/JSON over HTTP. The API uses the same backend as [Mybring Booking](https://www.mybring.com/booking/) and the same PDF labels.

      We support two types of integration with the Booking API. XML/JSON over HTTP and SOAP (over HTTP).

      Booking uses Shipping Guide as the source for price and availability for the different services. We advise clients of the Booking API to use [Shipping Guide API](/api/shipping-guide_2/) for getting the list price and checking availability before sending a booking request. Note that invoice payment is the only available payment option for the Booking API. This means that the Mybring user ID used in the booking request must have access to the customer number specified as payer of the booking.

      This API has similarities with the Shipment API, but there are differences. Read more about the [differences between the Booking API and the Shipment API](/api/booking-shipment/).

- title: Versioning strategy
  content: |
      Each request has a `schemaVersion` element indicating which release of the schema is being used in the request and expected schema format in the response. 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 thus not crash when unknown elements are encountered. Note that this requirement excludes the (old, but still widely used) Apache Axis 1.x Web Service client framework.

- title: Encoding
  content: |
    Booking endpoints will assume all requests are UTF-8 encoded

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

- title: Authorization
  content: |
    In addition to authentication, you need to be authorized with the _booking_ right in order to perform bookings. This is done in [customer administration in Mybring](https://www.mybring.com/useradmin/external/administration):

    ![Authorized for booking](booking_authorization.png)

    To perform a booking, you must specify which customer number to use. For your convenience, there is an [API for getting the customer numbers](#list-customer-numbers) associated with your API user. The Customer Number API also links customer numbers with the services the customer number is valid for.

- title: Making labels
  content: |
    The Booking API generates and sends all necessary EDI messages to carry out the shipment. A URL to a PDF label is returned in responses. This label must be printed and be attached to the shipment. A URL that points to tracking information is also returned.

    A GET request to the label URL will result in a HTTP 302 redirect to the concrete storage facility (e.g. redirect to Amazon S3). Ensure that your client follows these redirects.

- title: Performance
  content: |
    Different service groups have different response times in booking:

    - Parcels and courier services
      - A booking will typically take < 2 seconds
    - Express UPS services and Cargo
      - A booking will typically take < 3 seconds
    - Express Nordic SameDay
      - A booking will typically take < 10 seconds (query in flight schedules). We are working on improving the response times for QuickPack SameDay, making popular city-pairs much faster.

- title: Mailbox Parcel (Pakke i Postkassen)
  content: |
    From January 13. 2020, Mailbox Parcel is booked via the Booking API.

    Until then, the service will be possible to test-book (i.e. no real booking will happen and charges will not occur) to verify the API integration. We recommend doing this, especially if this is the first time integrating with the Booking API. Please note that it is possible to book Mailbox Parcel via Mybring's web solution if, for any reason, your integration with Booking API is not in place by January 13. 2020.

    #### What is new compared with today's Mailbox Parcel service?

    - Booking Mailbox Parcel in Booking API is a single-step process with one label per booking (as today's service, multi-kolli is not supported). Each parcel will be invoiced separately. A link to the label is returned in the response.
    - No waybill is generated, as each parcel is invoiced based on the weight registered at the terminal. The minimum price of 150,- per order is removed.
    - When booking Mailbox Parcel in Booking API, the new API customer number is used. This is identical to your company's main customer number (without prefix PARCELS_NORWAY and without padded zeros if any).
    - When booking Mailbox Parcel in Booking API, the service is defined by setting 3584 or 3570 in the product id.

    To book, order one of the two product ids:

    ### 3584 (tracking with RFID)
    Mailbox Parcel 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

    ### 3570 (no tracking)
    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.

    ### Additional Service : Bag on door (Pose på døren)
    A delivery alternative for Mailbox Parcels that cannot be delivered to the mailbox.

    Mailbox Parcel (Pakke i postkassen) is a parcel that will be delivered in the recipient’s mailbox. If the parcel for various reasons does not fit in the mailbox, the sender may, against a surcharge of NOK 15 per shipment, choose to leave the parcel on the door handle (in a special bag) to avoid it being sent to the pickup point (surcharge of NOK 23 per shipment). This delivery option will have to be confirmed by the receiver upon booking in the sender's webshop. When the parcel is delivered as a bag on the door, the bar code is scanned and the recipient will receive an SMS/email. Note that if the parcel is delivered in the mailbox the additional fee will not occur.

    #### Terms of delivery

    The sender must clearly inform the recipient about the criteria of Bag on door when displaying this service in the check out (e.g. via Shipping Guide API):

    - The distance from the mailbox to the recipient's door must not exceed 250 m
    - House no. must be clearly marked
    - The door must be clearly marked with the recipient's name
    - Posten must have access to the recipient's door, even when the main entrance is locked, for instance when recipient live in an apartment.

    Knowing these critera, the recipient must actively accept Bag on door as a delivery option.

    In cases where the criterias are not met, i.e. bad weather (risk of damage) or where for security reason the risk is considered too high to use Bag on door, the parcel will still be delivered to the recipient's pickup point for delivery.

    ### Example request
    There is an example request for 3584 in "More examples" section below. Booking 3570 is just a matter of changing the service code from 3584 to 3570.

- title: Customs information
  content: |
    It is now possible to pass customs information when booking the following services from Norway -> abroad:

    - Business Parcel
    - PickUp Parcel

    When included during booking, the customs information will be sent electronically from Bring to the destination country. As of now, sending customs information is optional.

    Please note that customs information will be mandatory to be included for the mentioned bookings from 3rd of June 2019.

    If sending customs information, the following elements are to be used:

    - quantity (required)
    - goodsDescription (required)
    - customsArticleNumber (optional)
    - itemNetWeightInKg (required)
    - tarriffLineAmount (required)
    - currency (required)
    - countryOfOrigin (optional)
    - natureOfTransaction (required)

    Please refer to the _Request params_ section below for more details about the elements. Customs tariff codes (tolltariffnummer) can be found [here](http://tolltariffen.toll.no/).

    #### Example

    In this example, you are sending a parcel/shipment with 2 shampoos, 5 cotton t-shirts and 1 wool jacket. The number of pieces is 8 (2 shampoos + 5 cotton
    t-shirts + 1 wool jacket), and the number of articles is 3 (shampoo, cotton t-shirt, wool jacket). The whole shipment is referred to as an item.

    | Quantity | Description of contents | Customs tariff code | Total content net weight (kg) | Total content value | Currency | Country of origin |
    |:--------:|:-----------------------:|:-------------------:|:----------------------------:|:-------------------:|:--------:|:-----------------:|
    | `2` | `shampoo` | `33.05.1000` | `3.0` | `200` | `NOK` | `CH`|
    | `5` | `cotton t-shirts` | `61.09.1000` | `2.5` | `1000`| `NOK`| `PL` |
    | `1` | `wool jacket` | `61.04.3100` | `2.0` | `750` | `NOK`| `DE` |

    Nature of Transaction: Gift or Sale of Goods or Returned Goods or Commercial Sample or Documents or Other

    Sending `Importer` party in the request is not mandatory. But if there is no importer sent then system will consider recipient as importer.

    Another additional field captured for customs is `vatNumber` for the parties. This is an optional field. If you are setting importer party then you can add `vatNumber` in it,
    else you can set `vatNumber` in the existing recipient party.

    There are two examples in the _More Examples_ section below that show requests containing customs information.
    * In one of these examples, importer not sent in request, hence the recipient is the importing party with (optional) `vatNumber`.
    * In the other example, there is importer party set in the request with the (optional) `vatNumber`.

/customers{mediaTypeExtension}:
  displayName: List customer numbers
  description: |
      The customer numbers are prefixed with the specialist, followed by the number. For Courier and Bring Express-services, we use a UUID to identify users.

      The customer API will return for each specialist a list with the services that you can order through the booking API.

      You can also get the API customer numbers from [this page in Mybring](https://www.mybring.com/useradmin/account/settings#customerApiKeyContainer).

      | Specialist | Example services | Example customer number |
      |:-----------|:-----------------|:------------------------|
      | Bring Parcels, Norway | `BPAKKE_DOR-DOR`, `PA_DOREN`, `EKSPRESS09`, `3584` | `PARCELS_NORWAY-10001123123` |
      | Bring Cargo, Norway | `CARGO_GROUPAGE` | `CARGO-329511` |
      | Bring Cargo, International | `CARGO_INTERNATIONAL` | `CARGO-803739` |
      | Bring Express, Norway | `COURIER_4H`, `EXPRESS_NORDIC_SAME_DAY`, `EXPRESS_INTERNATIONAL` | `EXPRESS_NORWAY-2caedf20-27da-012f-3858-58b0357c4f66` |
      | Bring Express, Sweden | `COURIER_4H`, `EXPRESS_NORDIC_SAME_DAY`, `EXPRESS_INTERNATIONAL` | `EXPRESS_SWEDEN-406077f0-27da-012f-3859-58b0357c4f66` |
      | Oil Express, Norway | `OIL_EXPRESS` | `SYSPED_NORWAY-12345` |
      | Frigo, Norway | `FRIGO` | `FRIGO-123456` |

      [Check out this page](/api/services/#booking) to see the whole list of services for each customer type.

  uriParameters:
    mediaTypeExtension:
      enum: [ .json, .xml ]
      description: Use .json to specify application/json or .xml to specify application/xml
  get:
    description: List customer numbers and services
    responses:
      200:
        displayName: List of available customers and services
        body:
          application/json:
            example: !include examples/customers.json
          application/xml:
            example: !include examples/customers.xml

/booking:
  displayName: Book shipments
  description: |
      This is the endpoint where you can book a shipment and get a printable label in return.

      #### Value added services

      The following services have available value added services:

      | Services | Value added services |
      |:--------|:--------------------|
      | SERVICEPAKKE | POSTOPPKRAV, EVARSLING |
      | BPAKKE_DOR-DOR | EVARSLING, SIMPLE_DELIVERY, deliveryOption |
      | PA_DOREN | EVARSLING, SIMPLE_DELIVERY |
      | EKSPRESS09 | EVARSLING, LORDAGSUTKJORING |
      | PICKUP_PARCEL | POSTOPPKRAV, FLEX_DELIVERY, EVARSLING, deliveryOption |
      | PICKUP_PARCEL_BULK | POSTOPPKRAV, FLEX_DELIVERY, EVARSLING, deliveryOption |
      | HOME_DELIVERY_PARCEL | POSTOPPKRAV, FLEX_DELIVERY, EVARSLING |
      | BUSINESS_PARCEL | POSTOPPKRAV, FLEX_DELIVERY, EVARSLING, PHONENOTIFICATION, DELIVERY_INDOOR |
      | BUSINESS_PARCEL_BULK | POSTOPPKRAV, FLEX_DELIVERY, EVARSLING, PHONENOTIFICATION, DELIVERY_INDOOR |
      | EXPRESS_NORDIC_0900_BULK | POSTOPPKRAV, FLEX_DELIVERY, EVARSLING, PHONENOTIFICATION, DELIVERY_INDOOR |
      | BUSINESS_PALLET | FLEX_DELIVERY, EVARSLING, PHONENOTIFICATION, DELIVERY_INDOOR |
      | BUSINESS_HALFPALLET | FLEX_DELIVERY, EVARSLING, PHONENOTIFICATION, DELIVERY_INDOOR |
      | BUSINESS_QUARTERPALLET | FLEX_DELIVERY, EVARSLING, PHONENOTIFICATION, DELIVERY_INDOOR |
      | EXPRESS_NORDIC_0900 | FLEX_DELIVERY, EVARSLING, PHONENOTIFICATION, DELIVERY_INDOOR |
      | 3570 | SIMPLE_DELIVERY |
      | 3584 | SIMPLE_DELIVERY |

      See the "More examples" section below to see examples on how to use value added services.

      We have added a new tag and by that a new way of requesting value added services. Both ways are still supported, but they can not be combined.

      * All the new value added services will be added supporting only the new way.

      * The old way will be decommissioned after some time.

      Where you before had to send each additional service as a tag under the services tag, the new way has a list of additionalService tags under the additionalServices tag, where the id element identify the additonal service to request.

       XML

      ```
       <additionalServices>
          <additionalService>
            <id>EVARSLING</id>
            <email>sender@sender.com</email>
            <mobile>12345</mobile>
          </additionalService>
          <additionalService>
            <id>DANGEROUS_GOODS</id>
            <mobile>777777</mobile>
            <unNumber>ABC</unNumber>
          </additionalService>
       </additionalServices>
      ```

       JSON

      ```
        "additionalServices": [
                  {
                    "id": "DANGEROUS_GOODS",
                    "unNumber": "ABC"
                  },
                  {
                    "id": "EVARSLING",
                    "email": "recipient@recipient.com",
                    "mobile": "97777777"
                  }
        ]
      ```

       The old way of requesting additional servies:

      ```
        <services>
           <simpleDelivery>true</simpleDelivery>
           <flexDelivery>
              <message>
                 Legg pakken i garasjen.
              </message>
           </flexDelivery>
        </services>

      ```

      #### Error handling

      If an error occurs, the following will be provided:

      - `uniqueId`: A unique log ID (UUID) that can be used as a reference for the error
      - `code`: An error code describing the error
      - `message`: Internationalized messages (with <message lang="”xx”"> elements). First version will be with lang=”en” (English) only. </message>

      See the [error codes](#error-codes) below to get an overview of error codes and what they mean.

      #### Testing

      This service will send actual production orders unless it is set to testing mode.

      To use the test mode, you need to set the `testIndicator` flag to `true` on the root node.

      Note that the examples below use `testIndicator=true`, so remove this when implementing the Booking API in your production system.

  post:
    description: Make a booking
    headers:
      Content-Type:
        description: Specify request format (application/json, application/xml)
        required: true
        enum: [ application/json, application/xml ]
      Accept:
        description: Specify response format (application/json, application/xml)
        required: false
        default: same as Content-Type
        enum: [ application/json, application/xml ]
    queryParameters:
        testIndicator:
            description:  It is true for test orders.
            type: boolean
            example: false
            required: true
        schemaVersion:
            description: Currently, it is 1
            type: integer
            example: 1
            required: true
        shippingDateTime:
            description: The date and time when an order is ready to be transported. The label generated against a booking will be valid for 52 weeks when Bring receives the request for an order.
            type: dateTime
            example: 2016-07-26T06:24:09 or 1469494449000 (for json req)
            required: true
        customerNumber:
            description: Specify API customer number. This parameter can be maximum 35 character long.
            type: string
            example: PARCELS_NORWAY-*********
            required: true
        addressLine:
            description: Specify address. This parameter can be maximum 35 character long.
            type: string
            example: Testsvingen 12
            required: true
        addressLine2:
            description: Specify address line 2. This parameter can be 35 character long.
            type: string
        purchaseOrderNumber:
            type: string
            description: Specify when there is any purchase orders associated with the booking. This parameter can be maximum 35 character long.
        weightInKg:
            description: Specify weight in kilograms
            type: double
            example: 15.2
            required: true
        goodsDescription:
            description: This can be used in three different elements; `package`(optional), `packageGroup`(optional), and `ediCustomsDeclaration`(required). It describes what is inside the package. This parameter can be maximum 35 characters long.
            type: string
        heightInCm:
            description: Specify height in cm. Dimension is optional when volumeInDm3 is specified in the request for cargo.
            type: integer
            example: 100
            required: true
        widthInCm:
            description: Specify width in cm. Dimension is optional when volumeInDm3 is specified in the request for cargo.
            type: integer
            example: 100
            required: true
        lengthInCm:
             description: Specify length in cm. Dimension is optional when volumeInDm3 is specified in the request for cargo.
             type: integer
             example: 100
             required: true
        numberOfItems:
             description: Specify number of items within a package
             type: integer
             example: 5
             required: true
        volumeInDm3:
             description: Specify volume in cubic decimeter. This is optional when dimension is specified in the request for cargo.
             type: decimal
             required: true
        numberOfPallets:
             description: Specify Number of pallets when request is for Cargo
             type: integer
             required: false
             example: 3
        loadMeters:
             description: Specify Load meters when request is for Cargo. Maximum value is 49.9
             type: double
             required: false
             example: 2.0
        whoPaysInvoice:
             description: Specify which party will pay the invoice for the booking. This parameter can be maximum 35 character long.
             type: string
             enum: [sender, recipient, thirdParty]
        accountNumber:
             description: Specify account number for cash on delivery. This parameter can be maximum 35 character long.
             type: string
             example: 12345678903
             required: true
        accountType:
             description: Specify account type. This parameter can be maximum 35 character long.
             type: string
             enum: [bankgiro,plusgiro]
        amount:
             description: Specify amount
             type: double
        currencyCode:
             description: Specify currency code
             type: string
             example: NOK
        correlationId:
             description: Specify something to correlate packages which belong to same order
             type: string
        containerId:
             description: Specify the container identification in which dangerous good is packed. This parameter can be maximum 35 character long.
             type: string
             example: 1236
        unNumber:
             description: Specify UN number of dangerous good. This parameter can be maximum 35 character long.
             type: string
             example: 1560
             required: true
        commodity:
             description: Specify name of the dangerous good. This parameter can be maximum 35 character long.
             type: string
             example: ARSENTRIKLORID
             required: true
        dangerClass:
             description: Specify the class of dangerous good. This parameter can be maximum 35 character long.
             type: string
             example: 1
             required: true
        postalCode:
             description: Specify the postal code. This parameter can be maximum 35 character long.
             type: string
             required: true
        city:
            description: Specify the city. This parameter can be maximum 35 character long.
            type : string
            required: true
        countryCode:
            description: Specify the country code. This parameter must be 2 characters long.
            type: string
            example: NO
            required: true
        reference:
            description: Specify shipper or consignee reference. This parameter can be maximum 35 character long.
            type: string
        additionalAddressInfo:
            description: Pickup instruction and delivery instruction. This parameter can be maximum 35 character long.
            type: string
        vatNumber:
            description: Specify organisation number. This parameter can be maximum 30 character long.
            type: string
        email:
            description: Specify email address. This parameter can be maximum 35 character long.
            type: string
            pattern: ^((\w*_)?(p|m|)\d*(\.\d|)|(\w*_)?(p|m)\d*(\.\d|)p)$
        phoneNumber:
            description: Specify phone number.
            type: string
        messageForRecipient:
            description: Specify message to recipient. This parameter can be maximum 35 character long.
            type: string
        quantity:
            description: The number of articles in an `ediCustomsDeclaration` line
            type: integer
            required: true
        customsArticleNumber:
            description: The customs article number in an `ediCustomsDeclaration` line
            type: string
            example: 33.05.1000
            required: false
        itemNetWeightInKg:
            description: The weight (in kg) of all the articles declared in an `ediCustomsDeclaration` line
            type: double
            required: true
        tarriffLineAmount:
            description: The value of all the articles declared in an `ediCustomsDeclaration` line
            type: double
            required: true
        currency:
            description: The currency code used in an `ediCustomsDeclaration` line. This parameter must be 3 characters long.
            type: string
            example: SEK
            required: true
        countryOfOrigin:
            description: The country code of origin of the articles in an `ediCustomsDeclaration` line. This parameter must be 2 characters long.
            type: string
            example: SE
            required: false
        natureOfTransaction:
            description: Specifies the purpose of transaction. This field is mandatory when sending customs information in the request.
            type: string
            enum: [SALE_OF_GOODS, RETURNED_GOODS, GIFT, COMMERCIAL_SAMPLE, DOCUMENTS, OTHER]
            required: true

    body:
      application/json:
        example: !include examples/basicRequestNew.json
      application/xml:
        schema: !include schemas/booking-v1.xsd
        example: !include examples/basicRequestNew.xml
    responses:
      200:
        displayName: Successful booking
        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:
            example: !include examples/successfulResponse.json
          application/xml:
            example: !include examples/successfulResponse.xml

      250:
        displayName: Recipient Notification. The old way of requesting value added services
        description: The `recipientNotification` attribute/element must be set for all services that allow electronic notification, in order for the recipient to receive electronic notification. This element must contain the recipient's mobile phone number and/or e-mail address.
        body:
          application/json:
            example: !include examples/recipientNotificationRequest.json
          application/xml:
            example: !include examples/recipientNotificationRequest.xml
      251:
        displayName: Recipient notification.
        description: The `recipientNotification` attribute/element must be set for all services that allow electronic notification, in order for the recipient to receive electronic notification. This element must the recipient's mobile phone number and/or e-mail address.
        body:
          application/json:
            example: !include examples/recipientNotificationRequestNew.json
          application/xml:
            example: !include examples/recipientNotificationRequestNew.xml

      252:
         displayName: Cash On Delivery. The old way of requesting value added services
         description: |
           The `cashOnDelivery` element/attribute can be set for services that allow cash on delivery. This element must contain the account number, the amount, the currency code and a `kid`, which is a customer identification number.

           `Amount` field only accepts numeric values without comma in it and with two decimal places.
         body:
           application/json:
             example: !include examples/cashOnDelivery.json
           application/xml:
             example: !include examples/cashOnDelivery.xml

      253:
         displayName: Cash On Delivery
         description: |
           The `cashOnDelivery` element/attribute can be set for services that allow cash on delivery. This element must contain the account number, the amount, the currency code and a `kid`, which is a customer identification number.

           `Amount` field only accepts numeric values without comma in it and with two decimal places.
         body:
           application/json:
             example: !include examples/cashOnDeliveryNew.json
           application/xml:
             example: !include examples/cashOnDeliveryNew.xml
      255:
        displayName: QuickPack Envelope
        description: |
          The `quickPackEnvelope` element/attribute is of type boolean, and can be set for services that allow quickpack envelope shipment. We recommend using the weight and measurements shown in the example, for correct mapping.
        body:
          application/json:
            example: !include examples/quickPackEnvelopeNew.json
          application/xml:
            example: !include examples/quickPackEnvelopeNew.xml
      262:
        displayName: Delivery Option
        description: |

          #### Attempted delivery

          If a sender want their package delivered to the door, and it cannot be delivered (i.e. Business closed or recipient is not present), then you can now choose what will happen with your package.

          If this option is not set, then the default behaviour is `TWO_DELIVERIES_THEN_RETURN`.

          If you want Bring to try deliver only once and/or deliver package to nearest PiB, then you must tell us by setting this option. These options cost extra money but the customer/sender will only be charged if the event happen.

          Example:

          You send a package to a business with the `deliveryOption=TWO_DELIVERIES_THEN_PIB`.

          - If Bring manage to deliver the package to the recipient on first try, then no extra charges is made.
          - If first attempt to deliver fails, then Bring will do a second attempt. The customer/sender will be charged extra.
          - If the second attempt also fails, then the package will be delivered to nearest PiB. The customer/sender will be charged extra.

          Possible options:

          - Not set = `TWO_DELIVERIES_THEN_RETURN`
          - `ONE_DELIVERY_THEN_PIB`
          - `TWO_DELIVERIES_THEN_PIB`
          - `TWO_DELIVERIES_THEN_RETURN`
        body:
          application/json:
            example: !include examples/deliveryOption.json
          application/xml:
            example: !include examples/deliveryOption.xml
      264:
        displayName: Flex Delivery
        description: |
          The `flexDelivery` element/attribute can be set for services that allow flex delivery. This element must contain an instruction message for the driver.
        body:
          application/json:
            example: !include examples/flexDelivery.json
          application/xml:
            example: !include examples/flexDelivery.xml
      266:
        displayName: Select Pickup Point in Norway
        description: |
          You can specify pickup point Id in request for `SERVICEPAKKE` and `PICKUP_PARCEL_BULK` services for delivery of parcels within Norway and to Norway from other countries. Use [Pickup Point API](/api/pickup-point/) to get list of nearest pickup points.

          The parcel will be delivered to the pickup point specified in the request with SMS/Email notification. Pickup point delivery requires that the *recipient has email and/or phone number set*, so that he can receive notification when the package arrives at the pickup point.

          Pickup point id and country code has to be specified under `pickupPoint` within `parties` as shown below.
        body:
          application/json:
            example: !include examples/selectPickupPoint_NO.json
          application/xml:
            example: !include examples/selectPickupPoint_NO.xml
      268:
        displayName: Select Pickup Point in Sweden
        description: |
          You can specify pickup point Id in request for `PICKUP_PARCEL_BULK` services for delivery of parcels within Sweden and to Sweden from other countries. Use [Pickup Point API](/api/pickup-point/) to get list of nearest pickup points.

          The parcel will be delivered to the pickup point specified in the request with SMS/Email notification. Pickup point delivery requires that the *recipient has email and/or phone number set*, so that he can receive notification when the package arrives at the pickup point.

          Pickup point id and country code has to be specified under `pickupPoint` in `parties` as shown below.
        body:
          application/json:
            example: !include examples/selectPickupPoint_SE.json
          application/xml:
            example: !include examples/selectPickupPoint_SE.xml
      270:
        displayName: Select Pickup Point in Denmark
        description: |
          The services `PICKUP_PARCEL` and `PICKUP_PARCEL_BULK` support the `deliveryOption=PICKUP_POINT` for shipments within Denmark and to Denmark, respectively. The parcel will be delivered to the pickup point closest to the recipient address and the recipient will receive a notification when the parcel arrives. If you do not specify a delivery option for these services in Denmark, the package will be delivered to the door.

          You can also specify a pickup point id to get the package delivered at a specific pickup point. Use [Pickup Point API](/api/pickup-point/) to get list of nearest pickup points. Pickup point id and country code has to be specified under `pickupPoint` within `parties` as shown below.

          `pickupPoint` is optional but both `id` and `countryCode` inside it are mandatory. This element has precedence over `deliveryOption=PICKUP_POINT` i.e. if this element is present then pickup point specified in it will be selected irrespective of value set in `deliveryOption`.

          Pickup point delivery requires that the *recipient has email and/or phone number set*, so that he can receive notification when the package arrives at the pickup point.
        body:
          application/json:
            example: !include examples/selectPickupPoint_DK.json
          application/xml:
            example: !include examples/selectPickupPoint_DK.xml
      272:
        displayName: Select Pickup Point in Finland
        description: |
          You can specify pickup point Id in request for `PICKUP_PARCEL_BULK` services for delivery of parcels to Finland from other countries. Use [Pickup Point API](/api/pickup-point/) to get list of nearest pickup points.

          The parcel will be delivered to the pickup point specified in the request with SMS/Email notification. Pickup point delivery requires that the *recipient has email and/or phone number set*, so that he can receive notification when the package arrives at the pickup point.

          Pickup point id and country code has to be specified under `pickupPoint` within `parties` as shown below.
        body:
          application/json:
            example: !include examples/selectPickupPoint_FI.json
          application/xml:
            example: !include examples/selectPickupPoint_FI.xml
      274:
        displayName: Express
        description: |
          ### Express service for Oil Express

          You can use Express service if you want to send your goods urgently (this service is *applicable only for Oil Express* service). In case of express delivery, goods are picked up as soon as possible and delivered to its destination.

          For using Express service send `true` value in `express` as shown in below example.
        body:
          application/json:
            example: !include examples/express.json
          application/xml:
            example: !include examples/express.xml
      276:
        displayName: Delivery Indoors
        description: The `deliveryIndoors` element/attribute can be set for services that allow delivery indoors. This element must contain an instruction message for the driver.
        body:
          application/json:
            example: !include examples/deliveryIndoors.json
          application/xml:
            example: !include examples/deliveryIndoors.xml
      278:
        displayName: Temperature Zone
        description: The `temperatureZone` element/attribute can be set for Frigo service for the goods which requires temperature controlled environment. This element allows either of 4 values `FROZEN`, `COOL`, `DRY` and `FISH`.
        body:
          application/json:
            example: !include examples/temperatureZone.json
          application/xml:
            example: !include examples/temperatureZone.xml
      280:
              displayName: Cargo International - Incoterms
              description: The `incotermRule` element/attribute can be set for Cargo International service. This is a mandatory element while creating an order for Cargo International. API request will return error code i.e., `BOOK-INPUT-065` in case of no IncotermRule is provided in request. This element allows either of 13 values `DDP`, `DAP`, `FCA`, `FAS`, `FOB`, `CFR`, `CIF`, `CPT`, `CIP`, `DAT`, `DAF`, `DES` and `EXW`.
              body:
                application/json:
                  example: !include examples/incotermRule.json
                application/xml:
                  example: !include examples/incotermRule.xml
      282:
              displayName: Cargo International - Dangerous Goods
              description: The `dangerousGoods` attribute/element block should be there in request for Cargo International to create an order with dangerous goods.
              body:
                application/json:
                  example: !include examples/bciDangerousGoods.json
                application/xml:
                  example: !include examples/bciDangerousGoods.xml
      284:
                    displayName: Cargo Norway - Dangerous Goods
                    description: The `dangerousGoods` attribute/element block should be there in request for Cargo Norway to create an order with dangerous goods.
                    body:
                      application/json:
                        example: !include examples/cargoDangerousGoods.json
                      application/xml:
                        example: !include examples/cargoDangerousGoods.xml
      286:
              displayName: Simple Delivery
              description: |
                The `simpleDelivery` element/attribute can be set for services that allow simple delivery.
              body:
                application/json:
                  example: !include examples/simpleDelivery.json
                application/xml:
                  example: !include examples/simpleDelivery.xml
      288:
              displayName: Cargo Norway - Number of Pallets & Load Meters
              description: The `numberOfPallets` element can be set for Number of pallets & `loadMeters` can be set for Load Metres
              body:
                application/json:
                  example: !include examples/cargowithPallets.json
                application/xml:
                  example: !include examples/cargoWithPallets.xml

      290:
              displayName: Customs declaration - with recipient as the importing party
              description: The `ediCustomsDeclarations` element needs one `ediCustomsDeclaration` line per declared item. No importer party in the request.
              body:
                application/json:
                  example: !include examples/customsDeclaration.json
                application/xml:
                  example: !include examples/customsDeclaration.xml

      292:
              displayName: Customs declaration - with importer
              description: The `ediCustomsDeclarations` element needs one `ediCustomsDeclaration` line per declared item. An importer party is also in the request.
              body:
                application/json:
                  example: !include examples/customsDeclarationWithImporter.json
                application/xml:
                  example: !include examples/customsDeclarationWithImporter.xml

      294:
              displayName: Mailbox parcel with tracking
              description: Recipient `phoneNumber` and/or recipient `email` is required
              body:
                application/json:
                  example: !include examples/mailboxParcel.json
                application/xml:
                  example: !include examples/mailboxParcel.xml

/errors{mediaTypeExtension}:
  displayName: Error codes
  description: |
    Programming is hard. Something will always go wrong. See below for the current enumeration of error codes. A value of "true" for the attribute "suffixable" means that the error code is suffixed with "-SENDER" if the error is for the sending party data and "-RECIPIENT" if the error is for the recipient party data.
  uriParameters:
    mediaTypeExtension:
      enum: [ .json, .xml ]
      description: Use .json to specify application/json or .xml to specify application/xml
  get:
    body:
      application/json:
        example: !include examples/errors.json
      application/xml:
        example: !include examples/errors.xml

/pickupOrder:
  displayName: Order pickups
  description: |
    The Pickup Order Api is for ordering a single pickup at a particular address.

    Parcels Norway, Parcels Sweden, Parcels Denmark and Cargo Customers with a Mybring user ID can use this service. Customer numbers in this API is the same as to booking API, obtained either through your Mybring profile or the customer number API.

    We have added new tags for new way of requesting pickup . Both ways are still supported, but they can not be combined.

    * All the new pickup services will be added supporting only the new way.

    * The old way will be decommissioned after some time.

    Where  before you had to send different tags under the `pickupOrderRequest` tag for ordering different types of Pickup .
    Now the new way introduced two tags  `service` and `pickupDetails` under `pickupOrderRequest` tag , one to capture type of service you wanted to book and one to capture what will be picked up.

    Example: Ordering pickup for Parcels in Norway

    The new way of requesting pickup

    ```
     <service>PARCEL</service>
     <pickupDetails>
             <numberOfPackages>1</numberOfPackages>
             <numberOfPostContainers>1</numberOfPostContainers>
             <numberOfPallets>1</numberOfPallets>
     </pickupDetails>
    ```
    The old way of requesting pickup

    ```
     <parcelsInformation>
            <numberOfPackages>1</numberOfPackages>
            <numberOfPostContainers>1</numberOfPostContainers>
            <numberOfPallets>1</numberOfPallets>
     </parcelsInformation>
    ```

    Pickup in the different countries requires different customer numbers:

    | Customer number prefix | Pickup in country | Required information element     |
    |:-----------------------|:------------------|:---------------------------------|
    | PARCELS_NORWAY         | Norway (parcels)  |  `<service>PARCEL</service>` & `<pickupDetails></pickupDetails>`  parcelsInformation |
    | CARGO                  | Norway (cargo)    | `<service>CARGO</service>` & `<pickupDetails></pickupDetails>` cargoInformation |
    | PARCELS_SWEDEN, PARCELS_DENMARK | Sweden, Denmark | `<service>PARCEL</service>` & `<pickupDetails></pickupDetails>` parcelsInternationalInformation |

    #### Pickup ordered by default with service CARGO_GROUPAGE from Bring Cargo

    A pickup order is necessary to get the goods collected for transportation by Bring Cargo but you don't have to worry about it when ordering with the API .

    A pickup will be automatically ordered together with the shipment when ordering a `CARGO_GROUPAGE` shipment.

    If you order many shipments the pickups will be aggregated by Bring Cargo to one pickup by place and date.
  post:
    description: Order a pickup
    body:
      application/json:
        example: !include examples/pickuporder_NO_new_way.json
      application/xml:
        example: !include examples/pickuporder_NO_new_way.xml
    responses:
      200:
        displayName: Successful pickup order
        body:
          application/json:
            example: !include examples/pickuporder_response.json
          application/xml:
            example: !include examples/pickuporder_response.xml
      250:
        displayName: Parcels Norway request (Old Way)
        body:
          application/json:
            example: !include examples/pickuporder_NO.json
          application/xml:
            example: !include examples/pickuporder_NO.xml

      251:
        displayName: Parcels Sweden request
        body:
          application/json:
            example: !include examples/pickuporder_SE_new_way.json
          application/xml:
            example: !include examples/pickuporder_SE_new_way.xml
      252:
        displayName: Parcels Sweden request (Old Way)
        body:
          application/json:
            example: !include examples/pickuporder_SE.json
          application/xml:
            example: !include examples/pickuporder_SE.xml
      253:
        displayName: Cargo request
        body:
          application/json:
            example: !include examples/pickuporder_CARGO_new_way.json
          application/xml:
            example: !include examples/pickuporder_CARGO_new_way.xml
      254:
        displayName:  Cargo request (Old Way)
        body:
          application/json:
            example: !include examples/pickuporder_CARGO.json
          application/xml:
            example: !include examples/pickuporder_CARGO.xml

/ws:
  displayName: SOAP
  description: |
    The SOAP Body follows the same XML Schema Definition (XSD) as the XML API.

    The SOAP endpoint has the same operations as the endpoints listed above:

    - list customers
    - book shipments
    - order pikcups

    #### WSDL

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

    #### XSD

    [https://api.bring.com/booking/api/schema/booking-v1.xsd](https://api.bring.com/booking/api/schema/booking-v1.xsd)

  post:
    description: SOAP