Allowing deleting relationships without Ids.

#%RAML 0.8
title: HATEOAS Inc. Example API
version: v1
baseUri: http://hateoas-example.skqr.net/app_dev.php/api/{version}
mediaType: application/vnd.api+json
schemas:
  - users: !include users.schema.json
resourceTypes: !include resource_types.raml
traits: !include traits.raml
/users:
  displayName: User
  get:
    description: Retrieves one or more users.
    is: [paginated]
    responses:
      200:
  post:
    description: Creates one or more users.
    responses:
      201:
  /{user-ids}:
    get:
      description: Retrieves one or more users.
      responses:
        200:
    put:
      description: Updates one or more users.
      responses:
        200:
    delete:
      description: Deletes one or more users.
    /links:
      /{relationship}:
        get:
          description: Retrieves one or more users.
          responses:
            200:
        post:
          description: Creates one or more users.
          responses:
            201:
        put:
          description: Updates one or more users.
          responses:
            204:
        delete:
          description: Deletes one or more users.
        /{relationship-ids}:
          delete:
            description: Deletes one or more users.

#%RAML 0.8
title: HATEOAS Inc. Example API
version: v1
baseUri: http://hateoas-example.skqr.net/app_dev.php/api/{version}
mediaType: application/vnd.api+json
schemas:
  - users: !include users.schema.json
resourceTypes: !include resource_types.raml
traits: !include traits.raml
/users:
  displayName: User
  get:
    description: Retrieves one or more users.
    is: [paginated]
    responses:
      200:
  post:
    description: Creates one or more users.
    responses:
      201:
  /{user-ids}:
    get:
      description: Retrieves one or more users.
      responses:
        200:
    put:
      description: Updates one or more users.
      responses:
        200:
    delete:
      description: Deletes one or more users.
    /links:
      /{relationship}:
        get:
          description: Retrieves one or more users.
          responses:
            200:
        post:
          description: Creates one or more users.
          responses:
            201:
        put:
          description: Updates one or more users.
          responses:
            204:
        /{relationship-ids}:
          delete:
            description: Deletes one or more users.


