Update OTM request with restriction of max 500 supported package numbers

#%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:
  Address:
    type: object
    description: An address
    properties:
      name:
        type: string
        required: true
        description: Name
      streetAddress:
        type: string
        required: true
        description: Senders address
      postalCode:
        type: string
        required: true
        description: Postal code. Must be a valid Norwegian postal code.
        pattern: "[0-9]{4}"
        example: "0150"
  AddressWithPostalName:
    type: object
    description: An address
    properties:
      name:
        type: string
        required: true
        description: Name
      streetAddress:
        type: string
        required: true
        description: Senders address
      postalCode:
        type: string
        required: true
        description: Senders postal code. Must be a valid Norwegian postal code.
        pattern: "[0-9]{4}"
        example: "0150"
      postalName:
        type: string
        required: true
        description: Name of the postalCode
  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
        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: false
        description: A reference for the shipment that will be shown on the invoice.
      testIndicator:
        required: false
        type: boolean
        description: Set to true when testing API implementation.
      returnAddress:
        required: false
        type: Address
        description: An optional return address. If set will override the return address in generated label.
      packages:
        minItems: 1
        maxItems: 500
        type: Package[]
        description: The packages to send in this shipment.
  Package:
    type: object
    description: A single package in a shipment.
    properties:
      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
        description: Recipient's email address.
  SuccessfulOrder:
    (hideRequired): true
    displayName: Successful Order
    description: A successfully placed order that contains links to labels and waybill.
    properties:
      testIndicator:
        type: boolean
        description: Whether the placed order had the testIndicator flag set or not.
      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
        description: Sender's email address for the order that was placed.
      reference:
        type: string
        description: A reference for the shipment that will be shown on the invoice.
      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.
      returnAddress:
        type: AddressWithPostalName
        required: false
        description: Return address for the order if one is set
      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:
      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
        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:
      testIndicator:
        type: boolean
        description: Whether the validated order had the testIndicator flag set or not.
      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 that will be shown on the invoice.
      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.
      returnAddress:
        type: AddressWithPostalName
        required: false
        description: Return address for the order if one is set
      packages:
        minItems: 1
        description: Packages in this validated shipment. The packages in the response will correspond to same order as it was in the request to make it easier for clients to do any mapping if needed.
        type: ValidatedPackage[]
  ValidatedPackage:
    (hideRequired): true
    displayName: Validated Package
    description: A single, valid package in a valid shipment.
    properties:
      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.
  PackageWithNumbers:
    displayName: Package Details
    description: Package Details with OrderID
    properties:
      rfid:
        type: boolean
        description: Whether to activate [tracking with RFID](#tracking-with-rfid) for the package.
      recipientName:
        type: string
        description: Recipient name.
      streetAddress:
        type: string
        description: Recipient's Street address.
      postalCode:
        type: string
        description: A valid Norwegian postal code.
      postalPlace:
        type: string
        description: The city/place for the postal code.
      phoneNumber:
        type: string
        pattern: "\\+[0-9 ]+"
        description: Recipient's phone number, including country code.
        example: "+4700000000"
      email:
        type: string
        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.
      priceType:
        type: string
        description: Whether the Price is Agreement or List
        enum: [ AGREEMENT_PRICE,  LIST_PRICE]
  OrderWithLabelResponse:
    (hideRequired): true
    displayName: Successful Order
    description: A successfully label generation that contains links to labels.
    properties:
      reference:
        type: string
        description: A reference for the shipment that will be shown on the invoice.
      senderName:
        type: string
        description: Sender's name.
      streetAddress:
        type: string
        description: Sender's street address.
      email:
        type: string
        description: Sender's email address for the order that was placed.
      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.
      orderTime:
        type: datetime
        example: 2017-09-01T14:00:00.000Z
        description: Timestamp for when the order was placed.
      postalCode:
        type: string
        description: Sender's postal code.
      postalPlace:
        type: string
        description: The city/place for the postal code.
      customerNumber:
        type: string
        description: The API customer number for the validated order.
      customerName:
        type: string
        description: The API customer name for which the order was placed.
      customerOrganizationNumber:
        type: string
        description: The organization number of the customer for which the order was placed.
      testIndicator:
        type: boolean
        description: Whether the placed order had the testIndicator flag set or not.
      packages:
        minItems: 1
        description: Packages Number for the shipment.
        type: PackageWithNumbers[]
  SuccessfulLabelGenerationResponse:
    (hideRequired): true
    (hideInDocumentation): true
    type: object
    properties:
      data:
        type: object
        description: JSON-API data object.
        properties:
          type:
            type: string
            enum: [ labels ]
            description: JSON-API type.
          attributes:
            type: OrderWithLabelResponse
            description: Order properties.
  LabelRequest:
    (hideInDocumentation): true
    type: object
    properties:
      data:
        type: object
        description: JSON-API data object.
        properties:
          type:
            type: string
            enum: [ labels ]
            description: JSON-API type.
          attributes:
            type: CreateOrderRequest
            description: Order properties.
  CreateOrderRequest:
    displayName: Create Order Request
    description: It creates the Request for Label Generation.
    properties:
      customerNumber:
        type: string
        description: The API customer number for the validated order.
      senderName:
        type: string
        description: The sender's name.
      senderEmail:
        required: false
        type: string
        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: Recipient's email address.
      reference:
        required: false
        description: A reference for the shipment that will be shown on the invoice.
      testIndicator:
        type: boolean
        description: Whether the validated order had the testIndicator flag set or not.
      packages:
        minItems: 1
        maxItems: 500
        type: Package[]
        description: The packages to send in this shipment. Response will have packages in same order as requested to make it easier for clients to do any mapping if needed.
  LabelOrderRequest:
      (hideInDocumentation): true
      type: object
      properties:
        data:
          type: object
          description: JSON-API data object.
          properties:
            type:
              type: string
              enum: [ label_orders ]
              description: JSON-API type.
            attributes:
              type: CreateLabelOrderRequest
              description: Create Order properties.
  CreateLabelOrderRequest:
    displayName: Create Label Order Request
    description: Create Label Order Request
    properties:
      customerNumber:
        type: string
        description: The API customer number.
      packageNumbers:
        minItems: 1
        maxItems: 500
        type: string[]
        description: List of Package Numbers.
  OrderWithIdAndEdiMessage:
    displayName: Reponse of Create Order Request
    description: Reponse of Create Order Request
    properties:
      id:
        type: number
        description: The ID of the order that was placed.
      customerNumber:
        type: string
        description: The API customer number for the validated order.
      customerName:
        type: string
        description: The API customer name 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.
      email:
        type: string
        description: Sender's email address for the order that was placed.
      postalCode:
        type: string
        description: Sender's postal code.
      reference:
        type: string
        description: A reference for the shipment that will be shown on the invoice.
      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.
      returnAddress:
        type: AddressWithPostalName
        required: false
        description: Return address for the order if one is set
      packages:
        minItems: 1
        description: Packages Number for the shipment.
        type: PackageWithNumbers[]
  SuccessfulLabelOrderResponse:
     (hideRequired): true
     (hideInDocumentation): true
     type: object
     properties:
       data:
         type: object
         description: JSON-API data object.
         properties:
           type:
             type: string
             enum: [ order ]
             description: JSON-API type.
           id:
             type: string
             description: Order Id
           attributes:
             type: OrderWithIdAndEdiMessage
             description: Label Order properties.

documentation:
- title: Introduction
  content: |
      Mailbox Packet API is an API 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 has replaced the services Minipakke and Småpakke.

      ##### There are two ways of using Mailbox Packet API

         - *Single step*: is the preferred way of usage when your work flow requires label generation, booking and waybill generation to be executed in one single step.
         - *Two steps*: is the preferred way of usage when your work flow requires flexibility, i.e. label generation to be separated from booking and waybill generation.

      ##### Single step

         - Label generation, booking and waybill generation is done in one step by requesting the rest API "[Order shipments in single step](#order-shipments-in-single-step)"

      ##### Two steps

        The process of ordering transport is split into

       - **Label generation**: first, labels are generated by requesting the rest API “[Label generation](#label-generation).” All shipments that are made through this endpoint are stored. Using this endpoint provides flexibility: Packing shipments, generating labels and sticking labels on respective shipments can be done throughout the day, without placing an order and generating a waybill.

       - **Booking and waybill generation**: second, order is placed and waybill is generated by requesting the rest API “[Waybill generation](#waybill-generation)”. The request must specify which shipments (i.e. package numbers) that are to be ordered. Note that all specified shipments in the request must already be stored, i.e. labels must already have been generated. Using this endpoint also provides flexibility: It is possible to order only a selection of the shipments stored in the database. That way, you avoid paying for shipments cancelled by end customers after the labels have been generated.
          - Shipments (i.e. package numbers) that have been stored for 120 hours without being ordered (step 2) will automatically be deleted.

- 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 shipments in single step
  description: |
      Generate labels, place order and generate waybill in one go.

      #### 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 application error | `/` |
      | 1000 | Missing field value | `/streetAddress` |
      | 2000 | Order must contain at least one package | `/packages` |
      | 2500 | Order can maximum contain 500 packages | `/packages` |
      | 2600 | Order can maximum contain 500 package numbers | `/packagesNumbers` |
      | 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` |
      | 8000 | Invalid phone number | `/pacakges/4/phoneNumber` |
      | 9000 | Invalid JSON API resource type (must be `orders`) | `/data/type` |

      #### Testing

      This service will send actual production orders unless it is set to testing mode.
      To use the test mode, you need to set the `testIndicator` flag to true in the order attributes.
      Note that the examples below use `"testIndicator":true`, so remove this when implementing the API in your production system.

  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

/labels:
  displayName: Label generation
  description: |
      This is step 1 in the two-step way of using the Mailbox Packet API. Note that this rest API is just used to generate labels. Booking and waybill generation is done separately in step 2 by requesting the rest API “[Waybill generation.](#waybill-generation)”

  post:
    description: Generate Label for packets
    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 ]
    body:
      application/json:
        examples:
          valid_request:
            displayName: Valid Request
            value: !include examples/label_generation_request.json
        type: LabelRequest
    responses:
      201:
        description: |
          On a successful label generation, the response gives information about the shipment.
          Most importantly it contains a links to labels that have to
          be printed and sent with the shipment:

          - `labelUri`: PDF for packages without tracking
          - `rfidLabelUri`: ZPL for packages with tracking

        body:
          application/json:
            type: SuccessfulLabelGenerationResponse
            examples:
              valid_response:
                displayName: Valid Response
                value: !include examples/label_generation_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_label_geneation_request:
                displayName: Invalid Label Generation Request
                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
/label/order:
  displayName: Waybill generation
  description: This is step 2 in the two-step way of using the Mailbox Packet API. Note that this rest API is just used for booking and waybill generation. Labels must already have been generated in step 1 by requesting the rest API "[Label generation](#label-generation)”.
  post:
    description: Generate Waybill for packets
    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 ]
    body:
      application/json:
        examples:
          valid_request:
            displayName: Valid Request
            value: !include examples/label_order_create_request.json
        type: LabelOrderRequest
    responses:
      201:
        description: |
          On a successful Transport Booking, the response gives information about the Waybill.
        body:
          application/json:
            type: SuccessfulLabelOrderResponse
            examples:
              valid_response:
                displayName: Valid Response
                value: !include examples/label_order_create_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_label_geneation_request:
                displayName: Invalid Label Generation Request
                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:
  Address:
    type: object
    description: An address
    properties:
      name:
        type: string
        required: true
        description: Name
      streetAddress:
        type: string
        required: true
        description: Senders address
      postalCode:
        type: string
        required: true
        description: Postal code. Must be a valid Norwegian postal code.
        pattern: "[0-9]{4}"
        example: "0150"
  AddressWithPostalName:
    type: object
    description: An address
    properties:
      name:
        type: string
        required: true
        description: Name
      streetAddress:
        type: string
        required: true
        description: Senders address
      postalCode:
        type: string
        required: true
        description: Senders postal code. Must be a valid Norwegian postal code.
        pattern: "[0-9]{4}"
        example: "0150"
      postalName:
        type: string
        required: true
        description: Name of the postalCode
  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
        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: false
        description: A reference for the shipment that will be shown on the invoice.
      testIndicator:
        required: false
        type: boolean
        description: Set to true when testing API implementation.
      returnAddress:
        required: false
        type: Address
        description: An optional return address. If set will override the return address in generated label.
      packages:
        minItems: 1
        maxItems: 500
        type: Package[]
        description: The packages to send in this shipment.
  Package:
    type: object
    description: A single package in a shipment.
    properties:
      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
        description: Recipient's email address.
  SuccessfulOrder:
    (hideRequired): true
    displayName: Successful Order
    description: A successfully placed order that contains links to labels and waybill.
    properties:
      testIndicator:
        type: boolean
        description: Whether the placed order had the testIndicator flag set or not.
      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
        description: Sender's email address for the order that was placed.
      reference:
        type: string
        description: A reference for the shipment that will be shown on the invoice.
      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.
      returnAddress:
        type: AddressWithPostalName
        required: false
        description: Return address for the order if one is set
      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:
      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
        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:
      testIndicator:
        type: boolean
        description: Whether the validated order had the testIndicator flag set or not.
      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 that will be shown on the invoice.
      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.
      returnAddress:
        type: AddressWithPostalName
        required: false
        description: Return address for the order if one is set
      packages:
        minItems: 1
        description: Packages in this validated shipment. The packages in the response will correspond to same order as it was in the request to make it easier for clients to do any mapping if needed.
        type: ValidatedPackage[]
  ValidatedPackage:
    (hideRequired): true
    displayName: Validated Package
    description: A single, valid package in a valid shipment.
    properties:
      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.
  PackageWithNumbers:
    displayName: Package Details
    description: Package Details with OrderID
    properties:
      rfid:
        type: boolean
        description: Whether to activate [tracking with RFID](#tracking-with-rfid) for the package.
      recipientName:
        type: string
        description: Recipient name.
      streetAddress:
        type: string
        description: Recipient's Street address.
      postalCode:
        type: string
        description: A valid Norwegian postal code.
      postalPlace:
        type: string
        description: The city/place for the postal code.
      phoneNumber:
        type: string
        pattern: "\\+[0-9 ]+"
        description: Recipient's phone number, including country code.
        example: "+4700000000"
      email:
        type: string
        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.
      priceType:
        type: string
        description: Whether the Price is Agreement or List
        enum: [ AGREEMENT_PRICE,  LIST_PRICE]
  OrderWithLabelResponse:
    (hideRequired): true
    displayName: Successful Order
    description: A successfully label generation that contains links to labels.
    properties:
      reference:
        type: string
        description: A reference for the shipment that will be shown on the invoice.
      senderName:
        type: string
        description: Sender's name.
      streetAddress:
        type: string
        description: Sender's street address.
      email:
        type: string
        description: Sender's email address for the order that was placed.
      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.
      orderTime:
        type: datetime
        example: 2017-09-01T14:00:00.000Z
        description: Timestamp for when the order was placed.
      postalCode:
        type: string
        description: Sender's postal code.
      postalPlace:
        type: string
        description: The city/place for the postal code.
      customerNumber:
        type: string
        description: The API customer number for the validated order.
      customerName:
        type: string
        description: The API customer name for which the order was placed.
      customerOrganizationNumber:
        type: string
        description: The organization number of the customer for which the order was placed.
      testIndicator:
        type: boolean
        description: Whether the placed order had the testIndicator flag set or not.
      packages:
        minItems: 1
        description: Packages Number for the shipment.
        type: PackageWithNumbers[]
  SuccessfulLabelGenerationResponse:
    (hideRequired): true
    (hideInDocumentation): true
    type: object
    properties:
      data:
        type: object
        description: JSON-API data object.
        properties:
          type:
            type: string
            enum: [ labels ]
            description: JSON-API type.
          attributes:
            type: OrderWithLabelResponse
            description: Order properties.
  LabelRequest:
    (hideInDocumentation): true
    type: object
    properties:
      data:
        type: object
        description: JSON-API data object.
        properties:
          type:
            type: string
            enum: [ labels ]
            description: JSON-API type.
          attributes:
            type: CreateOrderRequest
            description: Order properties.
  CreateOrderRequest:
    displayName: Create Order Request
    description: It creates the Request for Label Generation.
    properties:
      customerNumber:
        type: string
        description: The API customer number for the validated order.
      senderName:
        type: string
        description: The sender's name.
      senderEmail:
        required: false
        type: string
        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: Recipient's email address.
      reference:
        required: false
        description: A reference for the shipment that will be shown on the invoice.
      testIndicator:
        type: boolean
        description: Whether the validated order had the testIndicator flag set or not.
      packages:
        minItems: 1
        maxItems: 500
        type: Package[]
        description: The packages to send in this shipment. Response will have packages in same order as requested to make it easier for clients to do any mapping if needed.
  LabelOrderRequest:
      (hideInDocumentation): true
      type: object
      properties:
        data:
          type: object
          description: JSON-API data object.
          properties:
            type:
              type: string
              enum: [ label_orders ]
              description: JSON-API type.
            attributes:
              type: CreateLabelOrderRequest
              description: Create Order properties.
  CreateLabelOrderRequest:
    displayName: Create Label Order Request
    description: Create Label Order Request
    properties:
      customerNumber:
        type: string
        description: The API customer number.
      packageNumbers:
        type: string[]
        description: List of Package Numbers.
  OrderWithIdAndEdiMessage:
    displayName: Reponse of Create Order Request
    description: Reponse of Create Order Request
    properties:
      id:
        type: number
        description: The ID of the order that was placed.
      customerNumber:
        type: string
        description: The API customer number for the validated order.
      customerName:
        type: string
        description: The API customer name 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.
      email:
        type: string
        description: Sender's email address for the order that was placed.
      postalCode:
        type: string
        description: Sender's postal code.
      reference:
        type: string
        description: A reference for the shipment that will be shown on the invoice.
      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.
      returnAddress:
        type: AddressWithPostalName
        required: false
        description: Return address for the order if one is set
      packages:
        minItems: 1
        description: Packages Number for the shipment.
        type: PackageWithNumbers[]
  SuccessfulLabelOrderResponse:
     (hideRequired): true
     (hideInDocumentation): true
     type: object
     properties:
       data:
         type: object
         description: JSON-API data object.
         properties:
           type:
             type: string
             enum: [ order ]
             description: JSON-API type.
           id:
             type: string
             description: Order Id
           attributes:
             type: OrderWithIdAndEdiMessage
             description: Label Order properties.

documentation:
- title: Introduction
  content: |
      Mailbox Packet API is an API 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 has replaced the services Minipakke and Småpakke.

      ##### There are two ways of using Mailbox Packet API

         - *Single step*: is the preferred way of usage when your work flow requires label generation, booking and waybill generation to be executed in one single step.
         - *Two steps*: is the preferred way of usage when your work flow requires flexibility, i.e. label generation to be separated from booking and waybill generation.

      ##### Single step

         - Label generation, booking and waybill generation is done in one step by requesting the rest API "[Order shipments in single step](#order-shipments-in-single-step)"

      ##### Two steps

        The process of ordering transport is split into

       - **Label generation**: first, labels are generated by requesting the rest API “[Label generation](#label-generation).” All shipments that are made through this endpoint are stored. Using this endpoint provides flexibility: Packing shipments, generating labels and sticking labels on respective shipments can be done throughout the day, without placing an order and generating a waybill.

       - **Booking and waybill generation**: second, order is placed and waybill is generated by requesting the rest API “[Waybill generation](#waybill-generation)”. The request must specify which shipments (i.e. package numbers) that are to be ordered. Note that all specified shipments in the request must already be stored, i.e. labels must already have been generated. Using this endpoint also provides flexibility: It is possible to order only a selection of the shipments stored in the database. That way, you avoid paying for shipments cancelled by end customers after the labels have been generated.
          - Shipments (i.e. package numbers) that have been stored for 120 hours without being ordered (step 2) will automatically be deleted.

- 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 shipments in single step
  description: |
      Generate labels, place order and generate waybill in one go.

      #### 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 application error | `/` |
      | 1000 | Missing field value | `/streetAddress` |
      | 2000 | Order must contain at least one package | `/packages` |
      | 2500 | Order can maximum contain 500 packages | `/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` |
      | 8000 | Invalid phone number | `/pacakges/4/phoneNumber` |
      | 9000 | Invalid JSON API resource type (must be `orders`) | `/data/type` |

      #### Testing

      This service will send actual production orders unless it is set to testing mode.
      To use the test mode, you need to set the `testIndicator` flag to true in the order attributes.
      Note that the examples below use `"testIndicator":true`, so remove this when implementing the API in your production system.

  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

/labels:
  displayName: Label generation
  description: |
      This is step 1 in the two-step way of using the Mailbox Packet API. Note that this rest API is just used to generate labels. Booking and waybill generation is done separately in step 2 by requesting the rest API “[Waybill generation.](#waybill-generation)”

  post:
    description: Generate Label for packets
    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 ]
    body:
      application/json:
        examples:
          valid_request:
            displayName: Valid Request
            value: !include examples/label_generation_request.json
        type: LabelRequest
    responses:
      201:
        description: |
          On a successful label generation, the response gives information about the shipment.
          Most importantly it contains a links to labels that have to
          be printed and sent with the shipment:

          - `labelUri`: PDF for packages without tracking
          - `rfidLabelUri`: ZPL for packages with tracking

        body:
          application/json:
            type: SuccessfulLabelGenerationResponse
            examples:
              valid_response:
                displayName: Valid Response
                value: !include examples/label_generation_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_label_geneation_request:
                displayName: Invalid Label Generation Request
                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
/label/order:
  displayName: Waybill generation
  description: This is step 2 in the two-step way of using the Mailbox Packet API. Note that this rest API is just used for booking and waybill generation. Labels must already have been generated in step 1 by requesting the rest API "[Label generation](#label-generation)”.
  post:
    description: Generate Waybill for packets
    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 ]
    body:
      application/json:
        examples:
          valid_request:
            displayName: Valid Request
            value: !include examples/label_order_create_request.json
        type: LabelOrderRequest
    responses:
      201:
        description: |
          On a successful Transport Booking, the response gives information about the Waybill.
        body:
          application/json:
            type: SuccessfulLabelOrderResponse
            examples:
              valid_response:
                displayName: Valid Response
                value: !include examples/label_order_create_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_label_geneation_request:
                displayName: Invalid Label Generation Request
                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