Remove trailing spaces FOLIO-351

Remove trailing spaces FOLIO-351

#%RAML 0.8

title: Admin API
baseUri: http://localhost:8081/{version}
version: v1

traits:
  - log-level: !include traits/log-level.raml
  - upload-handler: !include traits/upload-handler.raml
  - history: !include traits/history.raml
  - dbname: !include traits/dbname.raml
  - secured: !include raml-util/traits/auth.raml
  - secret-key: !include traits/secret-key.raml
  - slow-query: !include traits/slow-query.raml
  - pid: !include traits/pid.raml

/admin:
  /uploadmultipart:
    description: Uploads a file and saves it to a directory configured on the server
    post:
      is: [secured, upload-handler]
      description: |
          Uploads a file and saves it to a directory configured on the server
      body:
        multipart/form-data:
          formParameters:
            file:
              description: The file to be uploaded
              required: true
              type: file
      responses:
        200:
          description: "Saved"
          headers:
            Location:
              description: URI to the created <<resourcePathName|!singularize>> item
        400:
          description: "Bad request"
          body:
            text/plain:
              example: |
                "unable to add <<resourcePathName|!singularize>>"
        500:
          description: "Internal server error, e.g. due to misconfiguration"
          body:
            text/plain:
              example: "Internal server error, contact administrator"
  /importSQL:
    description: Uploads a file and saves it to a directory configured on the server
    post:
      is: [secured]
      description: |
          Uploads a file and saves it to a directory configured on the server
      body:
        application/octet-stream:
      responses:
        200:
          description: "Saved"
          headers:
            Location:
              description: URI to the created <<resourcePathName|!singularize>> item
        400:
          description: "Bad request"
          body:
            text/plain:
              example: |
                "unable to add <<resourcePathName|!singularize>>"
        500:
          description: "Internal server error, e.g. due to misconfiguration"
          body:
            text/plain:
              example: "Internal server error, contact administrator"
  /loglevel:
    put:
      description: Set logging level for all loggers in the JVM or just for a specific package / class
      is: [secured, log-level]
      responses:
        200:
          description: "Returns packages with log level of the updated packages"
          body:
            application/json:
              example: "{\"package\" : \"log level\" , \"package2\" : \"log level\"}"
        500:
          description: "Internal server error, e.g. due to misconfiguration"
          body:
            text/plain:
              example: "Internal server error, contact administrator"
    get:
      description: Get the logging level for all loggers in the JVM
      is: [secured]
      responses:
        200:
          description: "Returns packages with log level"
          body:
            application/json:
              example: "{\"package\" : \"log level\" , \"package2\" : \"log level\"}"
        500:
          description: "Internal server error, e.g. due to misconfiguration"
          body:
            text/plain:
              example: "Internal server error, contact administrator"
  /jstack:
    put:
      description: dumps jstacks every N seconds to a jstack file to find potential bottlenecks. Looking at this |
        file you can see if there are functions blocking for too long
      is: [secured]
      responses:
        204:
          description: "Jstack request successful"
        500:
          description: "Internal server error"
          body:
            text/plain:
              example: "Internal server error, contact administrator"
    get:
      description: Get stack trace
      is: [secured]
      responses:
        200:
          description: "Returns the stack trace of all threads in the JVM"
          body:
            text/html:
              example: "Text....."
        500:
          description: "Internal server error"
          body:
            text/plain:
              example: "Internal server error, contact administrator"
  /memory:
    get:
      description: Get JVM memory info
      is: [secured, history]
      responses:
        200:
          description: "Returns JVM memory info"
          body:
            text/html:
              example: "Text....."
        500:
          description: "Internal server error"
          body:
            text/plain:
              example: "Internal server error, contact administrator"
  /postgres_maintenance:
    post:
      description: run one of the following maintenance jobs on the Postgres DB. |
        analyze, vacuum, vacuum analyze, vacuum verbose
      is: [secured]
      queryParameters:
        table:
          description: Table name to run command on
          required: true
        command:
          description: |
            The command to run
          enum: [ANALYZE, VACUUM, VACUUM_ANALYZE, VACUUM_VERBOSE]
          default: ANALYZE
          required: false
      responses:
        201:
          description: "Command requested successful"
          body:
            application/json:
        500:
          description: "Internal server error"
          body:
            text/plain:
              example: "Internal server error, contact administrator"
  /postgres_active_sessions:
    get:
      description: Get active PostgreSQL sessions
      is: [secured, dbname]
      responses:
        200:
          description: |
            Returns active sessions with the following information. |
              process ID of the currently connected user to the database. |
              name of the database to which the user is currently connected. |
              the full text of the SQL query that is being executed by the client. |
              etc...
          body:
            application/json:
        500:
          description: "Internal server error"
          body:
            text/plain:
              example: "Internal server error, contact administrator"
  /postgres_load:
    get:
      description: Get load information on PostgreSQL
      is: [secured, dbname]
      responses:
        200:
          description: |
            Returns load with the following information. |
              Number of active connections. |
              Number of rollbacks and commits issued. |
              Number of blocks read ( block = an 8kb segment information the file storing the table. ). |
              Number of buffer hits (cache) |
              Note that the function calls SELECT pg_stat_reset(); to clear stats, waits 10 seconds, and |
              then returns with the info collected during those 10 seconds
          body:
            application/json:
        500:
          description: "Internal server error"
          body:
            text/plain:
              example: "Internal server error, contact administrator"
  /postgres_table_access_stats:
    get:
      description: Get access stats on the PostgreSQL tables
      is: [secured]
      responses:
        200:
          description: |
            Returns info about how the tables are being accessed either sequential or index scans
          body:
            application/json:
        500:
          description: "Internal server error"
          body:
            text/plain:
              example: "Internal server error, contact administrator"
  /postgres_table_size:
    get:
      description: amount of disk usage for a specific database and its associated tables and indexes.
      is: [secured, dbname]
      responses:
        200:
          description: |
            Returns info for every table in format - table | table size | index size
          body:
            application/json:
        500:
          description: "Internal server error"
          body:
            text/plain:
              example: "Internal server error, contact administrator"
  /table_index_usage:
    get:
      description: table index usage rates per table
      is: [secured]
      responses:
        200:
          description: |
            Returns index usage info for every table
          body:
            application/json:
        500:
          description: "Internal server error"
          body:
            text/plain:
              example: "Internal server error, contact administrator"
  /cache_hit_rates:
    get:
      description: cache hit rates
      is: [secured]
      responses:
        200:
          description: |
            cache hit rates
          body:
            application/json:
        500:
          description: "Internal server error"
          body:
            text/plain:
              example: "Internal server error, contact administrator"
  /slow_queries:
    get:
      description: Check for currently running queries that have been executing longer than X seconds
      is: [secured, slow-query]
      responses:
        200:
          description: |
            List of slow queries
          body:
            application/json:
        500:
          description: "Internal server error"
          body:
            text/plain:
              example: "Internal server error, contact administrator"
  /total_db_size:
    get:
      description: Returns the size of the entire database for example, db_size = 711 MB
      is: [secured, dbname]
      responses:
        200:
          description: |
            Returns the size of the entire database
          body:
            application/json:
              example: "{\"db_size\" : \"711 MB\"}"
        500:
          description: "Internal server error"
          body:
            text/plain:
              example: "Internal server error, contact administrator"
  /db_cache_summary:
    get:
      description: Returns a list of the tables / indexes in the shared_buffers (cache) and their size. This is |
        an expensive API from a DB resource perspective and should not run frequently (every few hours should suffice)
      is: [secured]
      responses:
        200:
          description: |
            Returns a list of the tables / indexes in the shared_buffers
          body:
            application/json:
        500:
          description: "Internal server error"
          body:
            text/plain:
              example: "Internal server error, contact administrator"
  /list_locking_queries:
    get:
      description: Returns a list of queries in transactions that are blocking other queries. The result includes
        the blocking query, the query being blocked, and their pids
      is: [secured, dbname]
      responses:
        200:
          body:
            application/json:
        500:
          description: "Internal server error"
          body:
            text/plain:
              example: "Internal server error, contact administrator"
  /kill_query:
    delete:
      description: Stops a query from running based on its PID using the pg_terminate_backend command
      is: [secured, pid]
      responses:
        204:
          description: "Query terminated successfully"
        404:
          description: "PID not found"
          body:
            text/plain:
              example: |
                "<<resourcePathName|!singularize>> not found"
        500:
          description: "Internal server error"
          body:
            text/plain:
              example: "Internal server error, contact administrator"
  /postgres_drop_indexes:
    put:
      description: Drop indexes, useful before a large batch load, tenantid will be used to select the correct schema to use
      is: [secured]
      responses:
        204:
          description: "Indexes dropped"
        400:
          description: "Bad request"
          body:
            text/plain:
              example: |
                "No indexes to delete"
        500:
          description: "Internal server error, e.g. due to misconfiguration"
          body:
            text/plain:
              example: "Internal server error, contact administrator"
  /postgres_create_indexes:
    put:
      description: Create indexes, useful if prior to a large batch load the indexes were dropped, tenantid will be used to select the correct schema to use
      is: [secured]
      responses:
        204:
          description: "Indexes created"
        400:
          description: "Bad request"
          body:
            text/plain:
              example: |
                "example message"
        500:
          description: "Internal server error, e.g. due to misconfiguration"
          body:
            text/plain:
              example: "Internal server error, contact administrator"
  /set_AES_key:
    post:
      description: Sets the AES secret key that the postgres config file password was encrypted with. The key will only be checked |
        when the configuration file is read in and the DB connection is created
      is: [secured, secret-key]
      responses:
        204:
          description: "Secret key set"
  /get_password:
    post:
      description: The API takes the secret key passed in and the x-okapi-tenant header and returns the DB password generated for |
        that tenant's schema
      is: [secured, secret-key]
      responses:
        200:
          description: "returned password"
          body:
            text/plain:
              example: "as35235+df+df/ggr"
        400:
          description: "Bad request"
          body:
            text/plain:
              example: |
                "unable to add <<resourcePathName|!singularize>>"
        500:
          description: "Internal server error"
          body:
            text/plain:
              example: "Internal server error, contact administrator"
  /health:
    get:
      description: The API returns 200 if service is up and responding. Should be overridden |
        by individual services that want to actually run some business logic to determine health.
      is: [secured]
      responses:
        200:
          body:
            "any/any":
        400:
          description: "Bad request"
          body:
            text/plain:
              example: |
                ""
        500:
          description: "Internal server error"
          body:
            text/plain:
              example: "Internal server error, contact administrator"
  /module_stats:
    get:
      description: The API returns service specific statistics. Should be overridden |
        by individual services that run a set of business logic functions / gather stats and return.
      is: [secured]
      responses:
        200:
          description: "returned status"
          body:
            text/plain:
        400:
          description: "Bad request"
          body:
            text/plain:
              example: |
                ""
        500:
          description: "Internal server error"
          body:
            text/plain:
              example: "Internal server error, contact administrator"