remove unprintable characters for swagger conversion (#6202)

/:
  ###
  # Get the group
  #
  get:
    description:
      Get the group with all applications and all transitive child groups.
    is: [ secured ]
    queryParameters:
      embed:
        required: false
        description:
          Embeds nested resources that match the supplied path.
          You can specify this parameter multiple times with different values.
          Unknown embed parameters are ignored.
          If you omit this parameter, it defaults to group.groups, group.apps

          - group.groups embed all child groups of each group

          - group.apps embed all apps of each group

          - group.apps.tasks embed all tasks of each application

          - group.apps.counts embed all task counts (tasksStaged, tasksRunning, tasksHealthy, tasksUnhealthy)

          - group.apps.deployments embed all deployment identifier, if the related app currently is in deployment.

          - group.apps.readiness embed all readiness check results

          - group.apps.lastTaskFailure embeds the lastTaskFailure for the application if there is one.

          - group.apps.taskStats exposes task statistics in the JSON.

        enum: [ group.groups, group.apps, group.apps.tasks, group.apps.count, group.apps.deployments, group.apps.lastTaskFailure, group.apps.failures, group.apps.taskStats ]
        example: group.apps
    responses:
      200:
        description: The group with all transitive dependencies.
        body:
          application/json:
            example: !include examples/group.json
            schema: group.GroupInfo

  ###
  # Update the group
  #
  put:
    description:
      Change parameters of a deployed application group.
      The new group parameters get applied.

      * Changes to application parameters will result in a restart of this application.

      * A new application added to the group will be started.

      * An existing application removed from the group will be stopped.

      If there are no changes to the application definition, no restart is triggered.
      During restart marathon keeps track, that the configured amount of minimal running instances are _always_ available.

      This method allows 2 special modes for the update operation>

      * Provide only the `version` field in the group definition. This will rollback the group to that given version

      * Provide only the `scaleBy` field will scale all transitive applications instance counts by the given factor.

      When one of version or scaleBy are set, nothing else than a version change or transitive instance count scaling will be applied.
      If both version and scaleBy are set, only a version rollback will be performed. The scaleBy value will not be applied.

      A deployment can run forever. This is the case, when the new application has a problem and does not become healthy.
      In this case, human interaction is needed with 2 possible choices

      * Rollback to an existing older version

      * Update with a newer version of the group which does not have the problems of the old one.

      Since the deployment of the group can take a considerable amount of time, this endpoint returns immediately with a version.
      The failure or success of the action is signalled via event. There is a group_change_success and group_change_failed with
      the given version.
    is: [ secured, deployable ]
    queryParameters:
      dryRun:
        required: false
        description:
          When this parameter is set, it will return the deployment steps Marathon would execute to deploy this group.
          No deployment will be triggered.
        type: boolean
        default: false
    body:
      application/json:
        example: !include examples/group.json
        schema: group.Group
    responses:
      200:
        description:
          A deployment is started which has a unique deployment identifier.
          The related deployment can be fetched from the /v2/deployments endpoint.
          If the deployement is gone from the list of deployments, it means that it is finished.
          As long as the deployment runs, the effect of that change operation is visible only partially.
        headers:
          Marathon-Deployment-Id:
            type: string
            example: 97c136bf-5a28-4821-9d94-480d9fbb01c8
            description:
              Resulting deployment id created by the change operation.
        body:
          application/json:
            type: deploymentResult.DeploymentResult | deploymentSteps.DeploymentSteps
            example: !include examples/deployments_result.json
      400:
        description: The group definition provided in the body is not valid.
        body:
          application/json:
            example: |
              {"message":"Invalid JSON","details":[{"path":"/id","errors":["error.expected.jsstring"]}]}
      422:
        description: The entity send can not be preocessed, since there are validation errors
        body:
          application/json:
            example: |
              {
                "message":"Object is not valid",
                "details": [
                  {
                    "path":"/apps(0)/id",
                    "errors": [
                      "identifier /app is not child of /group. Hint: use relative paths."
                    ]
                  }
                ]
              }

  ###
  # Create a new application group
  #
  post:
    description:
      Create and start a new application group.
      Application groups can contain other application groups.
    is: [ secured, deployable ]
    body:
      application/json:
        example: !include examples/group.json
        schema: group.GroupUpdate
    responses:
      400:
        description: The group definition provided in the body is not valid.
        body:
          application/json:
            example: |
              {"message":"Invalid JSON","details":[{"path":"/id","errors":["error.expected.jsstring"]}]}
      409:
        description: There is an already deployed group with this name
        body:
          application/json:
            example: |
              {"message":"Group / is already created. Use PUT to change this group."}
      422:
        description: The entity send can not be preocessed, since there are validation errors
        body:
          application/json:
            example: |
              {
                "message":"Object is not valid",
                "details": [
                  {
                    "path":"/apps(0)/id",
                    "errors": [
                      "identifier /app is not child of /group. Hint: use relative paths."
                    ]
                  }
                ]
              }

  ###
  # Delete the group
  #
  delete:
    description:
      Destroy a group. All data about that group and all associated applications will be deleted.
      The failure or success of the action is signalled via events. There is a group_change_success and group_change_failed with
      the given version.
    is: [ secured, deployable ]

  ###
  # Versions of the group
  #
  /versions:
    ###
    # List the versions of the group with specific path
    #
    get:
      description:
        List all versions the group with the specified path.
      is: [ secured ]
      responses:
        200:
          description: List all available versions of that group.
          body:
            application/json:
              example: |
                [ "2015-09-25T15:13:48.343Z", "2015-09-11T11:11:22.692Z", "2015-09-11T10:47:21.241Z" ]

/:
  ###
  # Get the group
  #
  get:
    description:
      Get the group with all applications and all transitive child groups.
    is: [ secured ]
    queryParameters:
      embed:
        required: false
        description:
          Embeds nested resources that match the supplied path.
          You can specify this parameter multiple times with different values.
          Unknown embed parameters are ignored.
          If you omit this parameter, it defaults to group.groups, group.apps

          - group.groups embed all child groups of each group

          - group.apps embed all apps of each group

          - group.apps.tasks embed all tasks of each application

          - group.apps.counts embed all task counts (tasksStaged, tasksRunning, tasksHealthy, tasksUnhealthy)

          - group.apps.deployments embed all deployment identifier, if the related app currently is in deployment.

          - group.apps.readiness embed all readiness check results

          - group.apps.lastTaskFailure embeds the lastTaskFailure for the application if there is one.

          - group.apps.taskStats exposes task statistics in the JSON.

        enum: [ group.groups, group.apps, group.apps.tasks, group.apps.count, group.apps.deployments, group.apps.lastTaskFailure, group.apps.failures, group.apps.taskStats ]
        example: group.apps
    responses:
      200:
        description: The group with all transitive dependencies.
        body:
          application/json:
            example: !include examples/group.json
            schema: group.GroupInfo

  ###
  # Update the group
  #
  put:
    description:
      Change parameters of a deployed application group.
      The new group parameters get applied.

      * Changes to application parameters will result in a restart of this application.

      * A new application added to the group will be started.

      * An existing application removed from the group will be stopped.

      If there are no changes to the application definition, no restart is triggered.
      During restart marathon keeps track, that the configured amount of minimal running instances are _always_ available.

      This method allows 2 special modes for the update operation>

      * Provide only the `version` field in the group definition. This will rollback the group to that given version

      * Provide only the `scaleBy` field will scale all transitive applications instance counts by the given factor.

      When one of version or scaleBy are set, nothing else than a version change or transitive instance count scaling will be applied.
      If both version and scaleBy are set, only a version rollback will be performed – the scaleBy value will not be applied.

      A deployment can run forever. This is the case, when the new application has a problem and does not become healthy.
      In this case, human interaction is needed with 2 possible choices

      * Rollback to an existing older version

      * Update with a newer version of the group which does not have the problems of the old one.

      Since the deployment of the group can take a considerable amount of time, this endpoint returns immediately with a version.
      The failure or success of the action is signalled via event. There is a group_change_success and group_change_failed with
      the given version.
    is: [ secured, deployable ]
    queryParameters:
      dryRun:
        required: false
        description:
          When this parameter is set, it will return the deployment steps Marathon would execute to deploy this group.
          No deployment will be triggered.
        type: boolean
        default: false
    body:
      application/json:
        example: !include examples/group.json
        schema: group.Group
    responses:
      200:
        description:
          A deployment is started which has a unique deployment identifier.
          The related deployment can be fetched from the /v2/deployments endpoint.
          If the deployement is gone from the list of deployments, it means that it is finished.
          As long as the deployment runs, the effect of that change operation is visible only partially.
        headers:
          Marathon-Deployment-Id:
            type: string
            example: 97c136bf-5a28-4821-9d94-480d9fbb01c8
            description:
              Resulting deployment id created by the change operation.
        body:
          application/json:
            type: deploymentResult.DeploymentResult | deploymentSteps.DeploymentSteps
            example: !include examples/deployments_result.json
      400:
        description: The group definition provided in the body is not valid.
        body:
          application/json:
            example: |
              {"message":"Invalid JSON","details":[{"path":"/id","errors":["error.expected.jsstring"]}]}
      422:
        description: The entity send can not be preocessed, since there are validation errors
        body:
          application/json:
            example: |
              {
                "message":"Object is not valid",
                "details": [
                  {
                    "path":"/apps(0)/id",
                    "errors": [
                      "identifier /app is not child of /group. Hint: use relative paths."
                    ]
                  }
                ]
              }

  ###
  # Create a new application group
  #
  post:
    description:
      Create and start a new application group.
      Application groups can contain other application groups.
    is: [ secured, deployable ]
    body:
      application/json:
        example: !include examples/group.json
        schema: group.GroupUpdate
    responses:
      400:
        description: The group definition provided in the body is not valid.
        body:
          application/json:
            example: |
              {"message":"Invalid JSON","details":[{"path":"/id","errors":["error.expected.jsstring"]}]}
      409:
        description: There is an already deployed group with this name
        body:
          application/json:
            example: |
              {"message":"Group / is already created. Use PUT to change this group."}
      422:
        description: The entity send can not be preocessed, since there are validation errors
        body:
          application/json:
            example: |
              {
                "message":"Object is not valid",
                "details": [
                  {
                    "path":"/apps(0)/id",
                    "errors": [
                      "identifier /app is not child of /group. Hint: use relative paths."
                    ]
                  }
                ]
              }

  ###
  # Delete the group
  #
  delete:
    description:
      Destroy a group. All data about that group and all associated applications will be deleted.
      The failure or success of the action is signalled via events. There is a group_change_success and group_change_failed with
      the given version.
    is: [ secured, deployable ]

  ###
  # Versions of the group
  #
  /versions:
    ###
    # List the versions of the group with specific path
    #
    get:
      description:
        List all versions the group with the specified path.
      is: [ secured ]
      responses:
        200:
          description: List all available versions of that group.
          body:
            application/json:
              example: |
                [ "2015-09-25T15:13:48.343Z", "2015-09-11T11:11:22.692Z", "2015-09-11T10:47:21.241Z" ]


Rename booking endpoints

Rename booking endpoints

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

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

      Bring Booking uses Bring Fraktguide as the source for price and availability for the different products. We advise clients of the Booking API to use Fraktguiden 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.

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

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

    Those headers must be set for all endpoints documented below.

- title: Authorization
  content: |
    In addition to authentication, you need to be authorized with the "booing" 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](#customers-endpoint) associated with your API user. The Customer Number API also links customer numbers with the products the customer number is valid for.

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

      The customer API will return for each specialist a list with the products 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/apicustomernumber).

      | Specialist | Example products | Example customer number |
      |:-----------|:-----------------|:------------------------|
      | Bring Parcels, Norway | `BPAKKE_DOR-DOR`, `PA_DOREN`, `EKSPRESS09` | `PARCELS_NORWAY-10001123123` |
      | Bring Cargo, Norway | `CARGO_GROUPAGE` | `CARGO_NORWAY-10001123123` |
      | Bring Express, Norway | `COURIER_4H`, `QUICKPACK_SAMEDAY`, `QUICKPACK_DAY_CERTAIN` | `EXPRESS_NORWAY-2caedf20-27da-012f-3858-58b0357c4f66` |
      | Bring Express, Sweden | `COURIER_4H`, `QUICKPACK_SAMEDAY`, `QUICKPACK_DAY_CERTAIN` | `EXPRESS_SWEDEN-406077f0-27da-012f-3859-58b0357c4f66` |
      | Oil Express, Norway | `OIL_EXPRESS` | `SYSPED_NORWAY-12345` |

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

