Wrap request/response data and document rfid

#%RAML 1.0
---
title: Order to Mailbox API
version: v1
baseUri: https://api.bring.com/order/to-mailbox
mediaType: application/json
types:
  PostalCode:
    type: string
    pattern: "[0-9][0-9][0-9][0-9]"
  EmailAddress:
    type: string
    pattern: ".+@.+"
  PhoneNumber:
    type: string
    pattern: "\\+[0-9]+"
  Order:
    type: object
    properties:
      customerNumber:
        type: string
      senderName:
        type: string
      postalCode:
        type: PostalCode
      streetAddress:
        type: string
      reference:
        required: true
      packages:
        minItems: 1
        type: Package[]
  OrderWithLabels:
    type: Order
    properties:
      id: number
      customerName: string
      email: EmailAddress
      labelUri:
        type: string
        description: URL to PDF label if ordered without tracking.
      rfidLabelUri:
        type: string
        description: URL to ZPL label if ordered with tracking.
      priceWithoutVat:
        type: number
      priceWithVat:
        type: number
      currency:
        type: string
        default: NOK
      postalPlace: string
      packages: PackageWithNumbers[]
  Package:
    type: object
    properties:
      priority:
        enum: [ A, B ]
        description: Tracking with RFID
      rfid:
        type: boolean
        description: Whether to activate [tracking for the package](#tracking-with-rfid)
      weight:
        maximum: 2000
        type: integer
      recipientName: string
      postalCode:
        type: PostalCode
      streetAddress:
        type: string
      phoneNumber:
        type: PhoneNumber
      email:
        type: EmailAddress
  PackageWithNumbers:
    type: Package
    properties:
      postalPlace: string
      shipmentNumber:
        type: string
        description: The shipment number for this package.
      packageNumber:
        type: string
        description: The package number for this package.
      agreementNumber:
        type: boolean
        description: Whether you got an agreement price for this package.
  OrderRequest:
    type: object
    properties:
      data:
        type: object
        properties:
          type:
            type: string
            pattern: "orders"
          attributes: Order
  OrderResponse:
    type: object
    properties:
      data:
        type: object
        properties:
          type:
            type: string
            pattern: "order"
          id: string
          attributes: OrderWithLabels
  ErrorResponse:
    type: object
    properties:
      errors:
        type: ErrorObject[]
        description: See the [JSON-API documentation](http://jsonapi.org/format/#error-objects).
  ErrorObject:
    type: object
    properties:
      code:
        type: string
        description: Machine-readable description of error.
      title:
        type: string
        description: Human-readable description of error.
      source:
        type: object
        properties:
          pointer:
            type: string
            description: A JSON pointer to the associated entity of

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

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

- title: Tracking with RFID
  content: |
      Delivery to Mailbox 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 ZT410
      - Zebra ZT420

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

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

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

    Those headers must be present for authenticating requests.

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

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

      #### Error codes

      We follow the [JSON API](http://jsonapi.org/format/#error-objects) specification.

      From the spec, 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
            example: true
            required: false
    body:
      application/json:
        example: !include examples/without_tracking.json
        type: OrderRequest
    responses:
      201:
        description: On a successful request, the response gives information about the booking. Most importantly it contains a link to the label for the shipment.
        body:
          application/json:
            type: OrderResponse
            example: !include examples/without_tracking_response.json
      422:
        description: Validation error
        body:
          application/json:
            type: ErrorResponse
            example: !include examples/422.json
      500:
        description: If we have an error in our backend, we'll return a 500 error.
        body:
          application/json:
            type: ErrorResponse
            example: !include examples/500.json

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

#%RAML 1.0
---
title: Order to Mailbox API
version: v1
baseUri: https://api.bring.com/order/to-mailbox
mediaType: application/json
types:
  PostalCode:
    type: string
    pattern: "[0-9][0-9][0-9][0-9]"
  EmailAddress:
    type: string
    pattern: ".+@.+"
  PhoneNumber:
    type: string
    pattern: "\\+[0-9]+"
  Order:
    type: object
    properties:
      customerNumber:
        type: string
      senderName:
        type: string
      postalCode:
        type: PostalCode
      streetAddress:
        type: string
      reference:
        required: true
      packages:
        minItems: 1
        type: Package[]
  OrderWithLabels:
    type: Order
    properties:
      id: number
      customerName: string
      email: EmailAddress
      labelUri:
        type: string
        description: URL to PDF label if ordered without tracking.
      rfidLabelUri:
        type: string
        description: URL to ZPL label if ordered with tracking.
      priceWithoutVat:
        type: number
      priceWithVat:
        type: number
      currency:
        type: string
        default: NOK
      postalPlace: string
      packages: PackageWithNumbers[]
  Package:
    type: object
    properties:
      priority:
        enum: [ A, B ]
        description: Tracking with RFID
      rfid: boolean
      weight:
        maximum: 2000
        type: integer
      recipientName: string
      postalCode:
        type: PostalCode
      streetAddress:
        type: string
      phoneNumber:
        type: PhoneNumber
      email:
        type: EmailAddress
  PackageWithNumbers:
    type: Package
    properties:
      postalPlace: string
      shipmentNumber:
        type: string
        description: The shipment number for this package.
      packageNumber:
        type: string
        description: The package number for this package.
      agreementNumber:
        type: boolean
        description: Whether you got an agreement price for this package.
  OrderRequestData:
    type: object
    properties:
      type:
        pattern: orders
        type: string
      attributes: Order
  OrderRequest:
    type: object
    properties:
      data: OrderRequestData
  OrderResponseData:
    type: object
    properties:
      type:
        type: string
        pattern: order
      id: string
      attributes: OrderWithLabels
  OrderResponse:
    type: object
    properties:
      data: OrderResponseData
  ErrorResponse:
    type: object
    properties:
      errors:
        type: ErrorObject[]
        description: See the [JSON-API documentation](http://jsonapi.org/format/#error-objects).
  ErrorObject:
    type: object
    properties:
      code:
        type: string
        description: Machine-readable description of error.
      title:
        type: string
        description: Human-readable description of error.
      source:
        type: object
        properties:
          pointer:
            type: string
            description: A JSON pointer to the associated entity of

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

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

- title: Tracking with RFID
  content: |
      Delivery to Mailbox 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 ZT410
      - Zebra ZT420

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

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

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

    Those headers must be present for authenticating requests.

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

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

      #### Error codes

      We follow the [JSON API](http://jsonapi.org/format/#error-objects) specification.

      From the spec, 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
            example: true
            required: false
    body:
      application/json:
        example: !include examples/without_tracking.json
        type: OrderRequest
    responses:
      201:
        description: On a successful request, the response gives information about the booking. Most importantly it contains a link to the label for the shipment.
        body:
          application/json:
            type: OrderResponse
            example: !include examples/without_tracking_response.json
      422:
        description: Validation error
        body:
          application/json:
            type: ErrorResponse
            example: !include examples/422.json
      500:
        description: If we have an error in our backend, we'll return a 500 error.
        body:
          application/json:
            type: ErrorResponse
            example: !include examples/500.json

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


Correct endpoint url for Tracking API

Correct endpoint url for Tracking API

#%RAML 0.8
---
title: Tracking API
baseUri: https://tracking.bring.com

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 information available from the [Tracking web site](http://tracking.bring.com/). Response is available as either XML or JSON.

      *Oh by the way*, we also have a [Java client library](https://github.com/bring/bring-api-java) for the Tracking API.

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

    - You get more information about your parcels, for example signatures for proof of develiery
    - No rate limiting

    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 present for authenticating requests.

/tracking{mediaTypeExtension}:
  displayName: Tracking endpoint
  securedBy: [mybring_headers, null]
  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-v1.xsd](/api/tracking/schemas/tracking-v1.xsd).
  uriParameters:
    mediaTypeExtension:
      enum: [ .json, .xml ]
      description: Use .json to specify application/json or .xml to specify application/xml
  get:
    description: Get information about a shipment
    queryParameters:
      q:
        description: Reference, package number, shipment number to search for
        type: string
        required: true
        example: TESTPACKAGE-AT-PICKUPPOINT
      callback:
        description: JSONP callback function name
        type: string
        required: false

    responses:
      200:
        displayName: Successful response
        body:
          application/json:
            example: !include examples/testpackage.json
          application/xml:
            example: !include examples/testpackage.xml
            schema: !include schemas/tracking-v1.xsd
      250:
        displayName: Status - notification received
        description: |
          The example below is showing a package that have been EDI notified, but is not received by Bring.
        body:
          application/json:
            example: !include examples/notification_received.json
          application/xml:
            example: !include examples/notification_received.xml
      251:
        displayName: Status - waiting at pickup point
        description: |
          The example below is showing a package waiting for the recipient to collect it at a pickup point
        body:
          application/json:
            example: !include examples/waiting_at_pup.json
          application/xml:
            example: !include examples/waiting_at_pup.xml
      252:
        displayName: Status - loaded for delivery
        description: |
          The example below is showing a package that has been loaded on a distribution car for delivery to the reciepient.
        body:
          application/json:
            example: !include examples/loaded_for_delivery.json
          application/xml:
            example: !include examples/loaded_for_delivery.xml
      253:
        displayName: Status - delivered
        description: |
          The example below is showing a package that has been delivered to the reciepient.
        body:
          application/json:
            example: !include examples/delivered.json
          application/xml:
            example: !include examples/delivered.xml

#%RAML 0.8
---
title: Tracking API
baseUri: https://tracking.bring.com

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 information available from the [Tracking web site](http://tracking.bring.com/). Response is available as either XML or JSON.

      *Oh by the way*, we also have a [Java client library](https://github.com/bring/bring-api-java) for the Tracking API.

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

    - You get more information about your parcels, for example signatures for proof of develiery
    - No rate limiting

    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 present for authenticating requests.

/sporing{mediaTypeExtension}:
  displayName: Tracking endpoint
  securedBy: [mybring_headers, null]
  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-v1.xsd](/api/tracking/schemas/tracking-v1.xsd).
  uriParameters:
    mediaTypeExtension:
      enum: [ .json, .xml ]
      description: Use .json to specify application/json or .xml to specify application/xml
  get:
    description: Get information about a shipment
    queryParameters:
      q:
        description: Reference, package number, shipment number to search for
        type: string
        required: true
        example: TESTPACKAGE-AT-PICKUPPOINT
      callback:
        description: JSONP callback function name
        type: string
        required: false

    responses:
      200:
        displayName: Successful response
        body:
          application/json:
            example: !include examples/testpackage.json
          application/xml:
            example: !include examples/testpackage.xml
            schema: !include schemas/tracking-v1.xsd
      250:
        displayName: Status - notification received
        description: |
          The example below is showing a package that have been EDI notified, but is not received by Bring.
        body:
          application/json:
            example: !include examples/notification_received.json
          application/xml:
            example: !include examples/notification_received.xml
      251:
        displayName: Status - waiting at pickup point
        description: |
          The example below is showing a package waiting for the recipient to collect it at a pickup point
        body:
          application/json:
            example: !include examples/waiting_at_pup.json
          application/xml:
            example: !include examples/waiting_at_pup.xml
      252:
        displayName: Status - loaded for delivery
        description: |
          The example below is showing a package that has been loaded on a distribution car for delivery to the reciepient.
        body:
          application/json:
            example: !include examples/loaded_for_delivery.json
          application/xml:
            example: !include examples/loaded_for_delivery.xml
      253:
        displayName: Status - delivered
        description: |
          The example below is showing a package that has been delivered to the reciepient.
        body:
          application/json:
            example: !include examples/delivered.json
          application/xml:
            example: !include examples/delivered.xml