Fix api.raml

Fix api.raml

#%RAML 0.8
---
title: Order Management API
baseUri: https://api.bring.com/po/api/v1

documentation:
- title: Introduction
  content: |
    There are different customer types in Order Management and depending on what kind of customer you are setts the usage pattern for Order Management API.

    This is a step-by-step guide on how to use the API.

    A typical usage pattern for an Warehousing cutomer type is to create an order in Order Management that will go to the correct warehouse for picking, packing and sending. Then follow up with creating a packing list from the warehouse with transport information. All steps can be followed in Order Management.

    An other usage pattern is for an purchase order customer that create purchase orders and lets all of his suppliers get the order from Order Management. The suppliers will check whether a customer is a Order Management customer. Follow up with creating a packing list with transport information. All events and status changes will go back to purchase order owner.

    Order Management has several interfaces (SOAP and XML/JSON). Choose the option that fits your needs best (see table below). The SOAP interface is the core interface with complete functionality.

    Please note that this API currently doesn't support json on all of its methods yet. Look in the example section to see which are supported.

    ## SOAP

    ### Versioning

    Order Management makes an effort to always be backwards compatible regarding data format for requests and responses of the Web Service. To achieve this, a SchemaVersion element is used in the request, indicating which version the client is on and what data-format the client expects in the result.

    We make an effort not to return new elements in the response when an old schema version is specified. When changes in the schema are made, the SchemaVersion is incremented by one. The new schema is used at the same endpoint URL as before and uses the same namespace for its XML elements. A TraceMessage element (info message) in the response is added to inform the client that its schema should be updated. Old schema versions might in the future be unsupported.

    Regarding the XML API (not Web Services), an XML Schema is not used at all. Therefore, clients of the XML API are expected to handle new elements that appear. Nevertheless, the response will be backwards compatible in the sense that elements are not renamed or deleted.

    ### WSDL

    [https://api.bring.com/po/api/ws/purchaseorder-v1.wsdl](https://api.bring.com/po/api/ws/purchaseorder-v1.wsdl)

    ## Error handling

    When using the Order Management, errors or service unavailability can occur, although we do our utmost to prevent any downtime. Thus it is important to use timeouts and other error handling techniques when making requests to the service.

    How you handle errors depends on the nature of your application, but one strategy for handling such situations is by providing a failover if the shipping guide responds with an error or does not respond at all (timeout).

    See [the list of error codes](#list-error-codes) for hints on how to implement error handling.

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

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

    Those headers must be set for all endpoints documented below.

/purchaseorderCustomer/{customerId}:
  displayName: Check if customer is valid for order management
  description: |
      Check if a given customer number is an valid Order Management customer.
  get:
    description:
     Check if customer is valid for order management
    responses:
      200:
        displayName: Success
        description: |
          Returns `true` if given customer is a valid for order management.
        body:
          application/xml:
            example: !include examples/verify_customer.xml
          application/json:
            example: !include examples/verify_customer.json

/order/{customerId}/{orderId}:
  displayName: List order information
  description: |
      Get all information on a given order.
  get:
    description: List order information
    responses:
      200:
        displayName: Success
        description: |
          Complete order information including order items.
        body:
          application/xml:
            example: !include examples/retrieve_purchaseorder.xml

/order:
  displayName: Send an order
  description: |
      Send an order to Order Management. There are different types of order supported in Order Management.

       - Order / SalesOrder (as an pickorder for Warehousing)
            - Order Management act as an order repository.
            - When Warehousing functionality Order Management sends it to Warhousing system for picking and delivery.
       - PurchaseOrder
            - Order Management can give your suppliers access to purchase orders so they can get info, confirm, accept and deliver on them.
            - When Warehousing functionality Order Management sends it to Warhousing system for receiving notice.

  post:
    description: Send an order
    queryParameters:
      CreateOrderRequest messageFunction:
          description: Type of order. Order, OrderResponse, SalesOrder, NotifyTransport, PurchaseOrder, ArticleBalance, DespatchAdvice, ReceivingAdvice, PackageList.
          type: string
          required: true
          example: Order
      MessageSender partyId:
          description: Customer Number which Bring has provided. It cannot be demo customer number.
          type: string
          required: true
          example: 10000000000
      MessageRecipient partyId:
          description: Receiving Bring system. Constant value.
          type: string
          required: true
          example: NO98466118506
      MessageDate:
          description: The date on which message is sent.
          type: dateTime
          required: true
          example: 22.01.2017 11:36:22
      OrderSet updateIndicator:
          description: Type of order data. Original, Update or Deletion
          type: string
          required: true
          example: Original
      Order orderId:
          description: Ordernumber.
          type: dateTime
          required: true
          example: 101010
      Reference:
          description: Set of references.
          type: sequence
          required: false
      Reference referenceType:
          description: Type of reference coded. https://www.stylusstudio.com/edifact/D04A/1153.htm
          type: String
          required: true
          example: CMR
      Reference ReferenceNo:
          description: Reference.
          type: String
          required: true
          example: 10003455TT
      DateAndTimes subClass DocumentDate:
          description: The date on which order is booked.
          type: dateTime
          required: true
          example: 22.01.2017 11:36:22
      TransportService BasicServiceCode:
          description: Transport product for shipment to customer.
          type: String
          required: true
          example: SERVICEPAKKE
      Party/subClass OrderingParty:
          description: Details of sender. Must have Name, Street, City, CountryCode.
          required: true
      Party/subClass DeliveryParty:
          description: Details of recipient. Must have Name, Street, City, CountryCode.
          required: true
      Party/subClass Supplier:
          description: Details of supplier. Must have Name, Street, City, CountryCode if used.
          required: false
      OrderLineSet:
          description: Set of order items.
          type: sequence
          required: true
      OrderItem articleLineId:
          description: Line id for this order line.
          type: integer
          required: true
          example: 10
      ArticleId:
          description: Article number or id.
          type: string
          required: false
          example: 123-4000
      ArticleQuantity unitCode:
          description: Unit code for quantity ordered.
          type: string
          required: true
          example: STK
      ArticleQuantity:
          description: Quantity ordered.
          type: float
          required: true
          example: 2.0
      Description:
          description: Article description / name.
          type: string
          required: true
          example: Spear parts
      Description:
          description: Article description / name.
          type: string
          required: true
          example: Spear parts
      DateAndTimes subClass DeliveryDateRequested:
          description: The date on which order is requested delivered.
          type: dateTime
          required: true
          example: 22.01.2017 11:36:22

    body:
        application/xml:
          example: !include examples/create_order.xml
        application/json:
          example: !include examples/create_order.json
    responses:
      200:
        displayName: Success
        description: |
          Successfully created a order.

/items/{customerId}/{orderId}:
  displayName: List order items
  description: |
      List all item lines on an order.
  get:
    description: List order items
    responses:
      200:
        displayName: Success
        description: |
          List of order items.
        body:
          application/xml:
            example: !include examples/retrieve_orderitems.xml
          application/json:
            example: !include examples/retrieve_orderitems.json

/packaginglist/{customerId}/{orderId}:
  displayName: List packaging list for order
  description: |
      List all packaging list information for this order. One order can have multiple packaging lists.
  get:
    description: List packaging list for order
    responses:
      200:
        displayName: Success
        description: |
          List of packaging list for given order, if any.
        body:
          application/xml:
            example: !include examples/retrieve_packinglist.xml
          application/json:
            example: !include examples/retrieve_packinglist.json

/packaginglist:
  displayName: Add packaging list
  description: |
      When an order have been picked and sent, add packing list on order with transport information.
  post:
    description: Add packaging list
    body:
      application/xml:
        example: !include examples/create_packaging_list.xml
    responses:
      200:
        displayName: Success
        description: |
          Successfully added packaging list.

/senderStatus/{customerId}/{orderId}:
  displayName: Get status for order
  description: |
      Check status for an order. Open when not fully delivered or locked when fully delivered.
  get:
    description: Get status for order
    responses:
      200:
        displayName: Success
        description: Open or Locked.
        body:
          application/xml:
            example: !include examples/check_status.xml
          application/json:
            example: !include examples/check_status.json

/event:
  displayName: Create TMSEvents
  description: |
      Create tracking events on shipments associated with orders in Order Management.
  post:
    description: Create TMSEvents
    body:
      application/xml:
        example: !include examples/create_events.xml
    responses:
      200:
        displayName: Success
        description: |
          Successfully created a new resource

/articlebalance:
  displayName: Create or update article balance list
  post:
    description: Create or update article balance list
    body:
      application/xml:
        example: !include examples/create_articlebalance.xml
    responses:
      200:
        displayName: Success
        description: |
          Successfully created balance list

/articlebalance/{customerId}:
  displayName: Get stock balance and info for all articles
  get:
    description: Get stock balance and info for all articles
    responses:
      200:
        displayName: Success
        description: |
        body:
          application/xml:
            example: !include examples/retrieve_articlebalance_all.xml
          application/json:
            example: !include examples/retrieve_articlebalance_all.json

/articlebalance/{customerId}/{articleNo}:
  displayName: Get stock balance and info for one article
  get:
    description: Get stock balance and info for one article
    responses:
      200:
        displayName: Success
        description: |
        body:
          application/xml:
            example: !include examples/retrieve_articlebalance_one.xml
          application/json:
            example: !include examples/retrieve_articlebalance_one.json

/articlebalance/info/{customerId}/{articleSearchString}:
  displayName: Get stock balance and info for all articles matching search string
  get:
    description: Get stock balance and info for all articles matching search string
    responses:
      200:
        displayName: Success
        description: |
        body:
          application/xml:
            example: !include examples/retrieve_articlebalance_search.xml
          application/json:
            example: !include examples/retrieve_articlebalance_search.json

/errorCodes:
  displayName: List error codes
  get:
    description: List error codes
    responses:
      200:
        displayName: Success
        description: |
          Dynamic list of error codes used in the solution.
        body:
          application/xml:
            example: !include examples/error_codes.xml
          application/json:
            example: !include examples/error_codes.json

#%RAML 0.8
---
title: Order Management API
baseUri: https://api.bring.com/po/api/v1

documentation:
- title: Introduction
  content: |
    There are different customer types in Order Management and depending on what kind of customer you are setts the usage pattern for Order Management API.

    This is a step-by-step guide on how to use the API.

    A typical usage pattern for an Warehousing cutomer type is to create an order in Order Management that will go to the correct warehouse for picking, packing and sending. Then follow up with creating a packing list from the warehouse with transport information. All steps can be followed in Order Management.

    An other usage pattern is for an purchase order customer that create purchase orders and lets all of his suppliers get the order from Order Management. The suppliers will check whether a customer is a Order Management customer. Follow up with creating a packing list with transport information. All events and status changes will go back to purchase order owner.

    Order Management has several interfaces (SOAP and XML/JSON). Choose the option that fits your needs best (see table below). The SOAP interface is the core interface with complete functionality.

    Please note that this API currently doesn't support json on all of its methods yet. Look in the example section to see which are supported.

    ## SOAP

    ### Versioning

    Order Management makes an effort to always be backwards compatible regarding data format for requests and responses of the Web Service. To achieve this, a SchemaVersion element is used in the request, indicating which version the client is on and what data-format the client expects in the result.

    We make an effort not to return new elements in the response when an old schema version is specified. When changes in the schema are made, the SchemaVersion is incremented by one. The new schema is used at the same endpoint URL as before and uses the same namespace for its XML elements. A TraceMessage element (info message) in the response is added to inform the client that its schema should be updated. Old schema versions might in the future be unsupported.

    Regarding the XML API (not Web Services), an XML Schema is not used at all. Therefore, clients of the XML API are expected to handle new elements that appear. Nevertheless, the response will be backwards compatible in the sense that elements are not renamed or deleted.

    ### WSDL

    [https://api.bring.com/po/api/ws/purchaseorder-v1.wsdl](https://api.bring.com/po/api/ws/purchaseorder-v1.wsdl)

    ## Error handling

    When using the Order Management, errors or service unavailability can occur, although we do our utmost to prevent any downtime. Thus it is important to use timeouts and other error handling techniques when making requests to the service.

    How you handle errors depends on the nature of your application, but one strategy for handling such situations is by providing a failover if the shipping guide responds with an error or does not respond at all (timeout).

    See [the list of error codes](#list-error-codes) for hints on how to implement error handling.

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

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

    Those headers must be set for all endpoints documented below.

/purchaseorderCustomer/{customerId}:
  displayName: Check if customer is valid for order management
  description: |
      Check if a given customer number is an valid Order Management customer.
  get:
    description:
     Check if customer is valid for order management
    responses:
      200:
        displayName: Success
        description: |
          Returns `true` if given customer is a valid for order management.
        body:
          application/xml:
            example: !include examples/verify_customer.xml
          application/json:
            example: !include examples/verify_customer.json

/order/{customerId}/{orderId}:
  displayName: List order information
  description: |
      Get all information on a given order.
  get:
    description: List order information
    responses:
      200:
        displayName: Success
        description: |
          Complete order information including order items.
        body:
          application/xml:
            example: !include examples/retrieve_purchaseorder.xml

/order:
  displayName: Send an order
  description: |
      Send an order to Order Management. There are different types of order supported in Order Management.

       - Order / SalesOrder (as an pickorder for Warehousing)
            - Order Management act as an order repository.
            - When Warehousing functionality Order Management sends it to Warhousing system for picking and delivery.
       - PurchaseOrder
            - Order Management can give your suppliers access to purchase orders so they can get info, confirm, accept and deliver on them.
            - When Warehousing functionality Order Management sends it to Warhousing system for receiving notice.

  post:
    description: Send an order
    queryParameters:
      CreateOrderRequest messageFunction:
          description: Type of order. Order, OrderResponse, SalesOrder, NotifyTransport, PurchaseOrder, ArticleBalance, DespatchAdvice, ReceivingAdvice, PackageList.
          type: string
          required: true
          example: Order
      MessageSender partyId:
          description: Customer Number which Bring has provided. It cannot be demo customer number.
          type: string
          required: true
          example: 10000000000
      MessageRecipient partyId:
          description: Receiving Bring system. Constant value.
          type: string
          required: true
          example: NO98466118506
      MessageDate:
          description: The date on which message is sent.
          type: dateTime
          required: true
          example: 22.01.2017 11:36:22
      OrderSet updateIndicator:
          description: Type of order data. Original, Update or Deletion
          type: string
          required: true
          example: Original
      Order orderId:
          description: Ordernumber.
          type: dateTime
          required: true
          example: 101010
      Reference:
          description: Set of references.
          type: sequence
          required: false
      Reference referenceType:
          description: Type of reference coded. https://www.stylusstudio.com/edifact/D04A/1153.htm
          type: String
          required: true
          example: CMR
      Reference ReferenceNo:
          description: Reference.
          type: String
          required: true
          example: 10003455TT
      DateAndTimes subClass DocumentDate:
          description: The date on which order is booked.
          type: dateTime
          required: true
          example: 22.01.2017 11:36:22
      TransportService BasicServiceCode
          description: Transport product for shipment to customer.
          type: String
          required: true
          example: SERVICEPAKKE
      Party/subClass OrderingParty:
          description: Details of sender. Must have Name, Street, City, CountryCode.
          required: true
      Party/subClass DeliveryParty:
          description: Details of recipient. Must have Name, Street, City, CountryCode.
          required: true
      Party/subClass Supplier:
          description: Details of supplier. Must have Name, Street, City, CountryCode if used.
          required: false
      OrderLineSet:
          description: Set of order items.
          type: sequence
          required: true
      OrderItem articleLineId:
          description: Line id for this order line.
          type: integer
          required: true
          example: 10
      ArticleId:
          description: Article number or id.
          type: string
          required: false
          example: 123-4000
      ArticleQuantity unitCode:
          description: Unit code for quantity ordered.
          type: string
          required: true
          example: STK
      ArticleQuantity:
          description: Quantity ordered.
          type: float
          required: true
          example: 2.0
      Description:
          description: Article description / name.
          type: string
          required: true
          example: Spear parts
      Description:
          description: Article description / name.
          type: string
          required: true
          example: Spear parts
      DateAndTimes subClass DeliveryDateRequested:
          description: The date on which order is requested delivered.
          type: dateTime
          required: true
          example: 22.01.2017 11:36:22

    body:
        application/xml:
          example: !include examples/create_order.xml
        application/json:
          example: !include examples/create_order.json
    responses:
      200:
        displayName: Success
        description: |
          Successfully created a order.

/items/{customerId}/{orderId}:
  displayName: List order items
  description: |
      List all item lines on an order.
  get:
    description: List order items
    responses:
      200:
        displayName: Success
        description: |
          List of order items.
        body:
          application/xml:
            example: !include examples/retrieve_orderitems.xml
          application/json:
            example: !include examples/retrieve_orderitems.json

/packaginglist/{customerId}/{orderId}:
  displayName: List packaging list for order
  description: |
      List all packaging list information for this order. One order can have multiple packaging lists.
  get:
    description: List packaging list for order
    responses:
      200:
        displayName: Success
        description: |
          List of packaging list for given order, if any.
        body:
          application/xml:
            example: !include examples/retrieve_packinglist.xml
          application/json:
            example: !include examples/retrieve_packinglist.json

/packaginglist:
  displayName: Add packaging list
  description: |
      When an order have been picked and sent, add packing list on order with transport information.
  post:
    description: Add packaging list
    body:
      application/xml:
        example: !include examples/create_packaging_list.xml
    responses:
      200:
        displayName: Success
        description: |
          Successfully added packaging list.

/senderStatus/{customerId}/{orderId}:
  displayName: Get status for order
  description: |
      Check status for an order. Open when not fully delivered or locked when fully delivered.
  get:
    description: Get status for order
    responses:
      200:
        displayName: Success
        description: Open or Locked.
        body:
          application/xml:
            example: !include examples/check_status.xml
          application/json:
            example: !include examples/check_status.json

/event:
  displayName: Create TMSEvents
  description: |
      Create tracking events on shipments associated with orders in Order Management.
  post:
    description: Create TMSEvents
    body:
      application/xml:
        example: !include examples/create_events.xml
    responses:
      200:
        displayName: Success
        description: |
          Successfully created a new resource

/articlebalance:
  displayName: Create or update article balance list
  post:
    description: Create or update article balance list
    body:
      application/xml:
        example: !include examples/create_articlebalance.xml
    responses:
      200:
        displayName: Success
        description: |
          Successfully created balance list

/articlebalance/{customerId}:
  displayName: Get stock balance and info for all articles
  get:
    description: Get stock balance and info for all articles
    responses:
      200:
        displayName: Success
        description: |
        body:
          application/xml:
            example: !include examples/retrieve_articlebalance_all.xml
          application/json:
            example: !include examples/retrieve_articlebalance_all.json

/articlebalance/{customerId}/{articleNo}:
  displayName: Get stock balance and info for one article
  get:
    description: Get stock balance and info for one article
    responses:
      200:
        displayName: Success
        description: |
        body:
          application/xml:
            example: !include examples/retrieve_articlebalance_one.xml
          application/json:
            example: !include examples/retrieve_articlebalance_one.json

/articlebalance/info/{customerId}/{articleSearchString}:
  displayName: Get stock balance and info for all articles matching search string
  get:
    description: Get stock balance and info for all articles matching search string
    responses:
      200:
        displayName: Success
        description: |
        body:
          application/xml:
            example: !include examples/retrieve_articlebalance_search.xml
          application/json:
            example: !include examples/retrieve_articlebalance_search.json

/errorCodes:
  displayName: List error codes
  get:
    description: List error codes
    responses:
      200:
        displayName: Success
        description: |
          Dynamic list of error codes used in the solution.
        body:
          application/xml:
            example: !include examples/error_codes.xml
          application/json:
            example: !include examples/error_codes.json


updated paged trait doc;

updated paged trait doc;

description: Pagging feature for method that returns collection.
queryParameters:
  page:
    description: Page number
    type: number
    example: 1
  size:
    description: Page size
    type: number
    example: 10

description: Pagging feature for method that returns list of items.
queryParameters:
  page:
    description: Page number
    type: number
    example: 1
  size:
    description: Page size
    type: number
    example: 10


Update description for validation

Update description for validation

#%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
    description: An order to place in Mybring.
    properties:
      customerNumber:
        type: string
        description: API customer number for which to place the order.
      senderName:
        type: string
        description: Sender's name.
        example: Min Bedrift
      senderEmail:
        required: false
        type: string
        pattern: ".+@.+"
        description: Sender's email address. Defaults to the user's email address.
      postalCode:
        type: string
        description: Sender's postal code. Must be a valid Norwegian postal code.
      streetAddress:
        type: string
        description: Sender's street address.
      reference:
        required: true
        description: A reference for the shipment (all packages).
      packages:
        minItems: 1
        type: Package[]
        description: The packages to send in this shipment.
  Package:
    type: object
    description: A single package in a shipment.
    properties:
      priority:
        enum: [ A, B ]
        description: Delivery speed (A-post or B-post).
      rfid:
        type: boolean
        description: Whether to activate [tracking with RFID](#tracking-with-rfid) for the package.
      weight:
        maximum: 2000
        type: integer
        description: Weight in grams.
      recipientName:
        type: string
        description: Recipient name.
      postalCode:
        type: string
        description: A valid Norwegian postal code.
      streetAddress:
        type: string
        description: Recipient's street address.
      phoneNumber:
        type: string
        pattern: "\\+[0-9 ]+"
        description: Recipient's phone number, including country code.
        example: "+4700000000"
      email:
        type: string
        pattern: ".+@.+"
        description: Recipient's email address.
  SuccessfulOrder:
    (hideRequired): true
    displayName: Successful Order
    description: A successfully placed order that contains links to labels and waybill.
    properties:
      id:
        type: number
        description: The ID of the order that was placed.
      customerNumber:
        type: string
        description: The API customer number for which the order was placed.
      customerName:
        type: string
        description: The name of the customer for which the order was placed.
      customerOrganizationNumber:
        type: string
        description: The organization number of the customer for which the order was placed.
      senderName:
        type: string
        description: Sender's name.
      streetAddress:
        type: string
        description: Sender's street address.
      postalCode:
        type: string
        description: Sender's postal code.
      postalPlace:
        type: string
        description: The city/place for the postal code.
      email:
        type: string
        pattern: ".+@.+"
        description: Sender's email address that for the order that was placed.
      reference:
        type: string
        description: A reference for the shipment (all packages)
      labelUri:
        type: string
        description: URL to PDF label 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
    description: A single package in a successfully ordered shipment.
    properties:
      priority:
        enum: [ A, B ]
        description: Delivery speed (A-post or B-post).
      rfid:
        type: boolean
        description: Whether to [tracking for the package](#tracking-with-rfid) was activated.
      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
    description: A valid order that can be placed.
    properties:
      customerNumber:
        type: string
        description: The API customer number for the validated order.
      customerName:
        type: string
        description: The name of the customer for the validated order.
      customerOrganizationNumber:
        type: string
        description: The organization number of the customer for the validated order.
      senderName:
        type: string
        description: The sender's name.
      streetAddress:
        type: string
        description: The sender's street address.
      postalCode:
        type: string
        description: The sender's postal code.
      postalPlace:
        type: string
        description: The city/place for the postal code.
      email:
        type: string
        description: The sender's email address.
      reference:
        type: string
        description: A reference for the shipment (all packages).
      priceWithoutVat:
        type: number
        description: Calculated price without VAT (MVA).
      priceWithVat:
        type: number
        description: Calulated price with VAT (MVA).
      vat:
        type: number
        description: Calculated VAT (MVA).
      currency:
        type: string
        description: The price's currency.
      orderTime:
        type: datetime
        description: Timestamp for when the order was validated.
      packages:
        minItems: 1
        description: Packages in this validated shipment.
        type: ValidatedPackage[]
  ValidatedPackage:
    (hideRequired): true
    displayName: Validated Package
    description: A single, valid package in a valid shipment.
    properties:
      priority:
        enum: [ A, B ]
        description: Delivery speed (A-post or B-post).
      rfid:
        type: boolean
        description: Whether to [tracking with RFID](#tracking-with-rfid) was activated for the package.
      recipientName:
        type: string
        description: Recipient's name.
      streetAddress:
        type: string
        description: Recipient's email address.
      postalCode:
        type: string
        description: Recipient's postal code.
      postalPlace:
        type: string
        description: The city/place for the postal code.
      phoneNumber:
        type: string
        description: Recipient's phone number.
      email:
        type: string
        description: Recipient's email address.
      weight:
        type: integer
        description: Package weight in grams.
      agreementNumber:
        type: boolean
        description: Whether the customer has an agreement price for this package.
  OrderRequest:
    (hideInDocumentation): true
    type: object
    properties:
      data:
        type: object
        description: JSON-API data object.
        properties:
          type:
            type: string
            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:
        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 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
            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: Validation error
        body:
          application/json:
            type: ErrorResponse
            examples:
              invalid_order:
                displayName: Invalid order
                value: !include examples/422.json
      500:
        description: If we have an error in our backend, we'll return a 500 error.
        body:
          application/json:
            type: ErrorResponse
            examples:
              server_error:
                displayName: Server error
                value: !include examples/500.json

/{orderId}:
  displayName: Fetch order
  uriParameters:
    orderId:
      type: string
      description: Id from when placing an order.
  get:
    description: Fetch previously ordered shipment
    headers:
      Accept:
        description: Specify response format (application/json)
        required: true
        enum: [ application/json ]
    responses:
      200:
        description: Success!!!!
        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: 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
    description: An order to place in Mybring.
    properties:
      customerNumber:
        type: string
        description: API customer number for which to place the order.
      senderName:
        type: string
        description: Sender's name.
        example: Min Bedrift
      senderEmail:
        required: false
        type: string
        pattern: ".+@.+"
        description: Sender's email address. Defaults to the user's email address.
      postalCode:
        type: string
        description: Sender's postal code. Must be a valid Norwegian postal code.
      streetAddress:
        type: string
        description: Sender's street address.
      reference:
        required: true
        description: A reference for the shipment (all packages).
      packages:
        minItems: 1
        type: Package[]
        description: The packages to send in this shipment.
  Package:
    type: object
    description: A single package in a shipment.
    properties:
      priority:
        enum: [ A, B ]
        description: Delivery speed (A-post or B-post).
      rfid:
        type: boolean
        description: Whether to activate [tracking with RFID](#tracking-with-rfid) for the package.
      weight:
        maximum: 2000
        type: integer
        description: Weight in grams.
      recipientName:
        type: string
        description: Recipient name.
      postalCode:
        type: string
        description: A valid Norwegian postal code.
      streetAddress:
        type: string
        description: Recipient's street address.
      phoneNumber:
        type: string
        pattern: "\\+[0-9 ]+"
        description: Recipient's phone number, including country code.
        example: "+4700000000"
      email:
        type: string
        pattern: ".+@.+"
        description: Recipient's email address.
  SuccessfulOrder:
    (hideRequired): true
    displayName: Successful Order
    description: A successfully placed order that contains links to labels and waybill.
    properties:
      id:
        type: number
        description: The ID of the order that was placed.
      customerNumber:
        type: string
        description: The API customer number for which the order was placed.
      customerName:
        type: string
        description: The name of the customer for which the order was placed.
      customerOrganizationNumber:
        type: string
        description: The organization number of the customer for which the order was placed.
      senderName:
        type: string
        description: Sender's name.
      streetAddress:
        type: string
        description: Sender's street address.
      postalCode:
        type: string
        description: Sender's postal code.
      postalPlace:
        type: string
        description: The city/place for the postal code.
      email:
        type: string
        pattern: ".+@.+"
        description: Sender's email address that for the order that was placed.
      reference:
        type: string
        description: A reference for the shipment (all packages)
      labelUri:
        type: string
        description: URL to PDF label 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
    description: A single package in a successfully ordered shipment.
    properties:
      priority:
        enum: [ A, B ]
        description: Delivery speed (A-post or B-post).
      rfid:
        type: boolean
        description: Whether to [tracking for the package](#tracking-with-rfid) was activated.
      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
    description: A valid order that can be placed.
    properties:
      customerNumber:
        type: string
        description: The API customer number for the validated order.
      customerName:
        type: string
        description: The name of the customer for the validated order.
      customerOrganizationNumber:
        type: string
        description: The organization number of the customer for the validated order.
      senderName:
        type: string
        description: The sender's name.
      streetAddress:
        type: string
        description: The sender's street address.
      postalCode:
        type: string
        description: The sender's postal code.
      postalPlace:
        type: string
        description: The city/place for the postal code.
      email:
        type: string
        description: The sender's email address.
      reference:
        type: string
        description: A reference for the shipment (all packages).
      priceWithoutVat:
        type: number
        description: Calculated price without VAT (MVA).
      priceWithVat:
        type: number
        description: Calulated price with VAT (MVA).
      vat:
        type: number
        description: Calculated VAT (MVA).
      currency:
        type: string
        description: The price's currency.
      orderTime:
        type: datetime
        description: Timestamp for when the order was validated.
      packages:
        minItems: 1
        description: Packages in this validated shipment.
        type: ValidatedPackage[]
  ValidatedPackage:
    (hideRequired): true
    displayName: Validated Package
    description: A single, valid package in a valid shipment.
    properties:
      priority:
        enum: [ A, B ]
        description: Delivery speed (A-post or B-post).
      rfid:
        type: boolean
        description: Whether to [tracking with RFID](#tracking-with-rfid) was activated for the package.
      recipientName:
        type: string
        description: Recipient's name.
      streetAddress:
        type: string
        description: Recipient's email address.
      postalCode:
        type: string
        description: Recipient's postal code.
      postalPlace:
        type: string
        description: The city/place for the postal code.
      phoneNumber:
        type: string
        description: Recipient's phone number.
      email:
        type: string
        description: Recipient's email address.
      weight:
        type: integer
        description: Package weight in grams.
      agreementNumber:
        type: boolean
        description: Whether the customer has an agreement price for this package.
  OrderRequest:
    (hideInDocumentation): true
    type: object
    properties:
      data:
        type: object
        description: JSON-API data object.
        properties:
          type:
            type: string
            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:
        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: 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
            examples:
              valid_order:
                displayName: Valid order
                value: !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
            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: Validation error
        body:
          application/json:
            type: ErrorResponse
            examples:
              invalid_order:
                displayName: Invalid order
                value: !include examples/422.json
      500:
        description: If we have an error in our backend, we'll return a 500 error.
        body:
          application/json:
            type: ErrorResponse
            examples:
              server_error:
                displayName: Server error
                value: !include examples/500.json

/{orderId}:
  displayName: Fetch order
  uriParameters:
    orderId:
      type: string
      description: Id from when placing an order.
  get:
    description: Fetch previously ordered shipment
    headers:
      Accept:
        description: Specify response format (application/json)
        required: true
        enum: [ application/json ]
    responses:
      200:
        description: Success!!!!
        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