/booking:
  displayName: Book shipments
  description: |
      Book shipments, get labels.
  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 ]
    body:
      application/json:
        example: !include examples/basicRequest.json
      application/xml:
        schema: !include schemas/booking-v1.xsd
        example: !include examples/basicRequest.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
        description: The `recipientNotification` attribute/element must be set for all products 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: Cash On Delivery
        description: |
          The `cashOnDelivery` element/attribute can be set for products 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
      252:
        displayName: QuickPack Envelope
        description: |
          The `quickPackEnvelope` element/attribute is of type boolean, and can be set for products 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/quickPackEnvelope.json
          application/xml:
            example: !include examples/quickPackEnvelope.xml
      253:
        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
      254:
        displayName: Flex Delivery
        description: |
          The `flexDelivery` element/attribute can be set for products 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
      255:
        displayName: Select Pickup Point in Norway
        description: |
          You can specify pickup point Id in request for `SERVICEPAKKE` and `CARRYON_HOMESHOPPING_BULKSPLIT` products 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
      256:
        displayName: Select Pickup Point in Sweden
        description: |
          You can specify pickup point Id in request for `CARRYON_HOMESHOPPING_BULKSPLIT` products for delivery of parcels within Sweden and to Sweden from other countries except Norway. 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
      257:
        displayName: Select Pickup Point in Denmark
        description: |
          The products `CARRYON_HOMESHOPPING` and `CARRYON_HOMESHOPPING_BULKSPLIT` 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 products 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
      258:
        displayName: Select Pickup Point in Finland
        description: |
          You can specify pickup point Id in request for `CARRYON_HOMESHOPPING_BULKSPLIT` products for delivery of parcels to Finland from other countries except Norway. 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
      259:
        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* product). 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

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

    Pickup in the different countries requires different customer numbers:

    | Customer number prefix | Pickup in country | Required information element |
    |:-----------------------|:------------------|:-----------------------------|
    | PARCELS_NORWAY         | Norway (parcels)  | `parcelsInformation`         |
    | CARGO                  | Norway (cargo)    | `cargoInformation`           |
    | PARCELS_NORWAY_INTERNATIONAL, PARCELS_SWEDEN, PARCELS_DENMARK, PARCELS_FINLAND BRING_DENMARK_AS | Sweden, Denmark | parcelsInternationalInformation |

    #### Pickup ordered by default with product 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.json
      application/xml:
        example: !include examples/pickuporder_NO.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 Sweden request
        body:
          application/json:
            example: !include examples/pickuporder_SE.json
          application/xml:
            example: !include examples/pickuporder_SE.xml
      251:
        displayName: Cargo request
        body:
          application/json:
            example: !include examples/pickuporder_CARGO.json
          application/xml:
            example: !include examples/pickuporder_CARGO.xml

