small change in text

small change in text

#%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
      estimatedTimeSpanOfDelivery:
        type: EtaMlTimeSpan
        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
  EtaMlTimeSpan:
    type: object
    properties:
      startTime:
        type: string
        required: false
      endTime:
        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: 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 perform authenticated requests. They have the following benefits:
    - More information about parcels:
      - Price
      - Name
      - Address
      - Signatures for proof of delivery
    - Less strict rate limits

    To make authenticated Tracking API requests, you will have to use the endpoint [https://api.bring.com/tracking/api/](https://api.bring.com/tracking/api/). You also need an API key from Mybring. Steps for getting a key and description of headers can be found on the general API [Getting Started / Authentication](/api/#authentication) page.

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

- title: JSON API
  content: |
      We follow the [JSON API specification](http://jsonapi.org/) 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
      lang:
        description: Choose one of the following languages (en, no, sv, dk) to display information in respectively english, norwegian, swedish or danish
        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 cancelled 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
              badRequest:
                displayName: Bad request
                description: Returned when query requested is invalid
                value: !include examples/bad_request.json
              serviceUnavailable:
                displayName: Service unavailable
                description: Returned when there are too many requests on server
                value: !include examples/service_unavailable.json
              unspeciified:
                displayName: Technical Erroor
                description: Returned when there is some technical error
                value: !include examples/unspecified.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
              estimatedTimeOfArrival:
                displayName: Package with estimated time of arrival.
                description: The example below is showing a package with estimated arrival time window of delivery.
                value: !include examples/successfulWithEta.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
              badRequest:
                displayName: Bad request
                description: Returned when query requested is invalid
                value: !include examples/bad_request.xml
              serviceUnavailable:
                displayName: Service unavailable
                description: Returned when there are too many requests on server
                value: !include examples/service_unavailable.xml
              unspeciified:
                displayName: Technical Erroor
                description: Returned when there is some technical error
                value: !include examples/unspecified.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
              estimatedTimeOfArrival:
                displayName: Package with estimated time of arrival.
                description: The example below is showing a package with estimated arrival time window of delivery.
                value: !include examples/successfulWithEta.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
        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
      estimatedTimeSpanOfDelivery:
        type: EtaMlTimeSpan
        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
  EtaMlTimeSpan:
    type: object
    properties:
      startTime:
        type: string
        required: false
      endTime:
        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: 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 perform authenticated requests. They have the following benefits:
    - More information about parcels:
      - Price
      - Name
      - Address
      - Signatures for proof of delivery
    - Less strict rate limits

    To make authenticated Tracking API requests, you will have to use the endpoint [https://api.bring.com/tracking/api/](https://api.bring.com/tracking/api/). You also need an API key from Mybring. Steps for getting a key and description of headers can be found on the general API [Getting Started / Authentication](/api/#authentication) page.

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

- title: JSON API
  content: |
      We follow the [JSON API specification](http://jsonapi.org/) 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
      lang:
        description: Choose one of the following languages (en, no, sv, dk) to display the page information in respectively english, norwegian, swedish or danish
        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 cancelled 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
              badRequest:
                displayName: Bad request
                description: Returned when query requested is invalid
                value: !include examples/bad_request.json
              serviceUnavailable:
                displayName: Service unavailable
                description: Returned when there are too many requests on server
                value: !include examples/service_unavailable.json
              unspeciified:
                displayName: Technical Erroor
                description: Returned when there is some technical error
                value: !include examples/unspecified.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
              estimatedTimeOfArrival:
                displayName: Package with estimated time of arrival.
                description: The example below is showing a package with estimated arrival time window of delivery.
                value: !include examples/successfulWithEta.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
              badRequest:
                displayName: Bad request
                description: Returned when query requested is invalid
                value: !include examples/bad_request.xml
              serviceUnavailable:
                displayName: Service unavailable
                description: Returned when there are too many requests on server
                value: !include examples/service_unavailable.xml
              unspeciified:
                displayName: Technical Erroor
                description: Returned when there is some technical error
                value: !include examples/unspecified.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
              estimatedTimeOfArrival:
                displayName: Package with estimated time of arrival.
                description: The example below is showing a package with estimated arrival time window of delivery.
                value: !include examples/successfulWithEta.xml


Take THAT!

Take THAT!

#%RAML 1.0
---
title: Mailbox Packet API
version: v1
baseUri: https://api.bring.com/order/to-mailbox
mediaType: application/json
annotationTypes:
  hideInDocumentation: boolean
  hideRequired: boolean
types:
  Order:
    type: object
    description: An order to place in Mybring.
    properties:
      customerNumber:
        type: string
        description: API customer number for which to place the order.
      senderName:
        type: string
        description: Sender's name.
        example: Min Bedrift
      senderEmail:
        required: false
        type: string
        pattern: ".+@.+"
        description: Sender's email address. Defaults to the user's email address.
      postalCode:
        type: string
        description: Sender's postal code. Must be a valid Norwegian postal code.
      streetAddress:
        type: string
        description: Sender's street address.
      reference:
        required: true
        description: A reference for the shipment (all packages).
      packages:
        minItems: 1
        type: Package[]
        description: The packages to send in this shipment.
  Package:
    type: object
    description: A single package in a shipment.
    properties:
      priority:
        enum: [ A, B ]
        description: Delivery speed (A-post or B-post).
      rfid:
        type: boolean
        description: Whether to activate [tracking with RFID](#tracking-with-rfid) for the package.
      weight:
        maximum: 2000
        type: integer
        description: Weight in grams.
      recipientName:
        type: string
        description: Recipient name.
      postalCode:
        type: string
        description: A valid Norwegian postal code.
      streetAddress:
        type: string
        description: Recipient's street address.
      phoneNumber:
        type: string
        pattern: "\\+[0-9 ]+"
        description: Recipient's phone number, including country code.
        example: "+4700000000"
      email:
        type: string
        pattern: ".+@.+"
        description: Recipient's email address.
  SuccessfulOrder:
    (hideRequired): true
    displayName: Successful Order
    description: A successfully placed order that contains links to labels and waybill.
    properties:
      id:
        type: number
        description: The ID of the order that was placed.
      customerNumber:
        type: string
        description: The API customer number for which the order was placed.
      customerName:
        type: string
        description: The name of the customer for which the order was placed.
      customerOrganizationNumber:
        type: string
        description: The organization number of the customer for which the order was placed.
      senderName:
        type: string
        description: Sender's name.
      streetAddress:
        type: string
        description: Sender's street address.
      postalCode:
        type: string
        description: Sender's postal code.
      postalPlace:
        type: string
        description: The city/place for the postal code.
      email:
        type: string
        pattern: ".+@.+"
        description: Sender's email address for the order that was placed.
      reference:
        type: string
        description: A reference for the shipment (all packages)
      labelUri:
        type: string
        description: URL to PDF label(s) for packages ordered without tracking.
      rfidLabelUri:
        type: string
        description: URL to ZPL label(s) for packages ordered with tracking.
      waybillUri:
        type: string
        description: URL to waybill PDF that has to be printed and sent with the shipment.
      orderNumberReference:
        type: string
        description: The order number reference for the placed order. This is the number on the waybill.
      priceWithoutVat:
        type: number
        description: Price of shipment without VAT (MVA).
      priceWithVat:
        type: number
        description: Price of shipment with VAT (MVA).
      vat:
        type: number
        description: How much of the price was VAT (MVA).
      currency:
        type: string
        default: NOK
        description: The currency for the price.
      orderTime:
        type: datetime
        example: 2017-09-01T14:00:00.000Z
        description: Timestamp for when the order was placed.
      packages:
        minItems: 1
        description: Packages in this shipment.
        type: OrderedPackage[]
  OrderedPackage:
    (hideRequired): true
    displayName: Ordered Package
    description: A single package in a successfully ordered shipment.
    properties:
      priority:
        enum: [ A, B ]
        description: Delivery speed (A-post or B-post).
      rfid:
        type: boolean
        description: Whether to [tracking for the package](#tracking-with-rfid) was activated.
      recipientName:
        type: string
        description: Recipient name.
      streetAddress:
        type: string
        description: Recipient's street address.
      postalCode:
        type: string
        description: Recipient's postal code.
      postalPlace:
        type: string
        description: The city/place for the postal code.
      phoneNumber:
        type: string
        pattern: "\\+[0-9 ]+"
        description: Recipient's phone number.
      email:
        type: string
        pattern: ".+@.+"
        description: Recipient's email address.
      weight:
        maximum: 2000
        type: integer
        description: Package weight in grams.
      shipmentNumber:
        type: string
        description: The shipment number for this package. A package in a PIP shipment will have both a shipment number and a package number.
      packageNumber:
        type: string
        description: The package number for this package. This goes on the label.
      agreementNumber:
        type: boolean
        description: Whether the customer has an agreement price for this package.
  ValidatedOrder:
    (hideRequired): true
    displayName: Validated Order
    description: A valid order that can be placed.
    properties:
      customerNumber:
        type: string
        description: The API customer number for the validated order.
      customerName:
        type: string
        description: The name of the customer for the validated order.
      customerOrganizationNumber:
        type: string
        description: The organization number of the customer for the validated order.
      senderName:
        type: string
        description: The sender's name.
      streetAddress:
        type: string
        description: The sender's street address.
      postalCode:
        type: string
        description: The sender's postal code.
      postalPlace:
        type: string
        description: The city/place for the postal code.
      email:
        type: string
        description: The sender's email address.
      reference:
        type: string
        description: A reference for the shipment (all packages).
      priceWithoutVat:
        type: number
        description: Calculated price without VAT (MVA).
      priceWithVat:
        type: number
        description: Calulated price with VAT (MVA).
      vat:
        type: number
        description: Calculated VAT (MVA).
      currency:
        type: string
        description: The price's currency.
      orderTime:
        type: datetime
        description: Timestamp for when the order was validated.
      packages:
        minItems: 1
        description: Packages in this validated shipment.
        type: ValidatedPackage[]
  ValidatedPackage:
    (hideRequired): true
    displayName: Validated Package
    description: A single, valid package in a valid shipment.
    properties:
      priority:
        enum: [ A, B ]
        description: Delivery speed (A-post or B-post).
      rfid:
        type: boolean
        description: Whether to [tracking with RFID](#tracking-with-rfid) was activated for the package.
      recipientName:
        type: string
        description: Recipient's name.
      streetAddress:
        type: string
        description: Recipient's email address.
      postalCode:
        type: string
        description: Recipient's postal code.
      postalPlace:
        type: string
        description: The city/place for the postal code.
      phoneNumber:
        type: string
        description: Recipient's phone number.
      email:
        type: string
        description: Recipient's email address.
      weight:
        type: integer
        description: Package weight in grams.
      agreementNumber:
        type: boolean
        description: Whether the customer has an agreement price for this package.
  OrderRequest:
    (hideInDocumentation): true
    type: object
    properties:
      data:
        type: object
        description: JSON-API data object.
        properties:
          type:
            type: string
            enum: [ orders ]
            description: JSON-API type.
          attributes:
            type: Order
            description: Order properties.
  SuccessfulOrderResponse:
    (hideRequired): true
    (hideInDocumentation): true
    type: object
    properties:
      data:
        type: object
        description: JSON-API data object.
        properties:
          type:
            type: string
            description: JSON-API type.
          id: string
          attributes:
            type: SuccessfulOrder
            description: Order properties.
  ValidatedOrderResponse:
    (hideRequired): true
    (hideInDocumentation): true
    type: object
    properties:
      data:
        type: object
        description: JSON-API data object.
        properties:
          type:
            type: string
            pattern: "order"
            description: JSON-API type.
          attributes:
            type: ValidatedOrder
            description: Order properties.
  ErrorResponse:
    (hideRequired): true
    (hideInDocumentation): true
    type: object
    properties:
      errors:
        type: ErrorObject[]
        description: List of errors.
  ErrorObject:
    (hideRequired): true
    (hideInDocumentation): true
    type: object
    properties:
      code:
        type: string
        description: Machine-readable description of error.
      title:
        type: string
        description: Human-readable description of error.
      source:
        type: object
        properties:
          pointer:
            type: string
            description: A JSON pointer to the invalid field.

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

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

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

      #### How does tracking with RFID work?

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

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

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

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

      #### Special hardware required

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

      - Zebra R410
      - Zebra 500R

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

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

    | Header | Example | Comment |
    |:-------|:--------|:--------|
    | `X-MyBring-API-Uid` | `john.doe@example.com` | Mybring login ID |
    | `X-MyBring-API-Key` | `1234abc-abcd-1234-5678-abcd1234abcd ` | Mybring login's API key |

    Those headers must be present for authenticating requests.

- title: JSON API
  content: |
      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`.

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

      #### New endpoint coming

      Currently, we have only one endpoint for ordering shipments. This
      endpoint requires all packages in the shipment to be ordered at once. We
      are working on a new endpoint that can be used for generating labels before
      placing the order. This will allow you to stick labels on packages so they're
      ready to be sent, then later place an order to get a waybill.

      #### Error codes

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

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

  post:
    description: Order shipment
    headers:
      Content-Type:
        description: Specify request format (application/json)
        required: true
        enum: [ application/json ]
      Accept:
        description: Specify response format (application/json)
        required: true
        enum: [ application/json ]
    queryParameters:
        validate:
            description: If this is set to true, the order will only be validated, not ordered in our production systems.
            type: boolean
            required: false
    body:
      application/json:
        examples:
          with_tracking:
            displayName: With tracking
            value: !include examples/with_tracking_request.json
          without_tracking:
            displayName: Without tracking
            value: !include examples/without_tracking_request.json
        type: OrderRequest
    responses:
      200:
        description: The API returns 200 when validating the request by specifying query parameter `validate=true`.
        body:
          application/json:
            type: ValidatedOrderResponse
            examples:
              valid_order:
                displayName: Valid order
                value: !include examples/validate_order_response.json
      201:
        description: |
          On a successful order, the response gives information about the shipment.
          Most importantly it contains a links to labels and waybill that have to
          be printed and sent with the shipment:

          - `labelUri`: PDF for packages without tracking
          - `rfidLabelUri`: ZPL for packages with tracking
          - `waybillUri`: PDF for the shipment's waybill
        body:
          application/json:
            type: SuccessfulOrderResponse
            examples:
              with_tracking:
                displayName: With tracking
                value: !include examples/with_tracking_response.json
              without_tracking:
                displayName: Without tracking
                value: !include examples/without_tracking_response.json
      422:
        description: |
          When the request contained invalid data, we return a 422 with a list
          of errors for the shipment.
        body:
          application/json:
            type: ErrorResponse
            examples:
              invalid_order:
                displayName: Invalid order
                value: !include examples/422.json
      500:
        description: If we have an error in our backend, we'll return a 500 error.
        body:
          application/json:
            type: ErrorResponse
            examples:
              server_error:
                displayName: Server error
                value: !include examples/500.json

/{orderId}:
  displayName: Fetch order
  uriParameters:
    orderId:
      type: string
      description: Id from when placing an order.
  get:
    description: Fetch previously ordered shipment
    headers:
      Accept:
        description: Specify response format (application/json)
        required: true
        enum: [ application/json ]
    responses:
      200:
        description: Returns the same object that was returned when placing the order.
        body:
          application/json:
            displayName: JSON response
            description: A response in the form of application/json
            type: SuccessfulOrderResponse
            examples:
              without_tracking:
                displayName: Without tracking
                value: !include examples/without_tracking_response.json

#%RAML 1.0
---
title: Mailbox Packet API
version: v1
baseUri: https://api.bring.com/order/to-mailbox
mediaType: application/json
annotationTypes:
  hideInDocumentation: boolean
  hideRequired: boolean
types:
  Order:
    type: object
    description: An order to place in Mybring.
    properties:
      customerNumber:
        type: string
        description: API customer number for which to place the order.
      senderName:
        type: string
        description: Sender's name.
        example: Min Bedrift
      senderEmail:
        required: false
        type: string
        pattern: ".+@.+"
        description: Sender's email address. Defaults to the user's email address.
      postalCode:
        type: string
        description: Sender's postal code. Must be a valid Norwegian postal code.
      streetAddress:
        type: string
        description: Sender's street address.
      reference:
        required: true
        description: A reference for the shipment (all packages).
      packages:
        minItems: 1
        type: Package[]
        description: The packages to send in this shipment.
  Package:
    type: object
    description: A single package in a shipment.
    properties:
      priority:
        enum: [ A, B ]
        description: Delivery speed (A-post or B-post).
      rfid:
        type: boolean
        description: Whether to activate [tracking with RFID](#tracking-with-rfid) for the package.
      weight:
        maximum: 2000
        type: integer
        description: Weight in grams.
      recipientName:
        type: string
        description: Recipient name.
      postalCode:
        type: string
        description: A valid Norwegian postal code.
      streetAddress:
        type: string
        description: Recipient's street address.
      phoneNumber:
        type: string
        pattern: "\\+[0-9 ]+"
        description: Recipient's phone number, including country code.
        example: "+4700000000"
      email:
        type: string
        pattern: ".+@.+"
        description: Recipient's email address.
  SuccessfulOrder:
    (hideRequired): true
    displayName: Successful Order
    description: A successfully placed order that contains links to labels and waybill.
    properties:
      id:
        type: number
        description: The ID of the order that was placed.
      customerNumber:
        type: string
        description: The API customer number for which the order was placed.
      customerName:
        type: string
        description: The name of the customer for which the order was placed.
      customerOrganizationNumber:
        type: string
        description: The organization number of the customer for which the order was placed.
      senderName:
        type: string
        description: Sender's name.
      streetAddress:
        type: string
        description: Sender's street address.
      postalCode:
        type: string
        description: Sender's postal code.
      postalPlace:
        type: string
        description: The city/place for the postal code.
      email:
        type: string
        pattern: ".+@.+"
        description: Sender's email address that for the order that was placed.
      reference:
        type: string
        description: A reference for the shipment (all packages)
      labelUri:
        type: string
        description: URL to PDF label(s) for packages ordered without tracking.
      rfidLabelUri:
        type: string
        description: URL to ZPL label(s) for packages ordered with tracking.
      waybillUri:
        type: string
        description: URL to waybill PDF that has to be printed and sent with the shipment.
      orderNumberReference:
        type: string
        description: The order number reference for the placed order. This is the number on the waybill.
      priceWithoutVat:
        type: number
        description: Price of shipment without VAT (MVA).
      priceWithVat:
        type: number
        description: Price of shipment with VAT (MVA).
      vat:
        type: number
        description: How much of the price was VAT (MVA).
      currency:
        type: string
        default: NOK
        description: The currency for the price.
      orderTime:
        type: datetime
        example: 2017-09-01T14:00:00.000Z
        description: Timestamp for when the order was placed.
      packages:
        minItems: 1
        description: Packages in this shipment.
        type: OrderedPackage[]
  OrderedPackage:
    (hideRequired): true
    displayName: Ordered Package
    description: A single package in a successfully ordered shipment.
    properties:
      priority:
        enum: [ A, B ]
        description: Delivery speed (A-post or B-post).
      rfid:
        type: boolean
        description: Whether to [tracking for the package](#tracking-with-rfid) was activated.
      recipientName:
        type: string
        description: Recipient name.
      streetAddress:
        type: string
        description: Recipient's street address.
      postalCode:
        type: string
        description: Recipient's postal code.
      postalPlace:
        type: string
        description: The city/place for the postal code.
      phoneNumber:
        type: string
        pattern: "\\+[0-9 ]+"
        description: Recipient's phone number.
      email:
        type: string
        pattern: ".+@.+"
        description: Recipient's email address.
      weight:
        maximum: 2000
        type: integer
        description: Package weight in grams.
      shipmentNumber:
        type: string
        description: The shipment number for this package. A package in a PIP shipment will have both a shipment number and a package number.
      packageNumber:
        type: string
        description: The package number for this package. This goes on the label.
      agreementNumber:
        type: boolean
        description: Whether the customer has an agreement price for this package.
  ValidatedOrder:
    (hideRequired): true
    displayName: Validated Order
    description: A valid order that can be placed.
    properties:
      customerNumber:
        type: string
        description: The API customer number for the validated order.
      customerName:
        type: string
        description: The name of the customer for the validated order.
      customerOrganizationNumber:
        type: string
        description: The organization number of the customer for the validated order.
      senderName:
        type: string
        description: The sender's name.
      streetAddress:
        type: string
        description: The sender's street address.
      postalCode:
        type: string
        description: The sender's postal code.
      postalPlace:
        type: string
        description: The city/place for the postal code.
      email:
        type: string
        description: The sender's email address.
      reference:
        type: string
        description: A reference for the shipment (all packages).
      priceWithoutVat:
        type: number
        description: Calculated price without VAT (MVA).
      priceWithVat:
        type: number
        description: Calulated price with VAT (MVA).
      vat:
        type: number
        description: Calculated VAT (MVA).
      currency:
        type: string
        description: The price's currency.
      orderTime:
        type: datetime
        description: Timestamp for when the order was validated.
      packages:
        minItems: 1
        description: Packages in this validated shipment.
        type: ValidatedPackage[]
  ValidatedPackage:
    (hideRequired): true
    displayName: Validated Package
    description: A single, valid package in a valid shipment.
    properties:
      priority:
        enum: [ A, B ]
        description: Delivery speed (A-post or B-post).
      rfid:
        type: boolean
        description: Whether to [tracking with RFID](#tracking-with-rfid) was activated for the package.
      recipientName:
        type: string
        description: Recipient's name.
      streetAddress:
        type: string
        description: Recipient's email address.
      postalCode:
        type: string
        description: Recipient's postal code.
      postalPlace:
        type: string
        description: The city/place for the postal code.
      phoneNumber:
        type: string
        description: Recipient's phone number.
      email:
        type: string
        description: Recipient's email address.
      weight:
        type: integer
        description: Package weight in grams.
      agreementNumber:
        type: boolean
        description: Whether the customer has an agreement price for this package.
  OrderRequest:
    (hideInDocumentation): true
    type: object
    properties:
      data:
        type: object
        description: JSON-API data object.
        properties:
          type:
            type: string
            enum: [ orders ]
            description: JSON-API type.
          attributes:
            type: Order
            description: Order properties.
  SuccessfulOrderResponse:
    (hideRequired): true
    (hideInDocumentation): true
    type: object
    properties:
      data:
        type: object
        description: JSON-API data object.
        properties:
          type:
            type: string
            description: JSON-API type.
          id: string
          attributes:
            type: SuccessfulOrder
            description: Order properties.
  ValidatedOrderResponse:
    (hideRequired): true
    (hideInDocumentation): true
    type: object
    properties:
      data:
        type: object
        description: JSON-API data object.
        properties:
          type:
            type: string
            pattern: "order"
            description: JSON-API type.
          attributes:
            type: ValidatedOrder
            description: Order properties.
  ErrorResponse:
    (hideRequired): true
    (hideInDocumentation): true
    type: object
    properties:
      errors:
        type: ErrorObject[]
        description: List of errors.
  ErrorObject:
    (hideRequired): true
    (hideInDocumentation): true
    type: object
    properties:
      code:
        type: string
        description: Machine-readable description of error.
      title:
        type: string
        description: Human-readable description of error.
      source:
        type: object
        properties:
          pointer:
            type: string
            description: A JSON pointer to the invalid field.

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

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

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

      #### How does tracking with RFID work?

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

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

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

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

      #### Special hardware required

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

      - Zebra R410
      - Zebra 500R

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

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

    | Header | Example | Comment |
    |:-------|:--------|:--------|
    | `X-MyBring-API-Uid` | `john.doe@example.com` | Mybring login ID |
    | `X-MyBring-API-Key` | `1234abc-abcd-1234-5678-abcd1234abcd ` | Mybring login's API key |

    Those headers must be present for authenticating requests.

- title: JSON API
  content: |
      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`.

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

      #### New endpoint coming

      Currently, we have only one endpoint for ordering shipments. This
      endpoint requires all packages in the shipment to be ordered at once. We
      are working on a new endpoint that can be used for generating labels before
      placing the order. This will allow you to stick labels on packages so they're
      ready to be sent, then later place an order to get a waybill.

      #### Error codes

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

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

  post:
    description: Order shipment
    headers:
      Content-Type:
        description: Specify request format (application/json)
        required: true
        enum: [ application/json ]
      Accept:
        description: Specify response format (application/json)
        required: true
        enum: [ application/json ]
    queryParameters:
        validate:
            description: If this is set to true, the order will only be validated, not ordered in our production systems.
            type: boolean
            required: false
    body:
      application/json:
        examples:
          with_tracking:
            displayName: With tracking
            value: !include examples/with_tracking_request.json
          without_tracking:
            displayName: Without tracking
            value: !include examples/without_tracking_request.json
        type: OrderRequest
    responses:
      200:
        description: The API returns 200 when validating the request by specifying query parameter `validate=true`.
        body:
          application/json:
            type: ValidatedOrderResponse
            examples:
              valid_order:
                displayName: Valid order
                value: !include examples/validate_order_response.json
      201:
        description: |
          On a successful order, the response gives information about the shipment.
          Most importantly it contains a links to labels and waybill that have to
          be printed and sent with the shipment:

          - `labelUri`: PDF for packages without tracking
          - `rfidLabelUri`: ZPL for packages with tracking
          - `waybillUri`: PDF for the shipment's waybill
        body:
          application/json:
            type: SuccessfulOrderResponse
            examples:
              with_tracking:
                displayName: With tracking
                value: !include examples/with_tracking_response.json
              without_tracking:
                displayName: Without tracking
                value: !include examples/without_tracking_response.json
      422:
        description: |
          When the request contained invalid data, we return a 422 with a list
          of errors for the shipment.
        body:
          application/json:
            type: ErrorResponse
            examples:
              invalid_order:
                displayName: Invalid order
                value: !include examples/422.json
      500:
        description: If we have an error in our backend, we'll return a 500 error.
        body:
          application/json:
            type: ErrorResponse
            examples:
              server_error:
                displayName: Server error
                value: !include examples/500.json

/{orderId}:
  displayName: Fetch order
  uriParameters:
    orderId:
      type: string
      description: Id from when placing an order.
  get:
    description: Fetch previously ordered shipment
    headers:
      Accept:
        description: Specify response format (application/json)
        required: true
        enum: [ application/json ]
    responses:
      200:
        description: Returns the same object that was returned when placing the order.
        body:
          application/json:
            displayName: JSON response
            description: A response in the form of application/json
            type: SuccessfulOrderResponse
            examples:
              without_tracking:
                displayName: Without tracking
                value: !include examples/without_tracking_response.json