Rename service in English

Rename service in English

#%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) (Mailbox Delivery) shipments.

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

- title: Tracking with RFID
  content: |
      Mailbox Delivery 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: |
      This API adheres to the [JSON API](http://jsonapi.org/) specification.

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

      #### Error codes

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

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

  post:
    description: Order shipment
    headers:
      Content-Type:
        description: Specify request format (application/json)
        required: true
        enum: [ application/json ]
      Accept:
        description: Specify response format (application/json)
        required: true
        enum: [ application/json ]
    queryParameters:
        validate:
            description: If this is set to true, the order will only be validated, not ordered in our production systems.
            type: boolean
            required: false
    body:
      application/json:
        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:
        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 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: |
      This API adheres to the [JSON API](http://jsonapi.org/) specification.

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

      #### Error codes

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

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

  post:
    description: Order shipment
    headers:
      Content-Type:
        description: Specify request format (application/json)
        required: true
        enum: [ application/json ]
      Accept:
        description: Specify response format (application/json)
        required: true
        enum: [ application/json ]
    queryParameters:
        validate:
            description: If this is set to true, the order will only be validated, not ordered in our production systems.
            type: boolean
            required: false
    body:
      application/json:
        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


#7 fixing raml typo

#7 fixing raml typo

#%RAML 0.8
baseUri: http://{apiHost}
title: shoehorn
version: VERSION
mediaType:  application/json
baseUriParameters:
  apiHost:
    enum: ["dev-shoehorn.herokuapp.com","staging-shoehorn-backend.herokuapp.com","localhost:9000"]
resourceTypes:
  - collection:
      get:
        description: retrieves a list of <<resourceName>>s (all of them if no 'q' is present as query param)
        queryParameters:
          q: &q
            required: false
            description: optional query as a json expression
            example: ../<<resourceName>>s?q={"foo":true, "bar":2014}

      post:
        description: creates a new resource
        body:
          application/json:
            example: <<postexample>>
        responses:
            201:
              description: Created
              headers:
                Location:
                  description: the url of the newly created <<resourceName>>
                  example: http://{apiHost}/<<resourceName>>s/53ecbedd1700004c00d115b1
                Shoehorn-resource-id:
                  description: the id of the newly created <<resourceName>>
                  example: 53ecbedd1700004c00d115b1

  - collection-item:
      get:
        description: fetches the resource with the given id
        responses: &standardResponses
          200:
            description: OK
            body:
              application/json:
                example: <<getexample>>
          404:
            description: NOTFOUND
      put:
        description: updates an existing resource by the given id
        body:
          application/json:
            example: <<postexample>>
        responses:
          200:
            description: OK
          400:
            description: TODO
      delete:
        description: deletes the resource with the given id

/catalogs:
  type:
    collection:
      resourceName: catalog
      postexample: !include catalog.json

  /{id}:
    type:
      collection-item:
        getexample: !include catalog.json
        postexample: !include catalog.json
/products:
  type:
    collection:
      resourceName: product
      postexample: !include product.json
  get:
    queryParameters:
      q: *q
      catalogs:
        description: |
          json array of catalog ids.

          will return those products that are part of any of the given catalogs
        example: .../products?catalogs=["1","2","3"]

  /{id}:
    type:
      collection-item:
        getexample: !include product.json
        postexample: !include product.json
/warehouses:
  type:
    collection:
      resourceName: warehouse
      postexample: !include warehouse.json
  /{id}:
    type:
      collection-item:
        getexample: !include warehouse.json
        postexample: !include warehouse.json

/agents:
  type:
    collection:
      resourceName: agent
      postexample: !include agent.json
  /{id}:
    type:
      collection-item:
        getexample: !include agent.json
        postexample: !include agent.json


[ MODCAT-14 ] logical view raml modified.

#%RAML 0.8
title: LogicalView
version: v1
baseUri: http://github.com/org/folio/mod-cataloging

documentation:
  - title: mod-cataloging API
    content: This documents the API calls that can be made to manage logical view within the cataloging module.

schemas:
  - logicalView: !include schemas/logicalView.json
  - logicalViewCollection: !include schemas/logicalViewCollection.json
  - errors: !include ../raml-util/schemas/errors.schema
  - error.schema: !include ../raml-util/schemas/error.schema
  - parameters.schema: !include ../raml-util/schemas/parameters.schema

traits:
  - secured: !include ../raml-util/traits/auth.raml
  - orderable: !include ../raml-util/traits/orderable.raml
  - pageable: !include ../raml-util/traits/pageable.raml
  - searchable: !include ../raml-util/traits/searchable.raml
  - language: !include ../raml-util/traits/language.raml
  - validate: !include ../raml-util/traits/validation.raml

resourceTypes:
  - collection: !include ../raml-util/rtypes/collection.raml
  - collection-item: !include ../raml-util/rtypes/item-collection.raml
  - get-only: !include ../raml-util/rtypes/get-only.raml
  - post-empty-body: !include ../raml-util/rtypes/post-empty-body.raml

/logical-views:
  type:
    collection:
      exampleCollection: !include examples/logicalViewCollection.json
      exampleItem: !include examples/logicalView.json
      schemaCollection: logicalViewCollection
      schemaItem: logicalView
  get:
  /{viewId}:
    type:
      collection-item:
        exampleItem: !include examples/logicalView.json
        schema: logicalView
    get:
      description: Get a single logical view


Added valueType specs from 1.0 (numeric value or categorized)

Additional commit to commit 3b5f496:
The valueType of 1.0 has been re-introduced in 2.0. A value can be either a real or integer number, or the name of a category.

#%RAML 1.0 Library

# Name: dd-base-types.raml
#
# Date: 2018-07-25
#
#  This file defines the basic datatypes used in the DD API and DD-OPER API.

types:
  AdditionalQuality:
    type: integer
    description: Provides detailed information on specific Quality numbers.

  Altitude:
    description: Altitude of a (3d) coordinate
    type: number

  Aspect:
    description: A mathematical derived variant of a specific measurement, forecast, etc.
    type: object
    properties:
      name: string
      unit: string

  AspectSet:
    description: Defines a group of related mathematical values for a single measurement, forecast, etc
    type: object
    properties:
      name: AspectSetName
      aspects:
        type: Aspect[]
        minItems: 0

  AspectSetName:
    description: Name of an AspectSet
    type: string
    default: "standard"
    example: "minimum, maximum, standard, ...."

  AspectPointsValue:
    description: Object used for Event.Aspect.Points. Specifies the values in points array in context of Aspect name.
    type: object
    properties:
      name:
        type: string
        description: Name of aspect.
      points: PointsValue[]

  AspectValue:
    description: Object used for Event.Aspect[] results. Specifies the value in context of Aspect name.
    type: object
    properties:
      name:
        type: string
        description: Name of aspect.
      value: ValueType
      limitSymbol?:
        description: Specifies that the value of the quantity is e.g. higher (or lower) then the value in "value". Known limitSymbols are "<", ">", "<=", ">="
        type: number
      quality?: number
      additionalQuality?: number

  BoundingBox:
    description: The specification of a bounding box using the longitude and latitiude of the most SouthWest point followed by the most NorthEast points (GeoJSON).
    type: Double[]
    minItems: 4
    maxItems: 4
    examples:
      -bbox: [ 4.123456, 52.123456, 10.123456, 55.123456 ]

  Coordinate:
    description: Geographic coordinate,
    type: number
    format: double

  Double:
    description: A value of type Double.
    type: number
    format: double

  EndTime:
    type: datetime
    example: 2018-01-01T00:00:00Z
    description:  The End date/time of the timeseries, or the End date/time of the interval for an individual value in the series. Uses the UCT (Zulu) notation.
      The endtime is exlusive, hence the requested period ends just before the given time.
      2018-01-01T00:00:00Z - 2018-01-01T00:00:10Z  specifies a 10 minute period starting at midnight and
      ending at 2018-01-01T00:09:59.99999Z

  Error:
    description:  Error response in line with RFC7807. Although both optional the minimum information that should be given are the title and status.
    type: object
    properties:
      type?:
        description: Type of error.
        type: Url
      title?:
        description: Title of the error.
        type: string
      status?:
        type: integer
        description: The HTTP errrocode number.
      detail?:
        description: Details of the error
        type: string
      instance?:
        description: Reference to the error for the provider.
        type: string | nil
        # Additional fields, RFC7807 extension
      errors?:
        description: Error details. More than one error can occur within the problem.
        type: FilterError[]
      typeinfo?:
        description: Link to information on the type of error.  ??? Why not use 'type'. is link according RFC7807
        type: string | nil

  Event:
    description: In case of scalar time series the event contains time stamp and value, optionally extended with
      an interval specification (startTime/endTime/resultTime), and a quality indication (quality, additionalQuality).
      In case of a timeseries with Aspects or with values on multiple points, the events contains object for the aspects or points.
    type: object
    properties:
      timeStamp?:
        description: Timestamp of the occurrence of the event.
        type: datetime
      startTime?:
        description: Start time.
        type: StartTime
      endTime?:
        description: End time.
        type: EndTime
      resultTime?:
        description: Result time.
        type: datetime
      value?:
        description: The 'value', 'quantity' and 'additionalQuality' can be returned at this level (Event object) in case the AspectSet and/or Point nestings would be redundant and introduce unnecesssary levels in the response
        type: ValueType
      limitSymbol?:
        description: Specifies that the value of the quantity is e.g. higher (or lower) then the value in "value". Known limitSymbols are "<", ">", "<=", ">="
        type: number
      quality?:
        description: See value attribute.
        type: number
      additionalQuality?:
        description: See also value attribute.
        type: number
      aspects?:
        type: AspectValue[] | AspectPointsValue []
        description: When Aspects are used the value/quality/unit are given in and object for each aspect or aspect+point.
      points?:
        type: PointsValue[]
        description: When multiple positions are involved the value/quantity/unit are given in context of each position.

  Filter:
    type: string
    description: defined a query filter.

  FilterError:
    type: object
    description: Defines the field of an error in the filtering syntax.
    properties:
      errorType: string
      context: string

  Geometry:
    description: A geometry in GeoJSON format. Digital Delta currently only supports the Point and MultiPoint types.
    type: object
    properties:
      type:
        description: The geometry type. Must have the value "Point" or "MultiPoint".
        type: string
        example: "Point"
      coordinates?:
        description: An array of doubles, representing a Longitude, Latitude and optional Altitude.
        type: Position | Positions
        examples:
          -point:  [4.234 , 5.23423]
          -multipoint:  [[4.2, 52.0], [3.2, 52.3,0]]

  Identifier:
    type: string
    description: An identifier can be anything expressed as a string.

  Institution:
    type: object
    properties:
      name:
        type: string
        description: The name of the institution that produced and/or owns the data
      description?:
        type: string
        description: Additional description of the institution

# IntervalLength is not required as object since it is only used as query parameter
  IntervalLength:
    description: Interval length of the sequence.
    default: 10min

  Location:
    description: Generic DD API 2.0 Location object structure that is used by /dd and /dd-oper. Most attributes are optional as the content returned in the response depends on the request.  Location attributes are placed within the properties group of the GeoJSON  object.
    properties:
      type:
        description: Type of GeoJSON object. In the DD-API the only allowed type is "Feature".
        type: string
        enum: ["Feature"]
      geometry:
        description: The coordinate(s) of the Location are placed within the "geometry" section of the GeoJSON object. DD-API uses Point and Multi-Point locations, but is not restricted to these two.
        type: Geometry | nil
      properties?:
        description: The attributes of Location object are placed within the properties group of the GeoJSON object.
        type: object
        properties:
          url?:
            description: Url to details.
            type: string
          node?:
            description: Node reference.
            type: Node
          locationId?:
            description: Id of the location.
            type: string
          locationCode?:
            description: Code of the location.
            type: string
          locationName?:
            description: Name of the location.
            type: LocationName
          referenceLevel?:
            description: GeoJSON element. Specifies the reference plane for the altitude coordinates (third). For example "NAP".
            type: string
          crs?:
            description: GeoJSON element. According to GeoJSON the coordinate reference system element is only included when it is not "WGS84" (default).
            type: string
          locationNameSpace?:
            description: Location name space.
            type: LocationNameSpace
          displayNameDetail?:
            type: LocationName
            description: Remark, Only used in dd-oper response.
          displayNameGlobal?:
            type: LocationName
            description: Remark, Only used in dd-oper response.
          displayNameSpace?:
            type: LocationNameSpace
            description: Remark, Only used in dd-oper response.
          parentName?:
            type: LocationName
            description: Remark, Only used in dd-oper response.

  LocationName:
    type: string
    example: "Hoek-van-Holland"

  LocationNameSpace:
    type: string
    example: "NL.RWS.WM"

  Node:
    description: Node objects contain the properties of the data node. A node is an operational implementation of the Digital Delta specification.
    type: object
    properties:
      id?:
        description: Id of the node.
        type: Identifier
      name:
        type: string
        description: The name of the node.<br/>
      description?:
        type: string
        description: The description of the node.
      baseUrl?:
        type: string
        description: The base URL of the node.

  ObservationType:
    description: Generic DD API 2.0 parameter object. DD-OPER API response returns a subset of the attributes.
    type: object
    properties:
      id?:
        description: Id of the observation type.
        type: Identifier
      url?:
        description: Url with details.
        type: Url
      node?:
        description: Reference to the node.
        type: Node
      quantity?:
        description: Quantity (grootheid) of the observation type.
        type: string
      parameterCode?:
        description: Parameter code specifying the observationtype. Non-biological observation types follow the Aquo standards.
        type: string
      description?:
        description: Description of the observation type.
        type: string
      unit?:
        description: (Measurement) unit of the observation type.
        type: string
      compartment?:
        description: The compartment in which the measurement/computationt is available. Standardised Aquo compartments.
        type: string
        example:  OW, DL, GW, LW
      quantityName?:
        description: Composed name of the quantity(.parameterCode) that was measured or computed.
          Remark Only used in dd-oper response.
        type: QuantityName
      aspectSet?:
        description: Optional, currently only provided and used by RWS.
        type: AspectSet

  PageLinks:
    description: The object contains urls and page size information to support back and forward paging
    type: object
    properties:
      totalObjectCount?:
        description: The actual number of objects available. When paging is used the response contains a subset of the total obejcts available up to the max page size.
        type: integer
      maxPageSize?:
        description: Maximum number of objects in the response. Defined by the Provider of the response.
        type: PageSize
      minPageSize?:
          description: Minimum number of objects in the response. Defined by the Provider of the response.
          type: PageSize
          minimum: 1
      self?:
        description: Url of the current request.
        type: Url | nil
      first?:
        description: Url to the first page of the result set.
        type: Url | nil
      prev:
        description: Url to the previous page of the result set.
        type: Url | nil
      next:
        description: Url to the next page of the result set.
        type: Url | nil
      last?:
        description: Url to the last page of the result set.
        type: Url | nil

  PageNumber:
    description: Page number in case the response is seprated in different pages.
    type: integer
    minimum: 1
    example: 1

  PageSize:
    description: Number of result objects per a single response page. Used for minimum, maximum and/or actual.
    type: integer
    minimum: 1
    maximum: 10000
    example: 10

  PointsValue:
    type: object
    properties:
      coordinates: Position
      value:
        description: The 'value', 'quantity' and 'additionalQuality' can be returned at this level (Event object) in case the AspectSet and/or Point nestings would be redundant and introduce unnecesssary levels in the response
        type: ValueType
      limitSymbol?:
        description: Specifies that the value of the quantity is e.g. higher (or lower) then the value in "value". Known limitSymbols are "<", ">", "<=", ">="
        type: number
      quality?:
        description: See also value attribute.
        type: number
      additionalQuality?:
        description: See also value attribute.
        type: number

  Position:
    description: |
      A location specified in an array with longitude, lattitude and optional altitude.
    type: Double[]
    minItems: 2
    maxItems: 3
    example: [4.234 , 5.23423]

  Positions:
    description: An array of Positions to specify a MultiPpoint location.
    type: Position[]
    minItems: 0
    examples:
      -multipoint: [[4.2, 52.0], [3.2, 52.3,0]]

  ProcessName:
    type: string
    description: The name of the mechanism to collect/derive the timeseries value.
      When accessing RWS' DD-API, providing a processName as query parameter is required. The process names are pre-defined (see examples).
      Extending the processname with a suffix, referencing a more detailed mechanism like a specific calculation model, is not allowed.
      Other implementions dot need to implement this query-parameter.
    example: measurement, forecast, astronomical, advise

  Provider:
    type: object
    description: Information regarding the system that is responible for the response.
      Provides support contact information in case there are issues with response format or content.
    properties:
      name?:
        description: Name of the provider (of the service).
        type: string
      supportUrl?:
        description: Url to information for the provider (of the service).
        type: string
      apiVersion?:
        description: API Version with which the result set was generated. Can be used to parse the response.
        type: string
      responseType?:
        description: Name of the type of the result set. Can be used to parse the response.
        type: string
      responseTimestamp?:
        type: Timestamp
        description: Timestamp when this response was created.

  Quality:
    description: Defines the quality of the result (confidence).
    type: integer

  QuantityName:
    type: string
    description: A name referencing a category of timeseries. The quantity names are predefined.
      For example 'WaterLevel', 'WaterTemperature', 'WaveHeight'.
    example: WaterLevel

  Source:
    description: Describes the type of data in the time series, and the owner of the data.
    type: object
    properties:
      process:
        description: Name of the process.
        type: ProcessName
      name?:
        type: SourceName
        description: A name describing the source, e.g. a model name.
      description?:
        type: string
        description: Additional description of the data source (might contain a URL to a site with information on the model).
      realizationCount?:
        type: integer
        description: if present, and larger then 1, the results are part of an ensemble run
      institution: Institution

  SourceName:
    type: string
    description: A name describing the source, e.g. a model name
    example: rws_prediction

  StartTime:
    type: datetime
    example: 2016-01-01T12:45:00Z
    description:  Start date/time of the timeseries, or the Start date/time of the interval for an individual value in the series. Uses the UCT (Zulu) notation.

  Timeseries:
    description: Generic DD API 2.0 timeseries object.DD API 'OPER' response returns a subset of the attributes.
    type: object
    properties:
      node?:
        description: Reference to the Node.
        type: Node
      url?:
        description: URL of the time series.
        type: string
      id?:
        description: IdL of the time series.
        type: Identifier
      source:
        description: Source of the time series.
        type: Source
      location:
        description: Location of the time series.
        type: Location
      observationType:
        description: Observation type of the time series (concentration, parameter, etc.).
        type: ObservationType
      startTime:
        description: Start date-time of the time series.
        type: datetime
      endTime:
        description: End date-time  of the time series.
        type: datetime
      analysisTime?:
        description: Analysis date-time of the time series.
        type: datetime
      realization?:
        description: Realization count.
        type: number
      interval?:
        description: Specifies the interval between events in the timeseries. If present and set to 'null', the time series is non-equidistant.
        type: number
      valueType?:
        description: The data type of the measured or computed data (double, integer, categorized).
        type: string
      events?:
        type: Event[]
        description: If no startTime and no endTime are provided in the /timeseries-query, only meta-data is provided,
          so the events are not present.

  Timestamp:
    type: string
    description: Date and time in format "yyyy-mmm-ddThh:mm:ss.ffffffZ"  (UTC Zulu with minimal 3 digits of fractional seconds)
    example: "2018-07-05T15:11:36.123Z, 2018-07-05T15:11:36.123456Z, 2018-07-05T15:11:36.000Z"
    minLength: 24

  ValueType:
    type: number | string
    description: The type of values in the time series ('string' in case of categorized values, like 'natuurlijk' vs 'aangelegd').

  Url:
    type: string
    description: Correctly formatted url reference.

  Uuid:
    type: string
    pattern: "[0-9a-f]{8}-([0-9a-f]{4}-){3}[0-9a-f]{12}"
    description: Unique identifier for the datasource. Version 4.
    example: 978fdf5c-95c8-43a5-82ff-d27d9e6d685f

#%RAML 1.0 Library

# Name: dd-base-types.raml
#
# Date: 2018-07-25
#
#  This file defines the basic datatypes used in the DD API and DD-OPER API.

types:
  AdditionalQuality:
    type: integer
    description: Provides detailed information on specific Quality numbers.

  Altitude:
    description: Altitude of a (3d) coordinate
    type: number

  Aspect:
    description: A mathematical derived variant of a specific measurement, forecast, etc.
    type: object
    properties:
      name: string
      unit: string

  AspectSet:
    description: Defines a group of related mathematical values for a single measurement, forecast, etc
    type: object
    properties:
      name: AspectSetName
      aspects:
        type: Aspect[]
        minItems: 0

  AspectSetName:
    description: Name of an AspectSet
    type: string
    default: "standard"
    example: "minimum, maximum, standard, ...."

  AspectPointsValue:
    description: Object used for Event.Aspect.Points. Specifies the values in points array in context of Aspect name.
    type: object
    properties:
      name:
        type: string
        description: Name of aspect.
      points: PointsValue[]

  AspectValue:
    description: Object used for Event.Aspect[] results. Specifies the value in context of Aspect name.
    type: object
    properties:
      name:
        type: string
        description: Name of aspect.
      value: number
      limitSymbol?:
        description: Specifies that the value of the quantity is e.g. higher (or lower) then the value in "value". Known limitSymbols are "<", ">", "<=", ">="
        type: number
      quality?: number
      additionalQuality?: number

# BB is not required as object since bbox is only used as query parameter (toch maar laten staan? SH)
  BoundingBox:
    description: The specification of a bounding box using the longitude and latitiude of the most SouthWest point followed by the most NorthEast points (GeoJSON).
    type: Double[]
    minItems: 4
    maxItems: 4
    examples:
      -bbox: [ 4.123456, 52.123456, 10.123456, 55.123456 ]

  Coordinate:
    description: Geographic coordinate,
    type: number
    format: double

  Double:
    description: A value of type Double.
    type: number
    format: double

  EndTime:
    type: datetime
    example: 2018-01-01T00:00:00Z
    description:  The End date/time of the timeseries, or the End date/time of the interval for an individual value in the series. Uses the UCT (Zulu) notation.
      The endtime is exlusive, hence the requested period ends just before the given time.
      2018-01-01T00:00:00Z - 2018-01-01T00:00:10Z  specifies a 10 minute period starting at midnight and
      ending at 2018-01-01T00:09:59.99999Z

  Error:
    description:  Error response in line with RFC7807. Although both optional the minimum information that should be given are the title and status.
    type: object
    properties:
      type?:
        description: Type of error.
        type: Url
      title?:
        description: Title of the error.
        type: string
      status?:
        type: integer
        description: The HTTP errrocode number.
      detail?:
        description: Details of the error
        type: string
      instance?:
        description: Reference to the error for the provider.
        type: string | nil
        # Additional fields, RFC7807 extension
      errors?:
        description: Error details. More than one error can occur within the problem.
        type: FilterError[]
      typeinfo?:
        description: Link to information on the type of error.  ??? Why not use 'type'. is link according RFC7807
        type: string | nil

  Event:
    description: In case of scalar time series the event contains time stamp and value, optionally extended with
      an interval specification (startTime/endTime/resultTime), and a quality indication (quality, additionalQuality).
      In case of a timeseries with Aspects or with values on multiple points, the events contains object for the aspects or points.
    type: object
    properties:
      timeStamp?:
        description: Timestamp of the occurrence of the event.
        type: datetime
      startTime?:
        description: Start time.
        type: StartTime
      endTime?:
        description: End time.
        type: EndTime
      resultTime?:
        description: Result time.
        type: datetime
      value?:
        description: The 'value', 'quantity' and 'additionalQuality' can be returned at this level (Event object) in case the AspectSet and/or Point nestings would be redundant and introduce unnecesssary levels in the response
        type: number
      limitSymbol?:
        description: Specifies that the value of the quantity is e.g. higher (or lower) then the value in "value". Known limitSymbols are "<", ">", "<=", ">="
        type: number
      quality?:
        description: See value attribute.
        type: number
      additionalQuality?:
        description: See also value attribute.
        type: number
      aspects?:
        type: AspectValue[] | AspectPointsValue []
        description: When Aspects are used the value/quality/unit are given in and object for each aspect or aspect+point.
      points?:
        type: PointsValue[]
        description: When multiple positions are involved the value/quantity/unit are given in context of each position.

  Filter:
    type: string
    description: defined a query filter.

  FilterError:
    type: object
    description: Defines the field of an error in the filtering syntax.
    properties:
      errorType: string
      context: string

  Geometry:
    description: A geometry in GeoJSON format. Digital Delta currently only supports the Point and MultiPoint types.
    type: object
    properties:
      type:
        description: The geometry type. Must have the value "Point" or "MultiPoint".
        type: string
        example: "Point"
      coordinates?:
        description: An array of doubles, representing a Longitude, Latitude and optional Altitude.
        type: Position | Positions
        examples:
          -point:  [4.234 , 5.23423]
          -multipoint:  [[4.2, 52.0], [3.2, 52.3,0]]

  Identifier:
    type: string
    description: An identifier can be anything expressed as a string.

  Institution:
    type: object
    properties:
      name:
        type: string
        description: The name of the institution that produced and/or owns the data
      description?:
        type: string
        description: Additional discription of the institution

# IntervalLength is not required as object since it is only used as query parameter
  IntervalLength:
    description: Interval length of the sequence.
    default: 10min

  Location:
    description: Generic DD API 2.0 Location object structure that is used by /dd and /dd-oper. Most attributes are optional as the content returned in the response depends on the request.  Location attributes are placed within the properties group of the GeoJSON  object.
    properties:
      type:
        description: Type of GeoJSON object. In the DD-API the only allowed type is "Feature".
        type: string
        enum: ["Feature"]
      geometry:
        description: The coordinate(s) of the Location are placed within the "geometry" section of the GeoJSON object. DD-API uses Point and Multi-Point locations, but is not restricted to these two.
        type: Geometry | nil
      properties?:
        description: The attributes of Location object are placed within the properties group of the GeoJSON object.
        type: object
        properties:
          url?:
            description: Url to details.
            type: string
          node?:
            description: Node reference.
            type: Node
          locationId?:
            description: Id of the location.
            type: string
          locationCode?:
            description: Code of the location.
            type: string
          locationName?:
            description: Name of the location.
            type: LocationName
          referenceLevel?:
            description: GeoJSON element. Specifies the reference plane for the altitude coordinates (third). For example "NAP".
            type: string
          crs?:
            description: GeoJSON element. According to GeoJSON the coordinate reference system element is only included when it is not "WGS84" (default).
            type: string
          locationNameSpace?:
            description: Location name space.
            type: LocationNameSpace
          displayNameDetail?:
            type: LocationName
            description: Remark, Only used in dd-oper response.
          displayNameGlobal?:
            type: LocationName
            description: Remark, Only used in dd-oper response.
          displayNameSpace?:
            type: LocationNameSpace
            description: Remark, Only used in dd-oper response.
          parentName?:
            type: LocationName
            description: Remark, Only used in dd-oper response.

  LocationName:
    type: string
    example: "Hoek-van-Holland"

  LocationNameSpace:
    type: string
    example: "NL.RWS.WM"

  Node:
    description: Node objects contain the properties of the data node. A node is an operational implementation of the Digital Delta specification.
    type: object
    properties:
      id?:
        description: Id of the node.
        type: Identifier
      name:
        type: string
        description: The name of the node.<br/>
      description?:
        type: string
        description: The description of the node.
      baseUrl?:
        type: string
        description: The base URL of the node.

  ObservationType:
    description: Generic DD API 2.0 parameter object. DD-OPER API response returns a subset of the attributes.
    type: object
    properties:
      id?:
        description: Id of the observation type.
        type: Identifier
      url?:
        description: Url with details.
        type: Url
      node?:
        description: Reference to the node.
        type: Node
      quantity?:
        description: Quantity (grootheid) of the observation type.
        type: string
      parameterCode?:
        description: Parameter code specifying the observationtype. Non-biological observation types follow the Aquo standards.
        type: string
      description?:
        description: Description of the observation type.
        type: string
      unit?:
        description: (Measurement) unit of the observation type.
        type: string
      compartment?:
        description: The compartment in which the measurement/computationt is available. Standardised Aquo compartments.
        type: string
        example:  OW, DL, GW, LW
      quantityName?:
        description: Composed name of the quantity(.parameterCode) that was measured or computed.
          Remark Only used in dd-oper response.
        type: QuantityName
      aspectSet?:
        description: Optional, currently only provided and used by RWS.
        type: AspectSet

  PageLinks:
    description: The object contains urls and page size information to support back and forward paging
    type: object
    properties:
      totalObjectCount?:
        description: The actual number of objects available. When paging is used the response contains a subset of the total obejcts available up to the max page size.
        type: integer
      maxPageSize?:
        description: Maximum number of objects in the response. Defined by the Provider of the response.
        type: PageSize
      minPageSize?:
          description: Minimum number of objects in the response. Defined by the Provider of the response.
          type: PageSize
          minimum: 1
      self?:
        description: Url of the current request.
        type: Url | nil
      first?:
        description: Url to the first page of the result set.
        type: Url | nil
      prev:
        description: Url to the previous page of the result set.
        type: Url | nil
      next:
        description: Url to the next page of the result set.
        type: Url | nil
      last?:
        description: Url to the last page of the result set.
        type: Url | nil

  PageNumber:
    description: Page number in case the response is seprated in different pages.
    type: integer
    minimum: 1
    example: 1

  PageSize:
    description: Number of result objects per a single response page. Used for minimum, maximum and/or actual.
    type: integer
    minimum: 1
    maximum: 10000
    example: 10

  PointsValue:
    type: object
    properties:
      coordinates: Position
      value:
        description: The 'value', 'quantity' and 'additionalQuality' can be returned at this level (Event object) in case the AspectSet and/or Point nestings would be redundant and introduce unnecesssary levels in the response
        type: number
      limitSymbol?:
        description: Specifies that the value of the quantity is e.g. higher (or lower) then the value in "value". Known limitSymbols are "<", ">", "<=", ">="
        type: number
      quality?:
        description: See also value attribute.
        type: number
      additionalQuality?:
        description: See also value attribute.
        type: number

  Position:
    description: |
      A location specified in an array with longitude, lattitude and optional altitude.
    type: Double[]
    minItems: 2
    maxItems: 3
    example: [4.234 , 5.23423]

  Positions:
    description: An array of Positions to specify a MultiPpoint location.
    type: Position[]
    minItems: 0
    examples:
      -multipoint: [[4.2, 52.0], [3.2, 52.3,0]]

  ProcessName:
    type: string
    description: The name of the mechanism to collect/derive the timeseries value.
      When accessing RWS' DD-API, providing a processName as query parameter is required. The process names are pre-defined (see examples).
      Extending the processname with a suffix, referencing a more detailed mechanism like a specific calculation model, is not allowed.
      Other implementions dot need to implement this query-parameter.
    example: measurement, forecast, astronomical, advise

  Provider:
    type: object
    description: Information regarding the system that is responible for the response.
      Provides support contact information in case there are issues with response format or content.
    properties:
      name?:
        description: Name of the provider (of the service).
        type: string
      supportUrl?:
        description: Url to information for the provider (of the service).
        type: string
      apiVersion?:
        description: API Version with which the result set was generated. Can be used to parse the response.
        type: string
      responseType?:
        description: Name of the type of the result set. Can be used to parse the response.
        type: string
      responseTimestamp?:
        type: Timestamp
        description: Timestamp when this response was created.

  Quality:
    description: Defines the quality of the result (confidence).
    type: integer

  QuantityName:
    type: string
    description: A name referencing a category of timeseries. The quantity names are predefined.
      For example 'WaterLevel', 'WaterTemperature', 'WaveHeight'.
    example: WaterLevel

  Source:
    description: Describes the type of data in the time series, and the owner of the data.
    type: object
    properties:
      process:
        description: Name of the process.
        type: ProcessName
      name?:
        type: SourceName
        description: A name describing the source, e.g. a model name.
      description?:
        type: string
        description: Additional description of the data source (might contain a URL to a site with information on the model).
      realizationCount?:
        type: integer
        description: if present, and larger then 1, the results are part of an ensemble run
      institution: Institution

  SourceName:
    type: string
    description: A name describing the source, e.g. a model name
    example: rws_prediction

  StartTime:
    type: datetime
    example: 2016-01-01T12:45:00Z
    description:  Start date/time of the timeseries, or the Start date/time of the interval for an individual value in the series. Uses the UCT (Zulu) notation.

  Timeseries:
    description: Generic DD API 2.0 timeseries object.DD API 'OPER' response returns a subset of the attributes.
    type: object
    properties:
      node?:
        description: Reference to the Node.
        type: Node
      url?:
        description: URL of the time series.
        type: string
      id?:
        description: IdL of the time series.
        type: Identifier
      source:
        description: Source of the time series.
        type: Source
      location:
        description: Location of the time series.
        type: Location
      observationType:
        description: Observation ty[e] of the time series.
        type: ObservationType
      startTime:
        description: Start date-time of the time series.
        type: datetime
      endTime:
        description: End date-time  of the time series.
        type: datetime
      analysisTime?:
        description: Analysis date-time of the time series.
        type: datetime
      realization?:
        description: Realization count.
        type: number
      interval?:
        description: Specifies the interval between events in the timeseries. If present and set to 'null', the time series is non-equidistant.
        type: number
      valueType?:
        description: The data type of the measured or computed data (double, integer, catagorized).
        type: number
      events?:
        type: Event[]
        description: If no startTime and no endTime are provided in the /timeseries-query, only meta-data is provided,
          so the events are not present.

  Timestamp:
    type: string
    description: Date and time in format "yyyy-mmm-ddThh:mm:ss.ffffffZ"  (UTC Zulu with minimal 3 digits of fractional seconds)
    example: "2018-07-05T15:11:36.123Z, 2018-07-05T15:11:36.123456Z, 2018-07-05T15:11:36.000Z"
    minLength: 24

  Url:
    type: string
    description: Correctly formatted url reference.

  Uuid:
    type: string
    pattern: "[0-9a-f]{8}-([0-9a-f]{4}-){3}[0-9a-f]{12}"
    description: Unique identifier for the datasource. Version 4.
    example: 978fdf5c-95c8-43a5-82ff-d27d9e6d685f


Add descriptions for types

Add descriptions for types

#%RAML 1.0
---
title: Order to Mailbox API
version: v1
baseUri: https://api.bring.com/order/to-mailbox
mediaType: application/json
annotationTypes:
  hideInDocumentation: boolean
  hideRequired: boolean
types:
  Order:
    type: object
    properties:
      customerNumber:
        type: string
        description: API customer number for which to place the order.
      senderName:
        type: string
        description: Sender's name.
        example: Min Bedrift
      senderEmail:
        required: false
        type: string
        pattern: ".+@.+"
        description: Sender's email address. Defaults to the user's email address.
      postalCode:
        type: string
        description: Sender's postal code. Must be a valid Norwegian postal code.
      streetAddress:
        type: string
        description: Sender's street address.
      reference:
        required: true
        description: A reference for the shipment (all packages).
      packages:
        minItems: 1
        type: Package[]
        description: The packages to send in this shipment.
  Package:
    type: object
    properties:
      priority:
        enum: [ A, B ]
        description: Delivery speed (A-post or B-post).
      rfid:
        type: boolean
        description: Whether to activate [tracking with RFID](#tracking-with-rfid) for the package.
      weight:
        maximum: 2000
        type: integer
        description: Weight in grams.
      recipientName:
        type: string
        description: Recipient name.
      postalCode:
        type: string
        description: A valid Norwegian postal code.
      streetAddress:
        type: string
        description: Recipient's street address.
      phoneNumber:
        type: string
        pattern: "\\+[0-9 ]+"
        description: Recipient's phone number, including country code.
        example: "+4700000000"
      email:
        type: string
        pattern: ".+@.+"
        description: Recipient's email address.
  SuccessfulOrder:
    (hideRequired): true
    displayName: Successful Order
    properties:
      id:
        type: number
        description: The ID of the order that was placed.
      customerNumber:
        type: string
        description: The API customer number for which the order was placed.
      customerName:
        type: string
        description: The name of the customer for which the order was placed.
      customerOrganizationNumber:
        type: string
        description: The organization number of the customer for which the order was placed.
      senderName:
        type: string
        description: Sender's name.
      streetAddress:
        type: string
        description: Sender's street address.
      postalCode:
        type: string
        description: Sender's postal code.
      postalPlace:
        type: string
        description: The city/place for the postal code.
      email:
        type: string
        pattern: ".+@.+"
        description: Sender's email address that for the order that was placed.
      reference:
        type: string
        description: A reference for the shipment (all packages)
      labelUri:
        type: string
        description: URL to PDF label if ordered without tracking.
      rfidLabelUri:
        type: string
        description: URL to ZPL label if ordered with tracking.
      waybillUri:
        type: string
        description: URL to waybill PDF that goes with the order.
      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.
      userEmail:
        required: false
        type: string
        description: The email address for the user that placed the order.
      userPhone:
        required: false
        type: string
        description: The phone number for the user that placed the order.
      userFullName:
        required: false
        type: string
        description: The name for the user that placed the order.
      orderNumberReference:
        type: string
        description: The order number reference for the placed order. This is the number on the waybill.
      packages:
        minItems: 1
        description: Packages in this shipment.
        type: OrderedPackage[]
  OrderedPackage:
    (hideRequired): true
    displayName: Ordered Package
    properties:
      priority:
        enum: [ A, B ]
        description: Delivery speed (A-post or B-post).
      rfid:
        type: boolean
        description: Whether to [tracking for the package](#tracking-with-rfid) was activated.
      specialist:
        type: string
        description: The type of customer for which the order was placed.
      recipientName:
        type: string
        description: Recipient name.
      streetAddress:
        type: string
        description: Recipient's street address.
      postalCode:
        type: string
        description: Recipient's postal code.
      postalPlace:
        type: string
        description: The city/place for the postal code.
      phoneNumber:
        type: string
        pattern: "\\+[0-9 ]+"
        description: Recipient's phone number.
      email:
        type: string
        pattern: ".+@.+"
        description: Recipient's email address.
      weight:
        maximum: 2000
        type: integer
        description: Package weight in grams.
      shipmentNumber:
        type: string
        description: The shipment number for this package. A package in a PIP shipment will have both a shipment number and a package number.
      packageNumber:
        type: string
        description: The package number for this package. This goes on the label.
      agreementNumber:
        type: boolean
        description: Whether the customer has an agreement price for this package.
  ValidatedOrder:
    (hideRequired): true
    displayName: Validated Order
    properties:
      customerNumber:
        type: string
        description: The API customer number for the validated order.
      customerName:
        type: string
        description: The name of the customer for the validated order.
      customerOrganizationNumber:
        type: string
        description: The organization number of the customer for the validated order.
      senderName:
        type: string
        description: The sender's name.
      streetAddress:
        type: string
        description: The sender's street address.
      postalCode:
        type: string
        description: The sender's postal code.
      postalPlace:
        type: string
        description: The city/place for the postal code.
      email:
        type: string
        description: The sender's email address.
      reference:
        type: string
        description: A reference for the shipment (all packages).
      priceWithoutVat:
        type: number
        description: Calculated price without VAT (MVA).
      priceWithVat:
        type: number
        description: Calulated price with VAT (MVA).
      vat:
        type: number
        description: Calculated VAT (MVA).
      currency:
        type: string
        description: The price's currency.
      orderTime:
        type: datetime
        description: Timestamp for when the order was validated.
      packages:
        minItems: 1
        description: Packages in this validated shipment.
        type: ValidatedPackage[]
  ValidatedPackage:
    (hideRequired): true
    displayName: Validated Package
    properties:
      priority:
        enum: [ A, B ]
        description: Delivery speed (A-post or B-post).
      rfid:
        type: boolean
        description: Whether to [tracking with RFID](#tracking-with-rfid) was activated for the package.
      recipientName:
        type: string
        description: Recipient's name.
      streetAddress:
        type: string
        description: Recipient's email address.
      postalCode:
        type: string
        description: Recipient's postal code.
      postalPlace:
        type: string
        description: The city/place for the postal code.
      phoneNumber:
        type: string
        description: Recipient's phone number.
      email:
        type: string
        description: Recipient's email address.
      weight:
        type: integer
        description: Package weight in grams.
      agreementNumber:
        type: boolean
        description: Whether the customer has an agreement price for this package.
  OrderRequest:
    (hideInDocumentation): true
    type: object
    properties:
      data:
        type: object
        description: JSON-API data object.
        properties:
          type:
            type: string
            pattern: "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: See the [JSON-API documentation](http://jsonapi.org/format/#error-objects).
  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 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) (Mailbox Delivery) shipments.

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

- title: Tracking with RFID
  content: |
      Mailbox Delivery 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: |
      This API adheres to the [JSON API](http://jsonapi.org/) specification.

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

      #### Error codes

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

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

  post:
    description: Order shipment
    headers:
      Content-Type:
        description: Specify request format (application/json)
        required: true
        enum: [ application/json ]
      Accept:
        description: Specify response format (application/json)
        required: true
        enum: [ application/json ]
    queryParameters:
        validate:
            description: If this is set to true, the order will only be validated, not ordered in our production systems.
            type: boolean
            required: false
    body:
      application/json:
        example: !include examples/without_tracking_request.json
        type: OrderRequest
    responses:
      200:
        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: ValidatedOrderResponse
            example: !include examples/validate_order_response.json
      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: SuccessfulOrderResponse
            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: SuccessfulOrderResponse
            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
annotationTypes:
  hideInDocumentation: boolean
  hideRequired: boolean
types:
  Order:
    type: object
    properties:
      customerNumber:
        type: string
      senderName:
        type: string
      senderEmail:
        required: false
        type: string
        pattern: ".+@.+"
        description: Defaults to the user's email address.
      postalCode:
        type: string
        description: A valid Norwegian postal code.
      streetAddress:
        type: string
      reference:
        required: true
      packages:
        minItems: 1
        type: Package[]
  Package:
    type: object
    properties:
      priority:
        enum: [ A, B ]
        description: Delivery speed (A-post or B-post).
      rfid:
        type: boolean
        description: Whether to activate [tracking for the package](#tracking-with-rfid)
      weight:
        maximum: 2000
        type: integer
      recipientName: string
      postalCode:
        type: string
        description: A valid Norwegian postal code.
      streetAddress:
        type: string
      phoneNumber:
        type: string
        pattern: "\\+[0-9 ]+"
        description: A phone number including country code
        example: "+4700000000"
      email:
        type: string
        pattern: ".+@.+"
  SuccessfulOrder:
    (hideRequired): true
    displayName: Successful Order
    properties:
      id:
        type: number
      customerName:
        type: string
      customerOrganizationNumber:
        type: string
      customerNumber:
        type: string
      senderName:
        type: string
      streetAddress:
        type: string
      postalCode:
        type: string
        description: A valid Norwegian postal code.
      postalPlace:
        type: string
      email:
        type: string
        pattern: ".+@.+"
      reference:
        type: string
      labelUri:
        type: string
        description: URL to PDF label if ordered without tracking.
      rfidLabelUri:
        type: string
        description: URL to ZPL label if ordered with tracking.
      waybillUri:
        type: string
        description: URL to waybill PDF that goes with the order.
      priceWithoutVat:
        type: number
      priceWithVat:
        type: number
      vat:
        type: number
      currency:
        type: string
        default: NOK
      orderTime:
        type: datetime
      userEmail:
        required: false
        type: string
        description: The email address for the user that placed the order.
      userPhone:
        required: false
        type: string
        description: The phone number for the user that placed the order.
      userFullName:
        required: false
        type: string
        description: The name for the user that placed the order.
      orderNumberReference:
        type: string
        description: The order number reference for the placed order. This is the number on the waybill.
      packages:
        minItems: 1
        type: OrderedPackage[]
  OrderedPackage:
    (hideRequired): true
    displayName: Ordered Package
    properties:
      priority:
        enum: [ A, B ]
        description: Delivery speed (A-post or B-post).
      rfid:
        type: boolean
        description: Whether to [tracking for the package](#tracking-with-rfid) was activated.
      specialist:
        type: string
        description: The type of customer for which the order was placed.
      recipientName:
        type: string
      streetAddress:
        type: string
      postalCode:
        type: string
        description: A valid Norwegian postal code.
      postalPlace:
        type: string
      phoneNumber:
        type: string
        pattern: "\\+[0-9 ]+"
        description: A phone number including country code
        example: "+4700000000"
      email:
        type: string
        pattern: ".+@.+"
      weight:
        maximum: 2000
        type: integer
      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.
  ValidatedOrder:
    (hideRequired): true
    displayName: Validated Order
    properties:
      id:
        type: number
      customerName:
        type: string
      customerOrganizationNumber:
        type: string
      customerNumber:
        type: string
      senderName:
        type: string
      streetAddress:
        type: string
      postalCode:
        type: string
        description: A valid Norwegian postal code.
      postalPlace:
        type: string
      email:
        type: string
        pattern: ".+@.+"
      reference:
        type: string
      priceWithoutVat:
        type: number
      priceWithVat:
        type: number
      vat:
        type: number
      currency:
        type: string
        default: NOK
      orderTime:
        type: datetime
      packages:
        minItems: 1
        type: ValidatedPackage[]
  ValidatedPackage:
    (hideRequired): true
    displayName: Validated Package
    properties:
      priority:
        enum: [ A, B ]
        description: Delivery speed (A-post or B-post).
      rfid:
        type: boolean
        description: Whether to [tracking for the package](#tracking-with-rfid) was activated.
      recipientName:
        type: string
      streetAddress:
        type: string
      postalCode:
        type: string
        description: A valid Norwegian postal code.
      postalPlace:
        type: string
      phoneNumber:
        type: string
        pattern: "\\+[0-9 ]+"
        description: A phone number including country code
        example: "+4700000000"
      email:
        type: string
        pattern: ".+@.+"
      weight:
        maximum: 2000
        type: integer
      agreementNumber:
        type: boolean
        description: Whether you got an agreement price for this package.
  OrderRequest:
    (hideInDocumentation): true
    type: object
    properties:
      data:
        type: object
        properties:
          type:
            type: string
            pattern: "orders"
          attributes: Order
  SuccessfulOrderResponse:
    (hideRequired): true
    (hideInDocumentation): true
    type: object
    properties:
      data:
        type: object
        properties:
          type:
            type: string
            pattern: "order"
          id: string
          attributes: SuccessfulOrder
  ValidatedOrderResponse:
    (hideRequired): true
    (hideInDocumentation): true
    type: object
    properties:
      data:
        type: object
        properties:
          type:
            type: string
            pattern: "order"
          id: string
          attributes: ValidatedOrder
  ErrorResponse:
    (hideRequired): true
    (hideInDocumentation): true
    type: object
    properties:
      errors:
        type: ErrorObject[]
        description: See the [JSON-API documentation](http://jsonapi.org/format/#error-objects).
  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 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) (Mailbox Delivery) shipments.

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

- title: Tracking with RFID
  content: |
      Mailbox Delivery 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: |
      This API adheres to the [JSON API](http://jsonapi.org/) specification.

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

      #### Error codes

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

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

  post:
    description: Order shipment
    headers:
      Content-Type:
        description: Specify request format (application/json)
        required: true
        enum: [ application/json ]
      Accept:
        description: Specify response format (application/json)
        required: true
        enum: [ application/json ]
    queryParameters:
        validate:
            description: If this is set to true, the order will only be validated, not ordered in our production systems.
            type: boolean
            required: false
    body:
      application/json:
        example: !include examples/without_tracking_request.json
        type: OrderRequest
    responses:
      200:
        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: ValidatedOrderResponse
            example: !include examples/validate_order_response.json
      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: SuccessfulOrderResponse
            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: SuccessfulOrderResponse
            example: !include examples/without_tracking_response.json