/ws:
  displayName: SOAP
  description: Make a booking, get a label
  post:
    description: SOAP
    body:
      application/soap+xml:
        schema: schemas/booking-v1.xsd
        example: !include examples/soap_response_booking.xml
    responses:
      200:
        displayName: Successful booking
        body:
          application/soap+xml:
            example: !include examples/soap_response_booking.xml

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

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

      Bring Booking uses Bring Fraktguide as the source for price and availability for the different products. We advise clients of the Booking API to use Fraktguiden 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.

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

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

    Those headers must be set for all endpoints documented below.

- title: Authorization
  content: |
    In addition to authentication, you need to be authorized with the "booing" 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](#customers-endpoint) associated with your API user. The Customer Number API also links customer numbers with the products the customer number is valid for.

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

      The customer API will return for each specialist a list with the products 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/apicustomernumber).

      | Specialist | Example products | Example customer number |
      |:-----------|:-----------------|:------------------------|
      | Bring Parcels, Norway | `BPAKKE_DOR-DOR`, `PA_DOREN`, `EKSPRESS09` | `PARCELS_NORWAY-10001123123` |
      | Bring Cargo, Norway | `CARGO_GROUPAGE` | `CARGO_NORWAY-10001123123` |
      | Bring Express, Norway | `COURIER_4H`, `QUICKPACK_SAMEDAY`, `QUICKPACK_DAY_CERTAIN` | `EXPRESS_NORWAY-2caedf20-27da-012f-3858-58b0357c4f66` |
      | Bring Express, Sweden | `COURIER_4H`, `QUICKPACK_SAMEDAY`, `QUICKPACK_DAY_CERTAIN` | `EXPRESS_SWEDEN-406077f0-27da-012f-3859-58b0357c4f66` |
      | Oil Express, Norway | `OIL_EXPRESS` | `SYSPED_NORWAY-12345` |

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

/booking:
  displayName: Booking endpoint (REST)
  description: |
      Book shipments, get labels.
  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 ]
    body:
      application/json:
        example: !include examples/basicRequest.json
      application/xml:
        schema: !include schemas/booking-v1.xsd
        example: !include examples/basicRequest.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
        description: The `recipientNotification` attribute/element must be set for all products 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: Cash On Delivery
        description: |
          The `cashOnDelivery` element/attribute can be set for products 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
      252:
        displayName: QuickPack Envelope
        description: |
          The `quickPackEnvelope` element/attribute is of type boolean, and can be set for products 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/quickPackEnvelope.json
          application/xml:
            example: !include examples/quickPackEnvelope.xml
      253:
        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
      254:
        displayName: Flex Delivery
        description: |
          The `flexDelivery` element/attribute can be set for products 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
      255:
        displayName: Select Pickup Point in Norway
        description: |
          You can specify pickup point Id in request for `SERVICEPAKKE` and `CARRYON_HOMESHOPPING_BULKSPLIT` products 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
      256:
        displayName: Select Pickup Point in Sweden
        description: |
          You can specify pickup point Id in request for `CARRYON_HOMESHOPPING_BULKSPLIT` products for delivery of parcels within Sweden and to Sweden from other countries except Norway. 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
      257:
        displayName: Select Pickup Point in Denmark
        description: |
          The products `CARRYON_HOMESHOPPING` and `CARRYON_HOMESHOPPING_BULKSPLIT` 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 products 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
      258:
        displayName: Select Pickup Point in Finland
        description: |
          You can specify pickup point Id in request for `CARRYON_HOMESHOPPING_BULKSPLIT` products for delivery of parcels to Finland from other countries except Norway. 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
      259:
        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* product). 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

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

    Pickup in the different countries requires different customer numbers:

    | Customer number prefix | Pickup in country | Required information element |
    |:-----------------------|:------------------|:-----------------------------|
    | PARCELS_NORWAY         | Norway (parcels)  | `parcelsInformation`         |
    | CARGO                  | Norway (cargo)    | `cargoInformation`           |
    | PARCELS_NORWAY_INTERNATIONAL, PARCELS_SWEDEN, PARCELS_DENMARK, PARCELS_FINLAND BRING_DENMARK_AS | Sweden, Denmark | parcelsInternationalInformation |

    #### Pickup ordered by default with product 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.json
      application/xml:
        example: !include examples/pickuporder_NO.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 Sweden request
        body:
          application/json:
            example: !include examples/pickuporder_SE.json
          application/xml:
            example: !include examples/pickuporder_SE.xml
      251:
        displayName: Cargo request
        body:
          application/json:
            example: !include examples/pickuporder_CARGO.json
          application/xml:
            example: !include examples/pickuporder_CARGO.xml

/ws:
  displayName: SOAP
  description: Make a booking, get a label
  post:
    description: SOAP
    body:
      application/soap+xml:
        schema: schemas/booking-v1.xsd
        example: !include examples/soap_response_booking.xml
    responses:
      200:
        displayName: Successful booking
        body:
          application/soap+xml:
            example: !include examples/soap_response_booking.xml


Updating sporing schema definitions with all the new fields

#%RAML 1.0
---
title: Tracking API
version: v2
baseUri: https://tracking.bring.com/api
types:
  Consignment:
    type: object
    properties:
      consignmentSet:
        type: ConsignmentSet
      apiVersion:
        type: ApiVersion
  ConsignmentSet:
    type: object
    description: ?
    properties:
      consignmentId:
        type: string
      previousConsignmentId:
        type: string
        required: false
      packageSet:
        type: Package[]
      recipientAddress:
        type: Address
        required: false
      recipientHandlingAddress:
        type: Address
        required: false
      senderReference:
        type: string
      senderCustomerNumber:
        type: string
      senderCustomerMasterNumber:
        type: string
      senderName:
        type: string
      senderAddress:
        type: Address
        required: false
      senderCustomerType:
        type: string
      recipientCustomerNumber:
        type: string
      recipientCustomerMasterNumber:
        type: string
      recipientCustomerType:
        type: string
      isPickupNoticeAvailable:
        type: boolean
      consignmentActionSet:
        type: ConsignmentAction
        required: false
      senderLogo:
        type: string
        required: false
      totalListPrice:
        type: string
        required: false
      totalContractPrice:
        type: string
        required: false
      listPricePackageCount:
        type: string
        required: false
      contractPricePackageCount:
        type: string
        required: false
      currencyCode:
        type: string
        required: false
      totalWeightInKgs:
        type: number
      totalVolumeInDm3:
        type: number
  ApiVersion:
    type: object
  Package:
    type: object
    properties:
      statusDescription:
        type: string
      descriptions:
        type: string[]
        required: false
      packageNumber:
        type: string
      previousPackageNumber:
        type: string
      productName:
        type: string
      productCode:
        type: string
      productLink:
        type: string
        required: false
      brand:
        type: string
      lengthInCm:
        type: number
      widthInCm:
        type: number
      heightInCm:
        type: number
      volumeInDm3:
        type: number
      weightInKgs:
        type: number
      listPrice:
        type: string
        required: false
      contractPrice:
        type: string
        required: false
      currencyCode:
        type: string
        required: false
      pickupCode:
        type: string
        required: false
      shelfNumber:
        type: string
        required: false
      dateOfReturn:
        type: string
        required: false
      dateOfEstimatedDelivery:
        type: string
        required: false
      dateOfDelivery:
        type: string
        required: false
      senderName:
        type: string
        required: false
      senderAddress:
        type: Address
        required: false
      recipientAddress:
        type: Address
        required: false
      recipientHandlingAddress:
        type: Address
        required: false
      eventSet:
        type: Event[]
      additionalServiceSet:
        type: AdditionalService[]
        required: false
      requestPackage:
        type: requestedPackageType
        required: false
  Event:
    type: object
    properties:
      description:
        type: string
      status:
        type: string
      lmEventCode:
        type: string
        required: false
      recipientSignature:
        type: recipientSignatureType
      unitId:
        type: string
      unitInformationUrl:
        type: string
        required: false
      unitType:
        type: string
      postalCode:
        type: string
      city:
        type: string
      countryCode:
        type: string
      country:
        type: string
      dateIso:
        type: string
      displayDate:
        type: string
      displayTime:
        type: string
      consignmentEvent:
        type: boolean
      insignificant:
        type: boolean
      gpsXCoordinate:
        type: string
        required: false
      gpsYCoordinate:
        type: string
        required: false
      gpsMapUrl:
        type: string
        required: false
  Address:
    type: object
    properties:
      addressLine1:
        type: string
      addressLine2:
        type: string
      postalCode:
        type: string
      city:
        type: string
      countryCode:
        type: string
      country:
        type: string
  requestedPackageType:
      type: object
      properties:
        userEmail:
          type: string
        requestedPackageOn:
          type: string
        caseId:
          type: string
        hasBeenRequested:
          type: string
  AdditionalService:
    type: object
    properties:
      id:
        type: string
      description:
        type: string
      amount:
        type: string
      currencyCode:
        type: string
      longDescription:
        type: string
        required: false
  ConsignmentAction:
    type: object
    properties:
      actionType:
        type: string
      actionURL:
        type: string
  recipientSignatureType:
    type: object
    properties:
      name:
        type: string
      linkToImage:
        type: string
        required: false
  NamedElement:
    type: object
    properties:
      name:
        type: string
        required: false

documentation:
- title: Introduction
  content: |
      The Tracking API provides the opportunity to track shipments by reference, package or shipment number.
      It is an easy way to display details and the status of shipments.
      The information available in this API is the same that is publically available from the [Tracking web site](http://tracking.bring.com/).

- title: Formats
  content: |
    The Tracking API generates the following formats:
    - ```XML```
    - ```JSON```
    - ```JSONP```
- title: Versioning
  content: |
    Latest Tracking API version: `v2`

    We encourage you to use the latest version of our API all time.  Of course, we keep the previous version for some time so that you will get enough time to convert your application. This API supports versioning by two means.

    - **Select version by request-header**
      Use the normal URL but add the following request-header:

      | Header | Example |
      |:-------|:--------|
      | `api-version` | `2` |

      **Example request**
      ```curl -H "api-version: 2" https://tracking.bring.com/api/tracking.json?q=TESTPACKAGE-AT-PICKUPPOINT```

    - **Select version by URL**
      Use the normal URL, but add **```{v1, v2}```** to the URL. Example:

      | Application | URL example |
      |:-------|:--------|
      | Open tracking | https://tracking.bring.com/api/**v2**/tracking.json?q=TESTPACKAGE-AT-PICKUPPOINT |
      | Logged-in tracking | https://api.bring.com/tracking/api/**v2**/tracking.json?q=TESTPACKAGE-AT-PICKUPPOINT |

      You can verify that your request were used correctly by certifying that the response contains an element based on the request type:

      | URI request | Response type | Example |
      |:-------|:--------|:--------|
      | tracking.json | `application/json; charset=utf-8` | `{"apiVersion": "2"}` |
      | tracking.xml | `application/xml;charset=utf-8` | `<ApiVersion>2</ApiVersion>` |

      **Example request**
      ```curl -v https://tracking.bring.com/api/v2/tracking.json?q=TESTPACKAGE-AT-PICKUPPOINT```

- title: Authentication
  content: |
    If you have a Mybring user, you can log in to the Tracking API. Authenticated requests have the following benefits:

    - More information about parcels:
      - Prices
      - Name
      - Address
      - Signatures for proof of delivery
    - Less strict rate limits

    See the [getting started guide on authentication](/api/#authentication) if you're not sure what this means.

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

    The above headers must be present whilst using our logged-in variant of the tracking api. Also, you will have to use the endpoint:

        https://api.bring.com/tracking/api/
- title: JSON API
  content: |
      We follow the [JSON API](http://jsonapi.org/) specification with one
      exception: we allow media type to be specified as `application/json`
      instead of `application/vnd.api+json`.

/{version}/tracking{mediaTypeExtension}:
  displayName: Tracking endpoint
  description: Get information about an existing shipment based on a tracking number, shipment number or reference.
  uriParameters:
    version:
      enum: [ v1, v2 ]
      description: v1 is deprecated and will be removed soon. Use v2 when requesting the tracking API
    mediaTypeExtension:
      enum: [ .json, .xml ]
      description: Use .json to specify application/json or .xml to specify application/xml
  get:
    description: Get information about a shipment
    headers:
      X-MyBring-API-Uid:
        description: Your Mybring login ID
      X-MyBring-API-Key:
        description: Your user's API key
      X-Bring-Client-URL:
        description: A URL that sort of identifies where you're using the APIs.
    queryParameters:
      q:
        description: Reference, package number, shipment number to search for
        type: string
        required: true
        example: TESTPACKAGE-AT-PICKUPPOINT, 370000000000000001
      aktornummer:
        description: Represents a valid customer number registered with Posten
        type: string
        required: false
        example: "12345678901"
      callback:
        description: JSONP callback function name
        type: string
        required: false
    responses:
      200:
        displayName: Successful response
        description: |
          For testing you can use "TESTPACKAGE-AT-PICKUPPOINT" as the tracking number to generate test results. For real tracking this must be a valid number.

          You can find an XSD for the XML response here: [tracking-v2.xsd](https://tracking.bring.com/schema/api/tracking-v2.xsd).

          A parcel has a number of events connected to it during its travel. Here are a list of current event statuses that can be returned.

          | Event | Description |
          |:-------|:--------|
          | `ARRIVED_DELIVERY` | Arrived Delivery point - This is when a container arrives at recipients address, and can start unloading.
 |
          | `ARRIVED_COLLECTION` | Arrived for collection at pickup point |
          | `ATTEMPTED_DELIVERY` | The package has been attempted delivered at the door. Depending on the service it will be tried again or sent to closest pickup point. |
          | `CUSTOMS` | Package is in customs clearance. |
          | `COLLECTED` | The parcel has been collected at pickup address. |
          | `DELIVERED` | Package has been delivered. |
          | `DELIVERED_SENDER` | Package has been returned to the sender |
          | `DELIVERY_CANCELLED` | Home delivery has been canceled by the customer. |
          | `DELIVERY_CHANGED` | Date for Home delivery has been changed by customer. |
          | `DELIVERY_ORDERED` | Home delivery has been ordered |
          | `DEVIATION` | Deviation in production. Something wrong has happened and there is a probability for delay. |
          | `HANDED_IN` | Package has been handed in to Bring. |
          | `INTERNATIONAL` | Package has been sent from origin country or arrived at destination country.
 |
          | `IN_TRANSIT` | Package is in transit. |
          | `NOTIFICATION_SENT` | Notification for this package has been sent by sms, push and/or mail. This can be informational notifications and action notification like pickup notice. |
          | `PRE_NOTIFIED` | EDI message for the package has been received by Bring. |
          | `READY_FOR_PICKUP` | Package has arrived at pickup point. |
          | `RETURN` | The package has been returned to sender.
 |
          | `TRANSPORT_TO_RECIPIENT` | Package has been loaded for delivery to the recipient. |
          | `TERMINAL` | The package is now registered/arrived at inbound/outbound storage terminal |
          | `UNKNOWN` | Represents unknown / undefined events |

        body:
          application/json:
            type: Consignment
            examples:
              successful:
                displayName: Successful
                description: The example below shows an successful deliverance of a package at a pickup point
                value: !include examples/successful.json
              unsuccessful:
                displayName: Unsuccessful request
                description: Returned upon no search responses being returned for the request itself
                value: !include examples/unsuccessful.json
              notification_received:
                displayName: Unreceived package, with notification regarding EDI
                description: The example below is showing a package that have been EDI notified, but is not received by Bring.
                value: !include examples/notification_received.json
              waiting_at_pup:
                displayName: Waiting at Pickup Point
                description: The example below is showing a package waiting for the recipient to collect it at a pickup point
                value: !include examples/waiting_at_pup.json
              loaded_for_delivery:
                displayName: Package loaded for delivery
                description: The example below is showing a package that has been loaded on a distribution car for delivery to the reciepient.
                value: !include examples/loaded_for_delivery.json
              delivered:
                displayName: Package delivered to customer
                description: The example below is showing a package that has been delivered to the reciepient.
                value: !include examples/delivered.json
          application/xml:
            type: Consignment
            examples:
              successful:
                displayName: Successful
                description: The example below is showing a package that have been EDI notified, but is not received by Bring.
                value: !include examples/successful.xml
              unsuccessful:
                displayName: Unsuccessful request
                description: Returned upon no search responses being returned for the request itself
                value: !include examples/unsuccessful.xml
              notification_received:
                displayName: Unreceived package, with notification regarding EDI
                description: The example below is showing a package that have been EDI notified, but is not received by Bring.
                value: !include examples/notification_received.xml
              waiting_at_pup:
                displayName: Waiting at Pickup Point
                description: The example below is showing a package waiting for the recipient to collect it at a pickup point
                value: !include examples/waiting_at_pup.xml
              loaded_for_delivery:
                displayName: Package loaded for delivery
                description: The example below is showing a package that has been loaded on a distribution car for delivery to the reciepient.
                value: !include examples/loaded_for_delivery.xml
              delivered:
                displayName: Package delivered to customer
                description: The example below is showing a package that has been delivered to the reciepient.
                value: !include examples/delivered.xml

#%RAML 1.0
---
title: Tracking API
version: v2
baseUri: https://tracking.bring.com/api
types:
  Consignment:
    type: object
    properties:
      consignmentSet:
        type: ConsignmentSet
      apiVersion:
        type: ApiVersion
  ConsignmentSet:
    type: object
    description: ?
    properties:
      consignmentId:
        type: string
      previousConsignmentId:
        type: string
        required: false
      packageSet:
        type: Package[]
      recipientAddress:
        type: Address
      recipientHandlingAddress:
        type: Address
      senderReference:
        type: string
      senderCustomerNumber:
        type: string
      senderCustomerMasterNumber:
        type: string
      senderName:
        type: string
      senderAddress:
        type: Address
      senderCustomerType:
        type: string
      recipientCustomerNumber:
        type: string
      recipientCustomerMasterNumber:
        type: string
      recipientCustomerType:
        type: string
      isPickupNoticeAvailable:
        type: boolean
      consignmentActionSet:
        type: ConsignmentAction
      totalWeightInKgs:
        type: number
      totalVolumeInDm3:
        type: number
  ApiVersion:
    type: object
  ConsignmentAction:
    type: object
    properties:
      actionType:
        type: string
      actionURL:
        type: string
  Package:
    type: object
    properties:
      statusDescription:
        type: string
      descriptions:
        type: string[]
        required: false
      packageNumber:
        type: string
      previousPackageNumber:
        type: string
      productName:
        type: string
      productCode:
        type: string
      productLink:
        type: string
      brand:
        type: string
      lengthInCm:
        type: number
      widthInCm:
        type: number
      heightInCm:
        type: number
      volumeInDm3:
        type: number
      weightInKgs:
        type: number
      pickupCode:
        type: string
      dateOfReturn:
        type: string
      senderName:
        type: string
      senderAddress:
        type: Address
      recipientAddress:
        type: Address
      recipientHandlingAddress:
        type: Address
      eventSet:
        type: Event[]
      additionalServiceSet:
        type: object[]
        required: false
  Event:
    type: object
    properties:
      description: string
      status:
        type: string
      recipientSignature:
        type: NamedElement
      unitId:
        type: string
      unitType:
        type: string
      postalCode:
        type: string
        required: false
      city:
        type: string
        required: false
      countryCode:
        type: string
        required: false
      country:
        type: string
        required: false
      dateIso:
        type: string
      displayDate:
        type: string
      displayTime:
        type: string
      consignmentEvent:
        type: boolean
      insignificant:
        type: boolean
  Address:
    type: object
    properties:
      addressLine1:
        type: string
        required: false
      addressLine2:
        type: string
        required: false
      postalCode:
        type: string
        required: false
      city:
        type: string
        required: false
      countryCode:
        type: string
        required: false
      country:
        type: string
        required: false
  NamedElement:
    type: object
    properties:
      name:
        type: string
        required: false

documentation:
- title: Introduction
  content: |
      The Tracking API provides the opportunity to track shipments by reference, package or shipment number.
      It is an easy way to display details and the status of shipments.
      The information available in this API is the same that is publically available from the [Tracking web site](http://tracking.bring.com/).

- title: Formats
  content: |
    The Tracking API generates the following formats:
    - ```XML```
    - ```JSON```
    - ```JSONP```
- title: Versioning
  content: |
    Latest Tracking API version: `v2`

    We encourage you to use the latest version of our API all time.  Of course, we keep the previous version for some time so that you will get enough time to convert your application. This API supports versioning by two means.

    - **Select version by request-header**
      Use the normal URL but add the following request-header:

      | Header | Example |
      |:-------|:--------|
      | `api-version` | `2` |

      **Example request**
      ```curl -H "api-version: 2" https://tracking.bring.com/api/tracking.json?q=TESTPACKAGE-AT-PICKUPPOINT```

    - **Select version by URL**
      Use the normal URL, but add **```{v1, v2}```** to the URL. Example:

      | Application | URL example |
      |:-------|:--------|
      | Open tracking | https://tracking.bring.com/api/**v2**/tracking.json?q=TESTPACKAGE-AT-PICKUPPOINT |
      | Logged-in tracking | https://api.bring.com/tracking/api/**v2**/tracking.json?q=TESTPACKAGE-AT-PICKUPPOINT |

      You can verify that your request were used correctly by certifying that the response contains an element based on the request type:

      | URI request | Response type | Example |
      |:-------|:--------|:--------|
      | tracking.json | `application/json; charset=utf-8` | `{"apiVersion": "2"}` |
      | tracking.xml | `application/xml;charset=utf-8` | `<ApiVersion>2</ApiVersion>` |

      **Example request**
      ```curl -v https://tracking.bring.com/api/v2/tracking.json?q=TESTPACKAGE-AT-PICKUPPOINT```

- title: Authentication
  content: |
    If you have a Mybring user, you can log in to the Tracking API. Authenticated requests have the following benefits:

    - More information about parcels:
      - Prices
      - Name
      - Address
      - Signatures for proof of delivery
    - Less strict rate limits

    See the [getting started guide on authentication](/api/#authentication) if you're not sure what this means.

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

    The above headers must be present whilst using our logged-in variant of the tracking api. Also, you will have to use the endpoint:

        https://api.bring.com/tracking/api/
- title: JSON API
  content: |
      We follow the [JSON API](http://jsonapi.org/) specification with one
      exception: we allow media type to be specified as `application/json`
      instead of `application/vnd.api+json`.

/{version}/tracking{mediaTypeExtension}:
  displayName: Tracking endpoint
  description: Get information about an existing shipment based on a tracking number, shipment number or reference.
  uriParameters:
    version:
      enum: [ v1, v2 ]
      description: v1 is deprecated and will be removed soon. Use v2 when requesting the tracking API
    mediaTypeExtension:
      enum: [ .json, .xml ]
      description: Use .json to specify application/json or .xml to specify application/xml
  get:
    description: Get information about a shipment
    headers:
      X-MyBring-API-Uid:
        description: Your Mybring login ID
      X-MyBring-API-Key:
        description: Your user's API key
      X-Bring-Client-URL:
        description: A URL that sort of identifies where you're using the APIs.
    queryParameters:
      q:
        description: Reference, package number, shipment number to search for
        type: string
        required: true
        example: TESTPACKAGE-AT-PICKUPPOINT, 370000000000000001
      aktornummer:
        description: Represents a valid customer number registered with Posten
        type: string
        required: false
        example: "12345678901"
      callback:
        description: JSONP callback function name
        type: string
        required: false
    responses:
      200:
        displayName: Successful response
        description: |
          For testing you can use "TESTPACKAGE-AT-PICKUPPOINT" as the tracking number to generate test results. For real tracking this must be a valid number.

          You can find an XSD for the XML response here: [tracking-v2.xsd](https://tracking.bring.com/schema/api/tracking-v2.xsd).

          A parcel has a number of events connected to it during its travel. Here are a list of current event statuses that can be returned.

          | Event | Description |
          |:-------|:--------|
          | `ARRIVED_DELIVERY` | Arrived Delivery point - This is when a container arrives at recipients address, and can start unloading.
 |
          | `ARRIVED_COLLECTION` | Arrived for collection at pickup point |
          | `ATTEMPTED_DELIVERY` | The package has been attempted delivered at the door. Depending on the service it will be tried again or sent to closest pickup point. |
          | `CUSTOMS` | Package is in customs clearance. |
          | `COLLECTED` | The parcel has been collected at pickup address. |
          | `DELIVERED` | Package has been delivered. |
          | `DELIVERED_SENDER` | Package has been returned to the sender |
          | `DELIVERY_CANCELLED` | Home delivery has been canceled by the customer. |
          | `DELIVERY_CHANGED` | Date for Home delivery has been changed by customer. |
          | `DELIVERY_ORDERED` | Home delivery has been ordered |
          | `DEVIATION` | Deviation in production. Something wrong has happened and there is a probability for delay. |
          | `HANDED_IN` | Package has been handed in to Bring. |
          | `INTERNATIONAL` | Package has been sent from origin country or arrived at destination country.
 |
          | `IN_TRANSIT` | Package is in transit. |
          | `NOTIFICATION_SENT` | Notification for this package has been sent by sms, push and/or mail. This can be informational notifications and action notification like pickup notice. |
          | `PRE_NOTIFIED` | EDI message for the package has been received by Bring. |
          | `READY_FOR_PICKUP` | Package has arrived at pickup point. |
          | `RETURN` | The package has been returned to sender.
 |
          | `TRANSPORT_TO_RECIPIENT` | Package has been loaded for delivery to the recipient. |
          | `TERMINAL` | The package is now registered/arrived at inbound/outbound storage terminal |
          | `UNKNOWN` | Represents unknown / undefined events |

        body:
          application/json:
            type: Consignment
            examples:
              successful:
                displayName: Successful
                description: The example below shows an successful deliverance of a package at a pickup point
                value: !include examples/successful.json
              unsuccessful:
                displayName: Unsuccessful request
                description: Returned upon no search responses being returned for the request itself
                value: !include examples/unsuccessful.json
              notification_received:
                displayName: Unreceived package, with notification regarding EDI
                description: The example below is showing a package that have been EDI notified, but is not received by Bring.
                value: !include examples/notification_received.json
              waiting_at_pup:
                displayName: Waiting at Pickup Point
                description: The example below is showing a package waiting for the recipient to collect it at a pickup point
                value: !include examples/waiting_at_pup.json
              loaded_for_delivery:
                displayName: Package loaded for delivery
                description: The example below is showing a package that has been loaded on a distribution car for delivery to the reciepient.
                value: !include examples/loaded_for_delivery.json
              delivered:
                displayName: Package delivered to customer
                description: The example below is showing a package that has been delivered to the reciepient.
                value: !include examples/delivered.json
          application/xml:
            type: Consignment
            examples:
              successful:
                displayName: Successful
                description: The example below is showing a package that have been EDI notified, but is not received by Bring.
                value: !include examples/successful.xml
              unsuccessful:
                displayName: Unsuccessful request
                description: Returned upon no search responses being returned for the request itself
                value: !include examples/unsuccessful.xml
              notification_received:
                displayName: Unreceived package, with notification regarding EDI
                description: The example below is showing a package that have been EDI notified, but is not received by Bring.
                value: !include examples/notification_received.xml
              waiting_at_pup:
                displayName: Waiting at Pickup Point
                description: The example below is showing a package waiting for the recipient to collect it at a pickup point
                value: !include examples/waiting_at_pup.xml
              loaded_for_delivery:
                displayName: Package loaded for delivery
                description: The example below is showing a package that has been loaded on a distribution car for delivery to the reciepient.
                value: !include examples/loaded_for_delivery.xml
              delivered:
                displayName: Package delivered to customer
                description: The example below is showing a package that has been delivered to the reciepient.
                value: !include examples/delivered.xml