Document numberofdeliverydates for SG V2 REST

#%RAML 1.0
---
title: Shipping Guide API 2.0
baseUri: https://api.bring.com/shippingguide

documentation:
- title: Introduction
  content: |
      The Shipping Guide API 2.0 (Fraktguiden) for provides you with different shipping alternatives for your shipments. If you request applicable shipping alternatives with all relevant details you will receive an object with the following data:

      - Prices
      - Estimated delivery times
      - GUI information

      The API returns the recommended way to present these shipping alternatives, meaning that the actual response can easily be shown in a web-shop checkout without any sorting or filtering and with human readable product texts.

      The Shipping Guide API 2.0 has both a REST and a SOAP interface. The REST interface only supports single consignments, while the SOAP interface can be used for multiple consignments.

      ### Why upgrade?

      * [Unified request and response model](/api/shipping-guide_2/#getting-started): Due to backward compatibility, existing SOAP API versions had too many ways of requesting to Shipping Guide could be always confusing for clients. This has been simplified in the new version with one unified way of requesting to Shipping Guide.
      * [Better error handling for both SOAP and REST](/api/shipping-guide_2/#handle-api-errors): The new version of API gives ability to handle error in a much simpler way.
      * [Ability to fetch agreement prices specific to a product on REST](/api/shipping-guide_2/#get-shipment-prices-and-estimated-delivery): Now you can specify multiple products and along with multiple customer number in a single REST request. [How?](/api/shipping-guide_2/#get-shipment-prices-and-estimated-delivery)
      *  Some improvements to our service offering are planned for 2018-19. More info about upcoming changes will follow to all our partners. Future services will be supported by this new API-version in addition to other improvements. Note that our old versions of API’s will not support future changes in our service offering.

      ### How to upgrade
      Now that Shipping Guide API 2.0 is out you might be wondering how to upgrade to it. The [Upgrade to version 2.0](/api/shipping-guide_2/upgrade-to-version-2) will help you on your way to version 2.0 of the Shipping Guide API.

- title: Getting started
  content: |
      This guide will walk you through getting shipment alternatives for your first consignment using Shipping Guide API. In this example we will be calling the SOAP interface with a HTTP client and query for the product `SERVICEPAKKE` and `PA_DOREN` for two packages.

      ### Before you start
      Before you can begin using the new API you'll have to do the following:

      * [Sign up for a Mybring account](https://www.mybring.com/signup/register/user) if you do not already have one. If you're already registered in Mybring, head to the [settings and API](https://www.mybring.com/useradmin/account/settings/) page to get your API key.
      * [Generate an API key](/api/#authentication) for your user

      ### 1. Get your API key from Mybring
      To make API requests you will need an API key.

      To do this click the button below, which sends you to your "Settings and API" page in Mybring profile administration. Scroll down to the "API key" section. Your generated API key which you will use to authenticate your requests can be found here.

      Get API key

      ### 2. Add authentication headers
      A description of the headers can be found in [Getting Started / Authentication](/api/#authentication).

      ### 3. Add additional headers
      Since we're using the SOAP (1.1) interface we'll have to add the following header:

      - `Content-type: text/xml`

      Most SOAP libraries will do this for you.

      ### 4. Add the body to the request
      In this request we will query prices and expected delivery time for the product `SERVICEPAKKE` for a single package being sent from the postal code 0015 to 5518 in Norway.

      ```
      <soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/"
                        xmlns:ns="http://www.bring.no/logistics/shippingguide/2.0">
          <soapenv:Header/>
          <soapenv:Body>
              <ns:ShippingGuideRequest xmlns:ns="http://www.bring.no/logistics/shippingguide/2.0">
                  <ns:Language>no</ns:Language>
                  <ns:WithPrice>true</ns:WithPrice>
                  <ns:WithExpectedDelivery>false</ns:WithExpectedDelivery>
                  <ns:WithGuiInformation>true</ns:WithGuiInformation>
                  <ns:NumberOfAlternativeDeliveryDates>0</ns:NumberOfAlternativeDeliveryDates>
                  <ns:EDI>true</ns:EDI>
                  <ns:PostingAtPostoffice>true</ns:PostingAtPostoffice>
                  <ns:Trace>true</ns:Trace>
                  <ns:Consignments>
                    <ns:Consignment id="101">
                        <ns:Products>
                            <ns:Product>
                                <ns:Id>SERVICEPAKKE</ns:Id>
                            </ns:Product>
                        </ns:Products>
                        <ns:FromCountryCode>NO</ns:FromCountryCode>
                        <ns:FromPostalCode>0015</ns:FromPostalCode>
                        <ns:ToCountryCode>NO</ns:ToCountryCode>
                        <ns:ToPostalCode>5518</ns:ToPostalCode>
                        <ns:ShippingDate>
                            <ns:Year>2016</ns:Year>
                            <ns:Month>10</ns:Month>
                            <ns:Day>10</ns:Day>
                            <ns:Hour>10</ns:Hour>
                            <ns:Minute>0</ns:Minute>
                        </ns:ShippingDate>
                        <ns:AdditionalServices>
                            <ns:AdditionalService>
                                <ns:Id>EVARSLING</ns:Id>
                            </ns:AdditionalService>
                            <ns:AdditionalService>
                                <ns:Id>POSTOPPKRAV</ns:Id>
                            </ns:AdditionalService>
                            <ns:AdditionalService>
                                <ns:Id>SOSIAL_KONTROLL</ns:Id>
                            </ns:AdditionalService>
                        </ns:AdditionalServices>
                        <ns:Packages>
                            <ns:Package id="10">
                                <ns:Height>10</ns:Height>
                                <ns:Width>10</ns:Width>
                                <ns:Length>10</ns:Length>
                                <ns:GrossWeight>50</ns:GrossWeight>
                            </ns:Package>
                            <ns:Package id="11">
                                <ns:Height>10</ns:Height>
                                <ns:Width>10</ns:Width>
                                <ns:Length>10</ns:Length>
                                <ns:GrossWeight>50</ns:GrossWeight>
                            </ns:Package>
                            <ns:Package id="12">
                                <ns:Height>11</ns:Height>
                                <ns:Width>10</ns:Width>
                                <ns:Length>10</ns:Length>
                                <ns:GrossWeight>50</ns:GrossWeight>
                            </ns:Package>
                        </ns:Packages>
                    </ns:Consignment>
                  </ns:Consignments>
              </ns:ShippingGuideRequest>
          </soapenv:Body>
      </soapenv:Envelope>
      ```

      ### 5. Submit the request

      Post your request to

      ```

        https://api.bring.com/shippingguide/api/ws

      ```

      The response may have changed since it was documented but you will get a response that looks something like this:

      ```
      <SOAP-ENV:Envelope xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/">
          <SOAP-ENV:Header/>
          <SOAP-ENV:Body>
              <ns2:ShippingGuideResponse xmlns:ns2="http://www.bring.no/logistics/shippingguide/2.0">
                  <ns2:Consignments>
                      <ns2:Consignment consignmentId="101">
                          <ns2:Products>
                              <ns2:Product>
                                  <ns2:Id>SERVICEPAKKE</ns2:Id>
                                  <ns2:ProductionCode>1202</ns2:ProductionCode>
                                  <ns2:GuiInformation>
                                      <ns2:SortOrder>11</ns2:SortOrder>
                                      <ns2:MainDisplayCategory>Pakke</ns2:MainDisplayCategory>
                                      <ns2:SubDisplayCategory>Til private</ns2:SubDisplayCategory>
                                      <ns2:DisplayName>Klimanøytral Servicepakke</ns2:DisplayName>
                                      <ns2:ProductName>Klimanøytral Servicepakke</ns2:ProductName>
                                      <ns2:DescriptionText>Pakken kan spores og utleveres på ditt lokale hentested.</ns2:DescriptionText>
                                      <ns2:HelpText>Klimanøytral Servicepakke leveres til mottakers lokale hentested (postkontor eller Post i Butikk). Mottaker kan velge å hente sendingen på et annet hentested enn sitt lokale. Mottaker varsles om at sendingen er ankommet via SMS, e-post eller hentemelding i postkassen. Sendingen kan spores ved hjelp av sporingsnummeret.</ns2:HelpText>
                                      <ns2:ShortName>Klimanøytral Servicepakke</ns2:ShortName>
                                      <ns2:ProductURL>http://www.bring.no/sende/pakker/private-i-norge/hentes-pa-posten</ns2:ProductURL>
                                      <ns2:DeliveryType>Hentested</ns2:DeliveryType>
                                      <ns2:MaxWeightInKgs>35</ns2:MaxWeightInKgs>
                                  </ns2:GuiInformation>
                                  <ns2:Price>
                                      <ns2:ListPrice currencyCode="NOK">
                                          <ns2:PriceWithoutAdditionalServices>
                                              <ns2:AmountWithoutVAT>239.00</ns2:AmountWithoutVAT>
                                              <ns2:VAT>59.75</ns2:VAT>
                                              <ns2:AmountWithVAT>298.75</ns2:AmountWithVAT>
                                          </ns2:PriceWithoutAdditionalServices>
                                          <ns2:PriceWithAdditionalServices>
                                              <ns2:AmountWithoutVAT>239.00</ns2:AmountWithoutVAT>
                                              <ns2:VAT>59.75</ns2:VAT>
                                              <ns2:AmountWithVAT>298.75</ns2:AmountWithVAT>
                                          </ns2:PriceWithAdditionalServices>
                                      </ns2:ListPrice>
                                  </ns2:Price>
                                  <ns2:ExpectedDelivery>
                                      <ns2:WorkingDays>2</ns2:WorkingDays>
                                      <ns2:UserMessage/>
                                      <ns2:FormattedExpectedDeliveryDate>12.10.2018</ns2:FormattedExpectedDeliveryDate>
                                      <ns2:ExpectedDeliveryDate>
                                          <ns2:Year>2018</ns2:Year>
                                          <ns2:Month>10</ns2:Month>
                                          <ns2:Day>12</ns2:Day>
                                      </ns2:ExpectedDeliveryDate>
                                      <ns2:AlternativeDeliveryDates/>
                                  </ns2:ExpectedDelivery>
                              </ns2:Product>
                              <ns2:Product>
                                  <ns2:Id>PA_DOREN</ns2:Id>
                                  <ns2:ProductionCode>1736</ns2:ProductionCode>
                                  <ns2:GuiInformation>
                                      <ns2:SortOrder>41</ns2:SortOrder>
                                      <ns2:MainDisplayCategory>Pakke</ns2:MainDisplayCategory>
                                      <ns2:SubDisplayCategory>Til private</ns2:SubDisplayCategory>
                                      <ns2:DisplayName>På Døren</ns2:DisplayName>
                                      <ns2:ProductName>På Døren</ns2:ProductName>
                                      <ns2:DescriptionText>Pakken kan spores og leveres hjem til deg mellom kl. 17-21. Sjåføren ringer 30-60 min før ankomst.</ns2:DescriptionText>
                                      <ns2:HelpText>På Døren leveres hjem til mottaker mellom kl. 17 og 21. Mottaker varsles i god tid om forventet utleveringsdag via SMS eller e-post, i tillegg til nytt varsel når sendingen er lastet på bil for utkjøring samme kveld. Sjåføren ringer mottaker 30-60 minutter før ankomst. Mottaker kan endre leveringsdag når pakken spores (gjelder ikke lokalpakker). Dersom sendingen ikke kan leveres, blir den sendt til mottakers lokale hentested (postkontor eller Post i Butikk). Sendingen kan spores ved hjelp av sporingsnummeret.</ns2:HelpText>
                                      <ns2:ShortName>På Døren</ns2:ShortName>
                                      <ns2:ProductURL>http://www.bring.no/sende/pakker/private-i-norge/hjemlevering</ns2:ProductURL>
                                      <ns2:DeliveryType>Dør</ns2:DeliveryType>
                                      <ns2:MaxWeightInKgs>35</ns2:MaxWeightInKgs>
                                  </ns2:GuiInformation>
                                  <ns2:Price>
                                      <ns2:ListPrice currencyCode="NOK">
                                          <ns2:PriceWithoutAdditionalServices>
                                              <ns2:AmountWithoutVAT>270.00</ns2:AmountWithoutVAT>
                                              <ns2:VAT>67.50</ns2:VAT>
                                              <ns2:AmountWithVAT>337.50</ns2:AmountWithVAT>
                                          </ns2:PriceWithoutAdditionalServices>
                                          <ns2:PriceWithAdditionalServices>
                                              <ns2:AmountWithoutVAT>270.00</ns2:AmountWithoutVAT>
                                              <ns2:VAT>67.50</ns2:VAT>
                                              <ns2:AmountWithVAT>337.50</ns2:AmountWithVAT>
                                          </ns2:PriceWithAdditionalServices>
                                      </ns2:ListPrice>
                                  </ns2:Price>
                                  <ns2:Warnings>
                                      <ns2:Warning>
                                          <ns2:code>NO_EXPECTED_DELIVERY</ns2:code>
                                          <ns2:description>Expected delivery date is not available</ns2:description>
                                      </ns2:Warning>
                                  </ns2:Warnings>
                              </ns2:Product>
                          </ns2:Products>
                      </ns2:Consignment>
                  </ns2:Consignments>
              </ns2:ShippingGuideResponse>
          </SOAP-ENV:Body>
      </SOAP-ENV:Envelope>
      ```

      If you want to know more about the fields you can have a look at the XSD linked from the section [Request and response structure](/api/shipping-guide_2/#request-and-response-structure)

- title: Shipping Guide topics
  content: |
      If you want to know more about corner cases/topics/etc, then [Let's talk about Shipping Guide](/api/shipping-guide_2/topics)

- title: Handle API errors
  content: |
      When using the Shipping Guide it is important to handle errors gracefully. Your users should still be able to order even if the Shipping Guide API returns an error or if there is an error establishing a connection to the API.

      The Shipping Guide API return two levels of error information:

      * HTTP error codes or SOAP fault with a message in the body

        For REST we follow general convention of HTTP status codes.
        For SOAP we give out detailed error decription along with an error code which can be parsed programmatically.

        ```
        <SOAP-ENV:Envelope xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/">
            <SOAP-ENV:Header/>
            <SOAP-ENV:Body>
                <SOAP-ENV:Fault>
                    <faultcode>SOAP-ENV:Client</faultcode>
                    <faultstring>FG_INPUT_010 Number of alternative delivery dates must be numeric and less than 10 [errorId 2806bbda-1df0-4b1b-b008-1068f5c57f06]
                    </faultstring>
                    <detail>
                        <code>FG_INPUT_010</code>
                        <description>Error number of alternative deliverydates</description>
                    </detail>
                </SOAP-ENV:Fault>
            </SOAP-ENV:Body>
        </SOAP-ENV:Envelope>
        ```

        Possible error codes can be found [here](https://api.bring.com/shippingguide/api/errors?clientUrl=developer.bring.com)

      * An error object in the response that is on product level

        When we are not able to process one of the product requested, we will respond with a error on product level. Details of possible error codes are documented in [XSD](https://api.bring.com/shippingguide/api/ws/shipping-guide-20.xsd) and [WDSL](https://api.bring.com/shippingguide/api/ws/shippingguide-20.wsdl) itself, making it easier for clients to parse it.

- title: Request and response structure
  content: |
      If you request shipping alternatives via the API your request and response will have to comply with the following schemas:

      #### SOAP

      [https://api.bring.com/shippingguide/api/ws/shipping-guide-20.xsd](https://api.bring.com/shippingguide/api/ws/shipping-guide-20.xsd)

      [https://api.bring.com/shippingguide/api/ws/shippingguide-20.wsdl](https://api.bring.com/shippingguide/api/ws/shippingguide-20.wsdl)

- title: Versioning
  content: |
       The Shipping Guide makes an effort to always be backwards compatible regarding data format for requests and responses. To achieve this, namespace schema versioning is used in the request for webservices, indicating which version the client is on and what data-format the client expects in the result. For REST, versioning is defined as part of endpoint itself.

       **Important**: All clients must accept **new (unknown) elements** in the response. E.g. unknown elements should be ignored. Also, **new error codes and warning codes** could be added as well. The client framework used by client must not crash when **unknown elements or new code values** are are encountered.

       When incompatible changes in the schema are made (other than addition of new elements), the namespace versioning will be updated accordingly. The new schema is used at the *same endpoint URL* as before for webservices. Old schema versions will be shut down some time in the future, so its recommended always updating to the latest version.

- title: Improve performance
  content: |
      To have better performance of the api

      * Request can be limited to have only the products needed since the response time of some products can be slow as compared to others
      * If the request is only to find the lead time / prices of different product, the flag for withExpectedDelivery / withPrices should be set to true and others can be set to false. In case of REST these are different endpoints.
      * For net prices requests should include customer number and correct package details
      * Request can include limited number of consignments in each request for quick response.
      * New shipments request can be part of separate request

/v2/products:
  displayName: Get shipment prices and estimated delivery
  description: Use this endpoint to get expected delivery, product categories and additional information.
  get:
    description: Get shipment prices
    headers:
      X-MyBring-API-Uid:
        description: Your Mybring login ID
      X-MyBring-API-Key:
        description: Your user's API key
      Accept:
        description: Specify request format (application/json, application/xml)
    queryParameters:
      fromcountry:
        description: Sender country code
        type: string
      tocountry:
        description: Receiver country code
        type: string
      frompostalcode:
        description: Sender postal code
        type: string
      topostalcode:
        description: Receiver postal code
        type: string
      product:
        description: List of products requested. Multiple products can be requested in a single request. Requested product can also be specified with a customer number separated with delimiter (**:**). For example CARGO**:**CARGO-123456
        type: string
      date:
        description: Shipping date
        type: date
        example: 2018-11-18
        required: false
      time:
        description: Shipping time
        type: date
        example: 12:30
        required: false
      weight:
        description: Package weight in grams
        type: integer
        required: false
      volumeindm3:
        description: Package volume in dm3
        type: integer
        required: false
      loadingmeter:
        description: Package loading meters
        type: double
        required: false
      width:
        description: Package width in cm
        type: integer
        required: false
      length:
        description: Package length in cm
        type: integer
        required: false
      height:
        description: Package height in cm
        type: integer
        required: false
      numberofpallets:
        displayName: Number of pallets
        type: integer
        required: false
      nonstackable:
        description: Set to true if you know that pallet would be non-stackable
        type: boolean
        required: false
        default: false
      edi:
        description: Tells if the parcel will be registered using EDI when being booked. It may affect price and which products are available
        type: boolean
        required: false
        default: true
      postingatpostoffice:
        description: |
          Tells whether the parcel is delivered at a post office when it is shipped. A surcharge will be applied for SERVICEPAKKE and BPAKKE_DOR-DOR
        type: boolean
        required: false
        default: false
      additionalservice:
        displayName: Additional service
        description: Multiple additional services can be requested by repeating this parameter
        required: false
        type: string
      customernumber:
        description: Lets you specify which customer number to use in the request. If specified and product is not supplied with delimited customer number, then it will be applied on all request products
        type: string
        example: CARGO-123456
        required: false
      language:
        description: Language used for the product texts
        type: string
        default: no
        required: false
      volumeSpecial:
        description: True if the package has a shape that requires special handling
        type: boolean
        default: false
        required: false
      incoterms:
        description: Terms of delivery
        type: string
        required: false
      unnumber:
        description: Code for dangerous goods
        type: integer
        required: false
      payer:
        description: Payer type. Possible values are SENDER, RECEIVER or THIRD_PARTY
        type: string
        required: false
      numberofdeliverydates:
        description: Number of alternative delivery dates to be suggested by API for request
        type: integer
        required: false

    responses:
      200:
        displayName: Successful response
        description: |
          A successful response
      400:
        displayName: User error
        description: |
          This can mean that a required field or parameter has not been provided, the value supplied is invalid, or the combination of provided fields is invalid.
      401:
        displayName: Unauthorized
        description: |
          A failed response when the request is unauthenticated

/v2/products/price:
  displayName: Get shipment prices
  description: |
      Use this endpoint to get prices. The request parameters are the same as for [Get shipment prices and estimated delivery](/api/shipping-guide_2/#get-shipment-prices-and-estimated-delivery)
  get:
    description: Use this endpoint to get price. The request parameters are the same as for [Get shipment prices and estimated delivery](/api/shipping-guide_v2/#get-shipment-prices-and-estimated-delivery)

/v2/products/expectedDelivery:
  displayName: Get expected delivery times
  description: |
      Use this endpoint to get expected delivery. The request parameters are the same as for [Get shipment prices and estimated delivery](/api/shipping-guide_2/#get-shipment-prices-and-estimated-delivery)
  get:
    description: Get estimated delivery time

/api/ws:
  displayName: Get shipment prices and estimated delivery
  description: Use this endpoint to get expected delivery, product categories and additional information.
  post:
    description: Use this endpoint to get expected delivery, product categories and additional information.
    headers:
      X-MyBring-API-Uid:
        description: Your Mybring login ID
      X-MyBring-API-Key:
        description: Your user's API key
      Accept:
        description: Specify request format (application/json, application/xml)

#%RAML 1.0
---
title: Shipping Guide API 2.0
baseUri: https://api.bring.com/shippingguide

documentation:
- title: Introduction
  content: |
      The Shipping Guide API 2.0 (Fraktguiden) for provides you with different shipping alternatives for your shipments. If you request applicable shipping alternatives with all relevant details you will receive an object with the following data:

      - Prices
      - Estimated delivery times
      - GUI information

      The API returns the recommended way to present these shipping alternatives, meaning that the actual response can easily be shown in a web-shop checkout without any sorting or filtering and with human readable product texts.

      The Shipping Guide API 2.0 has both a REST and a SOAP interface. The REST interface only supports single consignments, while the SOAP interface can be used for multiple consignments.

      ### Why upgrade?

      * [Unified request and response model](/api/shipping-guide_2/#getting-started): Due to backward compatibility, existing SOAP API versions had too many ways of requesting to Shipping Guide could be always confusing for clients. This has been simplified in the new version with one unified way of requesting to Shipping Guide.
      * [Better error handling for both SOAP and REST](/api/shipping-guide_2/#handle-api-errors): The new version of API gives ability to handle error in a much simpler way.
      * [Ability to fetch agreement prices specific to a product on REST](/api/shipping-guide_2/#get-shipment-prices-and-estimated-delivery): Now you can specify multiple products and along with multiple customer number in a single REST request. [How?](/api/shipping-guide_2/#get-shipment-prices-and-estimated-delivery)
      *  Some improvements to our service offering are planned for 2018-19. More info about upcoming changes will follow to all our partners. Future services will be supported by this new API-version in addition to other improvements. Note that our old versions of API’s will not support future changes in our service offering.

      ### How to upgrade
      Now that Shipping Guide API 2.0 is out you might be wondering how to upgrade to it. The [Upgrade to version 2.0](/api/shipping-guide_2/upgrade-to-version-2) will help you on your way to version 2.0 of the Shipping Guide API.

- title: Getting started
  content: |
      This guide will walk you through getting shipment alternatives for your first consignment using Shipping Guide API. In this example we will be calling the SOAP interface with a HTTP client and query for the product `SERVICEPAKKE` and `PA_DOREN` for two packages.

      ### Before you start
      Before you can begin using the new API you'll have to do the following:

      * [Sign up for a Mybring account](https://www.mybring.com/signup/register/user) if you do not already have one. If you're already registered in Mybring, head to the [settings and API](https://www.mybring.com/useradmin/account/settings/) page to get your API key.
      * [Generate an API key](/api/#authentication) for your user

      ### 1. Get your API key from Mybring
      To make API requests you will need an API key.

      To do this click the button below, which sends you to your "Settings and API" page in Mybring profile administration. Scroll down to the "API key" section. Your generated API key which you will use to authenticate your requests can be found here.

      Get API key

      ### 2. Add authentication headers
      A description of the headers can be found in [Getting Started / Authentication](/api/#authentication).

      ### 3. Add additional headers
      Since we're using the SOAP (1.1) interface we'll have to add the following header:

      - `Content-type: text/xml`

      Most SOAP libraries will do this for you.

      ### 4. Add the body to the request
      In this request we will query prices and expected delivery time for the product `SERVICEPAKKE` for a single package being sent from the postal code 0015 to 5518 in Norway.

      ```
      <soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/"
                        xmlns:ns="http://www.bring.no/logistics/shippingguide/2.0">
          <soapenv:Header/>
          <soapenv:Body>
              <ns:ShippingGuideRequest xmlns:ns="http://www.bring.no/logistics/shippingguide/2.0">
                  <ns:Language>no</ns:Language>
                  <ns:WithPrice>true</ns:WithPrice>
                  <ns:WithExpectedDelivery>false</ns:WithExpectedDelivery>
                  <ns:WithGuiInformation>true</ns:WithGuiInformation>
                  <ns:NumberOfAlternativeDeliveryDates>0</ns:NumberOfAlternativeDeliveryDates>
                  <ns:EDI>true</ns:EDI>
                  <ns:PostingAtPostoffice>true</ns:PostingAtPostoffice>
                  <ns:Trace>true</ns:Trace>
                  <ns:Consignments>
                    <ns:Consignment id="101">
                        <ns:Products>
                            <ns:Product>
                                <ns:Id>SERVICEPAKKE</ns:Id>
                            </ns:Product>
                        </ns:Products>
                        <ns:FromCountryCode>NO</ns:FromCountryCode>
                        <ns:FromPostalCode>0015</ns:FromPostalCode>
                        <ns:ToCountryCode>NO</ns:ToCountryCode>
                        <ns:ToPostalCode>5518</ns:ToPostalCode>
                        <ns:ShippingDate>
                            <ns:Year>2016</ns:Year>
                            <ns:Month>10</ns:Month>
                            <ns:Day>10</ns:Day>
                            <ns:Hour>10</ns:Hour>
                            <ns:Minute>0</ns:Minute>
                        </ns:ShippingDate>
                        <ns:AdditionalServices>
                            <ns:AdditionalService>
                                <ns:Id>EVARSLING</ns:Id>
                            </ns:AdditionalService>
                            <ns:AdditionalService>
                                <ns:Id>POSTOPPKRAV</ns:Id>
                            </ns:AdditionalService>
                            <ns:AdditionalService>
                                <ns:Id>SOSIAL_KONTROLL</ns:Id>
                            </ns:AdditionalService>
                        </ns:AdditionalServices>
                        <ns:Packages>
                            <ns:Package id="10">
                                <ns:Height>10</ns:Height>
                                <ns:Width>10</ns:Width>
                                <ns:Length>10</ns:Length>
                                <ns:GrossWeight>50</ns:GrossWeight>
                            </ns:Package>
                            <ns:Package id="11">
                                <ns:Height>10</ns:Height>
                                <ns:Width>10</ns:Width>
                                <ns:Length>10</ns:Length>
                                <ns:GrossWeight>50</ns:GrossWeight>
                            </ns:Package>
                            <ns:Package id="12">
                                <ns:Height>11</ns:Height>
                                <ns:Width>10</ns:Width>
                                <ns:Length>10</ns:Length>
                                <ns:GrossWeight>50</ns:GrossWeight>
                            </ns:Package>
                        </ns:Packages>
                    </ns:Consignment>
                  </ns:Consignments>
              </ns:ShippingGuideRequest>
          </soapenv:Body>
      </soapenv:Envelope>
      ```

      ### 5. Submit the request

      Post your request to

      ```

        https://api.bring.com/shippingguide/api/ws

      ```

      The response may have changed since it was documented but you will get a response that looks something like this:

      ```
      <SOAP-ENV:Envelope xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/">
          <SOAP-ENV:Header/>
          <SOAP-ENV:Body>
              <ns2:ShippingGuideResponse xmlns:ns2="http://www.bring.no/logistics/shippingguide/2.0">
                  <ns2:Consignments>
                      <ns2:Consignment consignmentId="101">
                          <ns2:Products>
                              <ns2:Product>
                                  <ns2:Id>SERVICEPAKKE</ns2:Id>
                                  <ns2:ProductionCode>1202</ns2:ProductionCode>
                                  <ns2:GuiInformation>
                                      <ns2:SortOrder>11</ns2:SortOrder>
                                      <ns2:MainDisplayCategory>Pakke</ns2:MainDisplayCategory>
                                      <ns2:SubDisplayCategory>Til private</ns2:SubDisplayCategory>
                                      <ns2:DisplayName>Klimanøytral Servicepakke</ns2:DisplayName>
                                      <ns2:ProductName>Klimanøytral Servicepakke</ns2:ProductName>
                                      <ns2:DescriptionText>Pakken kan spores og utleveres på ditt lokale hentested.</ns2:DescriptionText>
                                      <ns2:HelpText>Klimanøytral Servicepakke leveres til mottakers lokale hentested (postkontor eller Post i Butikk). Mottaker kan velge å hente sendingen på et annet hentested enn sitt lokale. Mottaker varsles om at sendingen er ankommet via SMS, e-post eller hentemelding i postkassen. Sendingen kan spores ved hjelp av sporingsnummeret.</ns2:HelpText>
                                      <ns2:ShortName>Klimanøytral Servicepakke</ns2:ShortName>
                                      <ns2:ProductURL>http://www.bring.no/sende/pakker/private-i-norge/hentes-pa-posten</ns2:ProductURL>
                                      <ns2:DeliveryType>Hentested</ns2:DeliveryType>
                                      <ns2:MaxWeightInKgs>35</ns2:MaxWeightInKgs>
                                  </ns2:GuiInformation>
                                  <ns2:Price>
                                      <ns2:ListPrice currencyCode="NOK">
                                          <ns2:PriceWithoutAdditionalServices>
                                              <ns2:AmountWithoutVAT>239.00</ns2:AmountWithoutVAT>
                                              <ns2:VAT>59.75</ns2:VAT>
                                              <ns2:AmountWithVAT>298.75</ns2:AmountWithVAT>
                                          </ns2:PriceWithoutAdditionalServices>
                                          <ns2:PriceWithAdditionalServices>
                                              <ns2:AmountWithoutVAT>239.00</ns2:AmountWithoutVAT>
                                              <ns2:VAT>59.75</ns2:VAT>
                                              <ns2:AmountWithVAT>298.75</ns2:AmountWithVAT>
                                          </ns2:PriceWithAdditionalServices>
                                      </ns2:ListPrice>
                                  </ns2:Price>
                                  <ns2:ExpectedDelivery>
                                      <ns2:WorkingDays>2</ns2:WorkingDays>
                                      <ns2:UserMessage/>
                                      <ns2:FormattedExpectedDeliveryDate>12.10.2018</ns2:FormattedExpectedDeliveryDate>
                                      <ns2:ExpectedDeliveryDate>
                                          <ns2:Year>2018</ns2:Year>
                                          <ns2:Month>10</ns2:Month>
                                          <ns2:Day>12</ns2:Day>
                                      </ns2:ExpectedDeliveryDate>
                                      <ns2:AlternativeDeliveryDates/>
                                  </ns2:ExpectedDelivery>
                              </ns2:Product>
                              <ns2:Product>
                                  <ns2:Id>PA_DOREN</ns2:Id>
                                  <ns2:ProductionCode>1736</ns2:ProductionCode>
                                  <ns2:GuiInformation>
                                      <ns2:SortOrder>41</ns2:SortOrder>
                                      <ns2:MainDisplayCategory>Pakke</ns2:MainDisplayCategory>
                                      <ns2:SubDisplayCategory>Til private</ns2:SubDisplayCategory>
                                      <ns2:DisplayName>På Døren</ns2:DisplayName>
                                      <ns2:ProductName>På Døren</ns2:ProductName>
                                      <ns2:DescriptionText>Pakken kan spores og leveres hjem til deg mellom kl. 17-21. Sjåføren ringer 30-60 min før ankomst.</ns2:DescriptionText>
                                      <ns2:HelpText>På Døren leveres hjem til mottaker mellom kl. 17 og 21. Mottaker varsles i god tid om forventet utleveringsdag via SMS eller e-post, i tillegg til nytt varsel når sendingen er lastet på bil for utkjøring samme kveld. Sjåføren ringer mottaker 30-60 minutter før ankomst. Mottaker kan endre leveringsdag når pakken spores (gjelder ikke lokalpakker). Dersom sendingen ikke kan leveres, blir den sendt til mottakers lokale hentested (postkontor eller Post i Butikk). Sendingen kan spores ved hjelp av sporingsnummeret.</ns2:HelpText>
                                      <ns2:ShortName>På Døren</ns2:ShortName>
                                      <ns2:ProductURL>http://www.bring.no/sende/pakker/private-i-norge/hjemlevering</ns2:ProductURL>
                                      <ns2:DeliveryType>Dør</ns2:DeliveryType>
                                      <ns2:MaxWeightInKgs>35</ns2:MaxWeightInKgs>
                                  </ns2:GuiInformation>
                                  <ns2:Price>
                                      <ns2:ListPrice currencyCode="NOK">
                                          <ns2:PriceWithoutAdditionalServices>
                                              <ns2:AmountWithoutVAT>270.00</ns2:AmountWithoutVAT>
                                              <ns2:VAT>67.50</ns2:VAT>
                                              <ns2:AmountWithVAT>337.50</ns2:AmountWithVAT>
                                          </ns2:PriceWithoutAdditionalServices>
                                          <ns2:PriceWithAdditionalServices>
                                              <ns2:AmountWithoutVAT>270.00</ns2:AmountWithoutVAT>
                                              <ns2:VAT>67.50</ns2:VAT>
                                              <ns2:AmountWithVAT>337.50</ns2:AmountWithVAT>
                                          </ns2:PriceWithAdditionalServices>
                                      </ns2:ListPrice>
                                  </ns2:Price>
                                  <ns2:Warnings>
                                      <ns2:Warning>
                                          <ns2:code>NO_EXPECTED_DELIVERY</ns2:code>
                                          <ns2:description>Expected delivery date is not available</ns2:description>
                                      </ns2:Warning>
                                  </ns2:Warnings>
                              </ns2:Product>
                          </ns2:Products>
                      </ns2:Consignment>
                  </ns2:Consignments>
              </ns2:ShippingGuideResponse>
          </SOAP-ENV:Body>
      </SOAP-ENV:Envelope>
      ```

      If you want to know more about the fields you can have a look at the XSD linked from the section [Request and response structure](/api/shipping-guide_2/#request-and-response-structure)

- title: Shipping Guide topics
  content: |
      If you want to know more about corner cases/topics/etc, then [Let's talk about Shipping Guide](/api/shipping-guide_2/topics)

- title: Handle API errors
  content: |
      When using the Shipping Guide it is important to handle errors gracefully. Your users should still be able to order even if the Shipping Guide API returns an error or if there is an error establishing a connection to the API.

      The Shipping Guide API return two levels of error information:

      * HTTP error codes or SOAP fault with a message in the body

        For REST we follow general convention of HTTP status codes.
        For SOAP we give out detailed error decription along with an error code which can be parsed programmatically.

        ```
        <SOAP-ENV:Envelope xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/">
            <SOAP-ENV:Header/>
            <SOAP-ENV:Body>
                <SOAP-ENV:Fault>
                    <faultcode>SOAP-ENV:Client</faultcode>
                    <faultstring>FG_INPUT_010 Number of alternative delivery dates must be numeric and less than 10 [errorId 2806bbda-1df0-4b1b-b008-1068f5c57f06]
                    </faultstring>
                    <detail>
                        <code>FG_INPUT_010</code>
                        <description>Error number of alternative deliverydates</description>
                    </detail>
                </SOAP-ENV:Fault>
            </SOAP-ENV:Body>
        </SOAP-ENV:Envelope>
        ```

        Possible error codes can be found [here](https://api.bring.com/shippingguide/api/errors?clientUrl=developer.bring.com)

      * An error object in the response that is on product level

        When we are not able to process one of the product requested, we will respond with a error on product level. Details of possible error codes are documented in [XSD](https://api.bring.com/shippingguide/api/ws/shipping-guide-20.xsd) and [WDSL](https://api.bring.com/shippingguide/api/ws/shippingguide-20.wsdl) itself, making it easier for clients to parse it.

- title: Request and response structure
  content: |
      If you request shipping alternatives via the API your request and response will have to comply with the following schemas:

      #### SOAP

      [https://api.bring.com/shippingguide/api/ws/shipping-guide-20.xsd](https://api.bring.com/shippingguide/api/ws/shipping-guide-20.xsd)

      [https://api.bring.com/shippingguide/api/ws/shippingguide-20.wsdl](https://api.bring.com/shippingguide/api/ws/shippingguide-20.wsdl)

- title: Versioning
  content: |
       The Shipping Guide makes an effort to always be backwards compatible regarding data format for requests and responses. To achieve this, namespace schema versioning is used in the request for webservices, indicating which version the client is on and what data-format the client expects in the result. For REST, versioning is defined as part of endpoint itself.

       **Important**: All clients must accept **new (unknown) elements** in the response. E.g. unknown elements should be ignored. Also, **new error codes and warning codes** could be added as well. The client framework used by client must not crash when **unknown elements or new code values** are are encountered.

       When incompatible changes in the schema are made (other than addition of new elements), the namespace versioning will be updated accordingly. The new schema is used at the *same endpoint URL* as before for webservices. Old schema versions will be shut down some time in the future, so its recommended always updating to the latest version.

- title: Improve performance
  content: |
      To have better performance of the api

      * Request can be limited to have only the products needed since the response time of some products can be slow as compared to others
      * If the request is only to find the lead time / prices of different product, the flag for withExpectedDelivery / withPrices should be set to true and others can be set to false. In case of REST these are different endpoints.
      * For net prices requests should include customer number and correct package details
      * Request can include limited number of consignments in each request for quick response.
      * New shipments request can be part of separate request

/v2/products:
  displayName: Get shipment prices and estimated delivery
  description: Use this endpoint to get expected delivery, product categories and additional information.
  get:
    description: Get shipment prices
    headers:
      X-MyBring-API-Uid:
        description: Your Mybring login ID
      X-MyBring-API-Key:
        description: Your user's API key
      Accept:
        description: Specify request format (application/json, application/xml)
    queryParameters:
      fromcountry:
        description: Sender country code
        type: string
      tocountry:
        description: Receiver country code
        type: string
      frompostalcode:
        description: Sender postal code
        type: string
      topostalcode:
        description: Receiver postal code
        type: string
      product:
        description: List of products requested. Multiple products can be requested in a single request. Requested product can also be specified with a customer number separated with delimiter (**:**). For example CARGO**:**CARGO-123456
        type: string
      date:
        description: Shipping date
        type: date
        example: 2018-11-18
        required: false
      time:
        description: Shipping time
        type: date
        example: 12:30
        required: false
      weight:
        description: Package weight in grams
        type: integer
        required: false
      volumeindm3:
        description: Package volume in dm3
        type: integer
        required: false
      loadingmeter:
        description: Package loading meters
        type: double
        required: false
      width:
        description: Package width in cm
        type: integer
        required: false
      length:
        description: Package length in cm
        type: integer
        required: false
      height:
        description: Package height in cm
        type: integer
        required: false
      numberofpallets:
        displayName: Number of pallets
        type: integer
        required: false
      nonstackable:
        description: Set to true if you know that pallet would be non-stackable
        type: boolean
        required: false
        default: false
      edi:
        description: Tells if the parcel will be registered using EDI when being booked. It may affect price and which products are available
        type: boolean
        required: false
        default: true
      postingatpostoffice:
        description: |
          Tells whether the parcel is delivered at a post office when it is shipped. A surcharge will be applied for SERVICEPAKKE and BPAKKE_DOR-DOR
        type: boolean
        required: false
        default: false
      additionalservice:
        displayName: Additional service
        description: Multiple additional services can be requested by repeating this parameter
        required: false
        type: string
      customernumber:
        description: Lets you specify which customer number to use in the request. If specified and product is not supplied with delimited customer number, then it will be applied on all request products
        type: string
        example: CARGO-123456
        required: false
      language:
        description: Language used for the product texts
        type: string
        default: no
        required: false
      volumeSpecial:
        description: True if the package has a shape that requires special handling
        type: boolean
        default: false
        required: false
      incoterms:
        description: Terms of delivery
        type: string
        required: false
      unnumber:
        description: Code for dangerous goods
        type: integer
        required: false
      payer:
        description: Payer type. Possible values are SENDER, RECEIVER or THIRD_PARTY
        type: string
        required: false

    responses:
      200:
        displayName: Successful response
        description: |
          A successful response
      400:
        displayName: User error
        description: |
          This can mean that a required field or parameter has not been provided, the value supplied is invalid, or the combination of provided fields is invalid.
      401:
        displayName: Unauthorized
        description: |
          A failed response when the request is unauthenticated

/v2/products/price:
  displayName: Get shipment prices
  description: |
      Use this endpoint to get prices. The request parameters are the same as for [Get shipment prices and estimated delivery](/api/shipping-guide_2/#get-shipment-prices-and-estimated-delivery)
  get:
    description: Use this endpoint to get price. The request parameters are the same as for [Get shipment prices and estimated delivery](/api/shipping-guide_v2/#get-shipment-prices-and-estimated-delivery)

/v2/products/expectedDelivery:
  displayName: Get expected delivery times
  description: |
      Use this endpoint to get expected delivery. The request parameters are the same as for [Get shipment prices and estimated delivery](/api/shipping-guide_2/#get-shipment-prices-and-estimated-delivery)
  get:
    description: Get estimated delivery time

/api/ws:
  displayName: Get shipment prices and estimated delivery
  description: Use this endpoint to get expected delivery, product categories and additional information.
  post:
    description: Use this endpoint to get expected delivery, product categories and additional information.
    headers:
      X-MyBring-API-Uid:
        description: Your Mybring login ID
      X-MyBring-API-Key:
        description: Your user's API key
      Accept:
        description: Specify request format (application/json, application/xml)


correction

correction

#%RAML 0.8
---
title: Reports API
baseUri: https://www.mybring.com/reports/api

documentation:
- title: Introduction
  content: |
    The Reports API is used to generate shipment reports, the same set of reports that are available in mybring.

    Each Mybring user is associated with a set of customers and has access to specific set of report types for which they can generate a report.

    The following steps (which will be API calls) enables you to generate a report:

    1. Get the customers associated with the mybring user.
    2. Get the report types allowed for a customer.
    3. Initiate report creation and get report ID. The Report ID is initially used to monitor reports creation progress, later to get the actual report (XML or Excel file).
    4. After initiating report creation, you can check the status if the job. I.e. if it is in progress, completed or failed. When status is completed, a URL for fetching the actual report is returned.
    5. The report can then be downloaded.

    For all the above APIs we need to identify and authenticate the user. This is done by passing the following header information. These are described in Reference section:

    - Mybring username (email address)
    - API Key

    All these APIs are available in json and xml formats.

- title: How to use
  content: |
    The Reports API is a logged-in service and you need to get an API-key and authenticate before being able to use the API.

    The two first steps in the process is only necessary to find customer numbers and report types for the user. You can save these IDs, and perform the generation-step without verifying the IDs. The response may get added information, so implementation should ignore new elements added to the response.

    1. Get customer IDs
    2. Get list of available reports
    3. Generate report
    4. Check status of report
    5. Download report
    6. Get list of invoice numbers for given customer or group

- title:
  content: |
    #### List of available invoice sources
    For specified invoice report 4 different types of report can be returned depending on the invoice source. Those are

    Cargo Domestic and Sea :
      - AMPHORA_DOMESTIC
      - AMPHORA_SEA

    Cargo International and Sysped :
      - AMPHORA_BCI
      - SYSPED

    Parcels :
      - PARCEL_DOMESTIC

    Frigo :
      - TIMPEX

- title: Authentication
  content: |
    The Reports 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.

/generate{mediaTypeExtension}:
  displayName: List available customers
  description: |
    List available customers for the provided API credentials.
  uriParameters:
    mediaTypeExtension:
      enum: [ .json, .xml ]
      description: Use .json to specify application/json or .xml to specify application/xml
  get:
    description: List available customers
    headers:
      Accept-Language:
        description: A comma-separated list of language codes, `no` for Norwegian, `en` for English, etc.
        type: string
        required: false
    responses:
      200:
        displayName: Successful response
        body:
          application/json:
            example: !include examples/list_customers.json
          application/xml:
            example: !include examples/list_customers.xml

/generate/{customerId}{mediaTypeExtension}:
  displayName: List available reports for a customer
  description: |
    Each customer has a set of reports available. This endpoint lists all available reports for a given customer.
  uriParameters:
    customerId:
      description: A customer ID from the 'list of available customers' call.
      type: string
      required: true
    mediaTypeExtension:
      enum: [ .json, .xml ]
      description: Use .json to specify application/json or .xml to specify application/xml
  get:
    description: List available reports for a customer
    headers:
      Accept-Language:
        description: A comma-separated list of language codes, `no` for Norwegian, `en` for English, etc.
        type: string
        required: false
    responses:
      200:
        displayName: Successful response
        body:
          application/json:
            example: !include examples/list_reports.json
          application/xml:
            example: !include examples/list_reports.xml

/generate/{customerId}/{reportTypeId}{mediaTypeExtension}:
  displayName: Generate a report
  description: |
    To generate a report do a GET to the supplied URL, and include the parameters described in the previous response. You need not invoke the two first steps for every report generation if customer id and report type are known.

    This is asynchronous request. So the GET-call will return 202, telling the caller the that the request for a report is put on the queue. The URL to query to get the status for the request if provided as an HTTP header and also in the response.

    The example below shows how to generate a PARCELS-DELIVERED report for PARCELS_NORWAY-00012341234 in the period 01.07.2014 to 01.08.2014.
  uriParameters:
    customerId:
      description: A customer ID from the 'list of available customers' call.
      type: string
      required: true
    reportTypeId:
      description: A report type ID from the 'list of available reports' call.
      type: string
      required: true
    mediaTypeExtension:
      enum: [ .json, .xml ]
      description: Use .json to specify application/json or .xml to specify application/xml
  get:
    description: Generate a report
    queryParameters:
      parameterName:
        description: The different report types have different params. The params are doucmented in the list of available reports, for example `fromDate` and `toDate`.
        type: string
        required: true
    headers:
      Accept-Language:
        description: A comma-separated list of language codes, `no` for Norwegian, `en` for English, etc.
        type: string
        required: false
    responses:
      202:
        displayName: Successful response
        headers:
          Location:
            description: URL to get status of the generated report
            required: true
            type: string
            example: https://www.mybring.com/reports/api/report/db285042-6e8d-4563-94ca-eb1100706a73/status/
        body:
          application/json:
            example: !include examples/generate_report.json
          application/xml:
            example: !include examples/generate_report.xml

/report/{reportId}/status{mediaTypeExtension}:
  displayName: Check the status of a report
  description: |
    Since the generation of reports may take several minutes, we supply a status address to check the status of the report generation. The status page will display `NOT_DONE`, until the report is ready to be downloaded. When the report is ready, URLs to download the report will be in the response
  uriParameters:
    reportId:
      description: A report ID from a 'generate a report' call.
      type: string
      required: true
    mediaTypeExtension:
      enum: [ .json, .xml ]
      description: Use .json to specify application/json or .xml to specify application/xml
  get:
    description: Check the status of a report
    headers:
      Accept-Language:
        description: A comma-separated list of language codes, `no` for Norwegian, `en` for English, etc.
        type: string
        required: false
    responses:
      200:
        displayName: Report status
        description: Examples show different statuses.
        body:
          application/json+notdone:
            example: !include examples/status_not_done.json
          application/json+done:
            example: !include examples/status_done.json
          application/json+failed:
            example: !include examples/status_failed.json
          application/xml+notdone:
            example: !include examples/status_not_done.xml
          application/xml+done:
            example: !include examples/status_done.xml
          application/xml+failed:
            example: !include examples/status_failed.xml

/report/{reportId}{mediaTypeExtension}:
  displayName: Get report
  description: |
    Returns the generated report.
  uriParameters:
    reportId:
      description: A report ID from a 'generate a report' call.
      type: string
      required: true
    mediaTypeExtension:
      enum: [ .xls, .xml ]
      description: Use .xls to get Excel file or .xml to get XML file.
  get:
    headers:
      Accept-Language:
        description: A comma-separated list of language codes, `no` for Norwegian, `en` for English, etc.
        type: string
        required: false
    responses:
      200:
        displayName: Report
        description: |
          Examples show the MetaData included in successful(200) response for specified invoice report vs other reports.
        body:
          application/xml+invoice:
            example: !include examples/empty_invoice_report.xml
          application/xml:
            example: !include examples/empty_report.xml

/invoices/{customerOrGroupId}{mediaTypeExtension}:
  displayName: List invoice numbers
  description: |
    Gets the list of invoice numbers for a customer id or a customer group. By default it shows last 65 days of invoices, with the possibilty to access 365 days data by providing from date and to date.
  uriParameters:
    customerOrGroupId:
      description: Id for customer or customer group. Customer group id should have the prefix `GROUP_`.
      type: string
      required: true
    mediaTypeExtension:
      enum: [ .json, .xml ]
      description: Use .json to specify application/json or .xml to specify application/xml
  get:
    headers:
      Accept-Language:
        description: A comma-separated list of language codes, `no` for Norwegian, `en` for English, etc.
        type: string
        required: false
    queryParameters:
            fromDate:
              description: Start date for fetching invoices in format dd.mm.yyyy.
              required: false
              example: 01.01.2019
            toDate:
              description: End date for fetching invoices in format dd.mm.yyyy.
              type: string
              required: false
              example: 30.06.2019
    responses:
      200:
        displayName: Successful response
        body:
          application/json:
            example: !include examples/list_invoices.json
          application/xml:
            example: !include examples/list_invoices.xml

#%RAML 0.8
---
title: Reports API
baseUri: https://www.mybring.com/reports/api

documentation:
- title: Introduction
  content: |
    The Reports API is used to generate shipment reports, the same set of reports that are available in mybring.

    Each Mybring user is associated with a set of customers and has access to specific set of report types for which they can generate a report.

    The following steps (which will be API calls) enables you to generate a report:

    1. Get the customers associated with the mybring user.
    2. Get the report types allowed for a customer.
    3. Initiate report creation and get report ID. The Report ID is initially used to monitor reports creation progress, later to get the actual report (XML or Excel file).
    4. After initiating report creation, you can check the status if the job. I.e. if it is in progress, completed or failed. When status is completed, a URL for fetching the actual report is returned.
    5. The report can then be downloaded.

    For all the above APIs we need to identify and authenticate the user. This is done by passing the following header information. These are described in Reference section:

    - Mybring username (email address)
    - API Key

    All these APIs are available in json and xml formats.

- title: How to use
  content: |
    The Reports API is a logged-in service and you need to get an API-key and authenticate before being able to use the API.

    The two first steps in the process is only necessary to find customer numbers and report types for the user. You can save these IDs, and perform the generation-step without verifying the IDs. The response may get added information, so implementation should ignore new elements added to the response.

    1. Get customer IDs
    2. Get list of available reports
    3. Generate report
    4. Check status of report
    5. Download report
    6. Get list of invoice numbers for given customer or group

- title:
  content: |
    #### List of available invoice sources
    For specified invoice report 4 different types of report can be returned depending on the invoice type. Those are

    Cargo Domestic and Sea :
      - AMPHORA_DOMESTIC
      - AMPHORA_SEA

    Cargo International and Sysped :

      - AMPHORA_BCI
      - SYSPED

    Parcels :
      - PARCEL_DOMESTIC

    Frigo :
      - TIMPEX

- title: Authentication
  content: |
    The Reports 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.

/generate{mediaTypeExtension}:
  displayName: List available customers
  description: |
    List available customers for the provided API credentials.
  uriParameters:
    mediaTypeExtension:
      enum: [ .json, .xml ]
      description: Use .json to specify application/json or .xml to specify application/xml
  get:
    description: List available customers
    headers:
      Accept-Language:
        description: A comma-separated list of language codes, `no` for Norwegian, `en` for English, etc.
        type: string
        required: false
    responses:
      200:
        displayName: Successful response
        body:
          application/json:
            example: !include examples/list_customers.json
          application/xml:
            example: !include examples/list_customers.xml

/generate/{customerId}{mediaTypeExtension}:
  displayName: List available reports for a customer
  description: |
    Each customer has a set of reports available. This endpoint lists all available reports for a given customer.
  uriParameters:
    customerId:
      description: A customer ID from the 'list of available customers' call.
      type: string
      required: true
    mediaTypeExtension:
      enum: [ .json, .xml ]
      description: Use .json to specify application/json or .xml to specify application/xml
  get:
    description: List available reports for a customer
    headers:
      Accept-Language:
        description: A comma-separated list of language codes, `no` for Norwegian, `en` for English, etc.
        type: string
        required: false
    responses:
      200:
        displayName: Successful response
        body:
          application/json:
            example: !include examples/list_reports.json
          application/xml:
            example: !include examples/list_reports.xml

/generate/{customerId}/{reportTypeId}{mediaTypeExtension}:
  displayName: Generate a report
  description: |
    To generate a report do a GET to the supplied URL, and include the parameters described in the previous response. You need not invoke the two first steps for every report generation if customer id and report type are known.

    This is asynchronous request. So the GET-call will return 202, telling the caller the that the request for a report is put on the queue. The URL to query to get the status for the request if provided as an HTTP header and also in the response.

    The example below shows how to generate a PARCELS-DELIVERED report for PARCELS_NORWAY-00012341234 in the period 01.07.2014 to 01.08.2014.
  uriParameters:
    customerId:
      description: A customer ID from the 'list of available customers' call.
      type: string
      required: true
    reportTypeId:
      description: A report type ID from the 'list of available reports' call.
      type: string
      required: true
    mediaTypeExtension:
      enum: [ .json, .xml ]
      description: Use .json to specify application/json or .xml to specify application/xml
  get:
    description: Generate a report
    queryParameters:
      parameterName:
        description: The different report types have different params. The params are doucmented in the list of available reports, for example `fromDate` and `toDate`.
        type: string
        required: true
    headers:
      Accept-Language:
        description: A comma-separated list of language codes, `no` for Norwegian, `en` for English, etc.
        type: string
        required: false
    responses:
      202:
        displayName: Successful response
        headers:
          Location:
            description: URL to get status of the generated report
            required: true
            type: string
            example: https://www.mybring.com/reports/api/report/db285042-6e8d-4563-94ca-eb1100706a73/status/
        body:
          application/json:
            example: !include examples/generate_report.json
          application/xml:
            example: !include examples/generate_report.xml

/report/{reportId}/status{mediaTypeExtension}:
  displayName: Check the status of a report
  description: |
    Since the generation of reports may take several minutes, we supply a status address to check the status of the report generation. The status page will display `NOT_DONE`, until the report is ready to be downloaded. When the report is ready, URLs to download the report will be in the response
  uriParameters:
    reportId:
      description: A report ID from a 'generate a report' call.
      type: string
      required: true
    mediaTypeExtension:
      enum: [ .json, .xml ]
      description: Use .json to specify application/json or .xml to specify application/xml
  get:
    description: Check the status of a report
    headers:
      Accept-Language:
        description: A comma-separated list of language codes, `no` for Norwegian, `en` for English, etc.
        type: string
        required: false
    responses:
      200:
        displayName: Report status
        description: Examples show different statuses.
        body:
          application/json+notdone:
            example: !include examples/status_not_done.json
          application/json+done:
            example: !include examples/status_done.json
          application/json+failed:
            example: !include examples/status_failed.json
          application/xml+notdone:
            example: !include examples/status_not_done.xml
          application/xml+done:
            example: !include examples/status_done.xml
          application/xml+failed:
            example: !include examples/status_failed.xml

/report/{reportId}{mediaTypeExtension}:
  displayName: Get report
  description: |
    Returns the generated report.
  uriParameters:
    reportId:
      description: A report ID from a 'generate a report' call.
      type: string
      required: true
    mediaTypeExtension:
      enum: [ .xls, .xml ]
      description: Use .xls to get Excel file or .xml to get XML file.
  get:
    headers:
      Accept-Language:
        description: A comma-separated list of language codes, `no` for Norwegian, `en` for English, etc.
        type: string
        required: false
    responses:
      200:
        displayName: Report
        description: |
          Examples show the MetaData included in successful(200) response for specified invoice report vs other reports.
        body:
          application/xml+invoice:
            example: !include examples/empty_invoice_report.xml
          application/xml:
            example: !include examples/empty_report.xml

/invoices/{customerOrGroupId}{mediaTypeExtension}:
  displayName: List invoice numbers
  description: |
    Gets the list of invoice numbers for a customer id or a customer group. By default it shows last 65 days of invoices, with the possibilty to access 365 days data by providing from date and to date.
  uriParameters:
    customerOrGroupId:
      description: Id for customer or customer group. Customer group id should have the prefix `GROUP_`.
      type: string
      required: true
    mediaTypeExtension:
      enum: [ .json, .xml ]
      description: Use .json to specify application/json or .xml to specify application/xml
  get:
    headers:
      Accept-Language:
        description: A comma-separated list of language codes, `no` for Norwegian, `en` for English, etc.
        type: string
        required: false
    queryParameters:
            fromDate:
              description: Start date for fetching invoices in format dd.mm.yyyy.
              required: false
              example: 01.01.2019
            toDate:
              description: End date for fetching invoices in format dd.mm.yyyy.
              type: string
              required: false
              example: 30.06.2019
    responses:
      200:
        displayName: Successful response
        body:
          application/json:
            example: !include examples/list_invoices.json
          application/xml:
            example: !include examples/list_invoices.xml


Removed Pageable option from /locations/geojson end-point

#%RAML 1.0
title: Digitale Delta - API
version: 2.0.1
securitySchemes:
  basic:
    type: Basic Authentication
  openidconnect:
    type: OAuth 2.0
baseUri: http://api.rws.nl/dl/
mediaType: [ application/json ]
description: Digital Delta API version 2.0.1
documentation:
 - title: Introduction
   content: !include documentation/dd/Introduction.md
 - title: Document history
   content: !include documentation/dd/Document_History.md
 - title: The API specification
   content: !include documentation/dd/The_API_Specification.md
 - title: End points specification
   content: !include documentation/dd/End_Points_Specification.md

# HTTP is included as protocol but is optional as for security reasons a Provider might decide to support HTTPS only.
protocols:
  - HTTP
  - HTTPS

uses:
  DD-T: libraries/dd-base-types.raml
  GENERIC-RESP: libraries/generic-response-types.raml
  DD-RESP: libraries/dd-response-types.raml
  TRAITS: libraries/dd-traits.raml

#
# All data types are defined in external files (see above) so they can be shared between DD and DD-OPER API.
#
types:

#
# The resources
/dd/2.0:

# ##################################################

  /nodes:
    get:
      description: |
        A (data)node is an area from which resource objects can be retrieved.
      is: [ TRAITS.pageable, TRAITS.has403-AccessDeniedError, TRAITS.has500-ServerError ]
      queryParameters:
        process?:
          type: DD-T.ProcessName
        name?:
          type: string
          description: (Partial) name of the node. Partial meaning startsWith(...).
          example: RwsPrimaryNode
      responses:
        200:
          description: |
            Succesfully retrieved resource.
          body:
            application/json:
              type: DD-RESP.NodeListResponse
              example: !include examples/dd-nodelist-response.json
    /{nodeId}:
      uriParameters:
        nodeId:
          type: DD-T.Identifier
      is: [ TRAITS.has403-AccessDeniedError, TRAITS.has404-NotFoundError, TRAITS.has500-ServerError ]
      get:
        description: Request a specific Node by its unique dentifier.
        queryParameters:
          process?:
            type: DD-T.ProcessName
        responses:
          200:
            description: |
              Succesfully retrieved resource.
            body:
              application/json:
                type: DD-RESP.NodeResponse
                example: !include examples/dd-node-response.json

# ##################################################

  /sources:
    is: [ TRAITS.pageable, TRAITS.has403-AccessDeniedError, TRAITS.has500-ServerError ]
    get:
      description: |
        A (data)source describes the source of the data. A node can have multiple data sources.
      queryParameters:
        process?:
          type: DD-T.ProcessName
      responses:
        200:
          description: Succesfully retrieved resource.
          body:
            application/json:
              type: DD-RESP.SourceListResponse
              example: !include examples/dd-sourcelist-response.json

# #####################################################

  /locations:
    get:
      description: |
        Location objects contains all information required to describe a location.
      is: [ TRAITS.pageable, TRAITS.has400-InvalidRequestError, TRAITS.has403-AccessDeniedError, TRAITS.has500-ServerError, TRAITS.locationFilterable ]
      queryParameters:
        process?:
          type: DD-T.ProcessName
        boundingBox?:
          type: DD-T.BoundingBox
        locationName?:
          type: DD-T.LocationName
        nodeId?:
          type: DD-T.Identifier
          description: This query parameter is deprecated.
        locationCode?:
          type: DD-T.LocationCode
        locationId?:
          type: DD-T.Identifier
      responses:
        200:
          description: Succesfully retrieved resource.
          body:
            application/json:
              type: DD-RESP.LocationListResponse
              example: !include examples/dd-locationslist-response.json

    /geojson:
      get:
        description: |
          Retrieve location resources. Response is in GeoJSON FeatureCollection format (see https://tools.ietf.org/html/rfc7946#page-12).
        is: [ TRAITS.has400-InvalidRequestError, TRAITS.has403-AccessDeniedError, TRAITS.has500-ServerError, TRAITS.locationFilterable ]
        queryParameters:
          process?:
            type: DD-T.ProcessName
          boundingBox?:
            type: DD-T.BoundingBox
          locationName?:
            type: DD-T.LocationName
          nodeId?:
            type: DD-T.Identifier
            description: This query parameter is deprecated.
          locationCode?:
            type: DD-T.LocationCode
          locationId?:
            type: DD-T.Identifier
        responses:
          200:
            description: Succesfully retrieved resource.
            body:
              application/json:
                type: DD-RESP.LocationListResponseGeoJSON
                example: !include examples/dd-locationslist-response-geojson.json

    /{locationId}:
      description: Request a specific location by its id. Response is always in GeoJSON Feature format (see https://tools.ietf.org/html/rfc7946#page-11).
      uriParameters:
        locationId:
          type: DD-T.Identifier
      is: [ TRAITS.has403-AccessDeniedError, TRAITS.has404-NotFoundError, TRAITS.has500-ServerError ]
      get:
        description: |
          Request a specific Location by its unique dentifier.
        queryParameters:
          process?:
            type: DD-T.ProcessName
            default: measurement
        responses:
          200:
            description: |
              Succesfully retrieved resource
            body:
              application/json:
                type: object
                example: !include examples/dd-location-response.json

######################################################

  /observationTypes:
    get:
      description: |
        ObservationType objects describe all attributes to correctly interpret what has been measured, and in what way. It is essential to have the quantity field.
      is: [ TRAITS.pageable, TRAITS.has400-InvalidRequestError, TRAITS.has403-AccessDeniedError, TRAITS.has500-ServerError, TRAITS.observationTypeFilterable ]
      queryParameters:
        process?:
          type: DD-T.ProcessName
        observationTypeId?:
          type: DD-T.Identifier
        quantity?:
          description: Retrieve only observation types that contain the specified quantity.
          type: string
        parameterCode?:
          description: Retrieve only observation types that contain the specified parameter code.
          type: string
      responses:
        200:
          description: |
            Succesfully retrieved timeseries.
          body:
            application/json:
              type: DD-RESP.ObservationTypeListResponse
              example: !include examples/dd-observationtypelist-response.json

    /{observationTypeId}:
      is: [ TRAITS.has403-AccessDeniedError, TRAITS.has404-NotFoundError, TRAITS.has500-ServerError ]
      uriParameters:
        observationTypeId:
          type: DD-T.Identifier
      get:
        description: Request a specific ObservationType by its unique identifier.
        queryParameters:
          process?:
            type: DD-T.ProcessName
        responses:
          200:
            description: |
              Succesfully retrieved resource.
            body:
              application/json:
                type: DD-RESP.ObservationTypeResponse
                example: !include examples/dd-observationtype-response.json

######################################################

  /timeseries:
    get:
      description: |
        TimeSeriesType objects describe the type of measurement the timeseries contains. These can be for example raw measurements, but also aggregations or simulations. This information could be needed to correctly interpret the measurement values.
        A request where both startTime and endTime are omitted returns a response with just the metadata.
      is: [ TRAITS.pageable, TRAITS.has400-InvalidRequestError, TRAITS.has403-AccessDeniedError, TRAITS.has500-ServerError, TRAITS.timeseriesFilterable, TRAITS.locationFilterable, TRAITS.observationTypeFilterable ]
      queryParameters:
        process?:
          type: DD-T.ProcessName
        startTime?:
          type: DD-T.StartTime
        endTime?:
          type: DD-T.EndTime
        locationCode?:
          type: DD-T.LocationCode
        locationName?:
          type: DD-T.LocationName
        sourceName?:
          type: DD-T.SourceName
        observationTypeId?:
          type: DD-T.Identifier
        realizationCount?:
          description: Added Count as this is the name in ObservationType response.
          type: integer
        parameterCode?:
          description: Implementation is optional. Preferably to be implemented by means of the generic filtering mechanism.
          type: string
        quantity?:
          description: Implementation is optional. Preferably to be implemented by means of the generic filtering mechanism.
          type: string
        valueType?:
          description: Value type (float, integer, categorized).
          type: string
        nodeId?:
          type: DD-T.Identifier
        qualifier?:
          description: Filter for the optional qualifier property.
          type: string
        aspectSet?:
          type: DD-T.AspectSetName
          description: Remark: Only required for systems that implement aspect sets
        quantityName?:
          type: DD-T.QuantityName
          description: Remark: Only required for systems that are accessed by RWS's MKK-DL
        intervalLength?:
          type: DD-T.IntervalLength
          description: Remark: Only required for systems that are accessed by RWS's MKK-DL
      responses:
        200:
          description: |
            Succesfully retrieved timeseries.
          body:
            application/json:
              type: DD-RESP.TimeseriesListResponse
              example: !include examples/dd-timeserieslist-response-verwachtingen-en-metingen-fulldd.json

    /{timeseriesId}:
      uriParameters:
        timeseriesId:
          type: DD-T.Identifier
      is: [ TRAITS.has403-AccessDeniedError, TRAITS.has404-NotFoundError, TRAITS.has500-ServerError ]
      get:
        description: Request a specific (single) Timeseries by its unique identifier.
        queryParameters:
          process?:
            type: DD-T.ProcessName
            default: measurement
        responses:
          200:
            description: |
              Succesfully retrieved resource
            body:
              application/json:
                type: DD-RESP.TimeseriesResponse
                example: !include examples/dd-timeseries-response-single.json

#%RAML 1.0
title: Digitale Delta - API
version: 2.0.1
securitySchemes:
  basic:
    type: Basic Authentication
  openidconnect:
    type: OAuth 2.0
baseUri: http://api.rws.nl/dl/
mediaType: [ application/json ]
description: Digital Delta API version 2.0.1
documentation:
 - title: Introduction
   content: !include documentation/dd/Introduction.md
 - title: Document history
   content: !include documentation/dd/Document_History.md
 - title: The API specification
   content: !include documentation/dd/The_API_Specification.md
 - title: End points specification
   content: !include documentation/dd/End_Points_Specification.md

# HTTP is included as protocol but is optional as for security reasons a Provider might decide to support HTTPS only.
protocols:
  - HTTP
  - HTTPS

uses:
  DD-T: libraries/dd-base-types.raml
  GENERIC-RESP: libraries/generic-response-types.raml
  DD-RESP: libraries/dd-response-types.raml
  TRAITS: libraries/dd-traits.raml

#
# All data types are defined in external files (see above) so they can be shared between DD and DD-OPER API.
#
types:

#
# The resources
/dd/2.0:

# ##################################################

  /nodes:
    get:
      description: |
        A (data)node is an area from which resource objects can be retrieved.
      is: [ TRAITS.pageable, TRAITS.has403-AccessDeniedError, TRAITS.has500-ServerError ]
      queryParameters:
        process?:
          type: DD-T.ProcessName
        name?:
          type: string
          description: (Partial) name of the node. Partial meaning startsWith(...).
          example: RwsPrimaryNode
      responses:
        200:
          description: |
            Succesfully retrieved resource.
          body:
            application/json:
              type: DD-RESP.NodeListResponse
              example: !include examples/dd-nodelist-response.json
    /{nodeId}:
      uriParameters:
        nodeId:
          type: DD-T.Identifier
      is: [ TRAITS.has403-AccessDeniedError, TRAITS.has404-NotFoundError, TRAITS.has500-ServerError ]
      get:
        description: Request a specific Node by its unique dentifier.
        queryParameters:
          process?:
            type: DD-T.ProcessName
        responses:
          200:
            description: |
              Succesfully retrieved resource.
            body:
              application/json:
                type: DD-RESP.NodeResponse
                example: !include examples/dd-node-response.json

# ##################################################

  /sources:
    is: [ TRAITS.pageable, TRAITS.has403-AccessDeniedError, TRAITS.has500-ServerError ]
    get:
      description: |
        A (data)source describes the source of the data. A node can have multiple data sources.
      queryParameters:
        process?:
          type: DD-T.ProcessName
      responses:
        200:
          description: Succesfully retrieved resource.
          body:
            application/json:
              type: DD-RESP.SourceListResponse
              example: !include examples/dd-sourcelist-response.json

# #####################################################

  /locations:
    get:
      description: |
        Location objects contains all information required to describe a location.
      is: [ TRAITS.pageable, TRAITS.has400-InvalidRequestError, TRAITS.has403-AccessDeniedError, TRAITS.has500-ServerError, TRAITS.locationFilterable ]
      queryParameters:
        process?:
          type: DD-T.ProcessName
        boundingBox?:
          type: DD-T.BoundingBox
        locationName?:
          type: DD-T.LocationName
        nodeId?:
          type: DD-T.Identifier
          description: This query parameter is deprecated.
        locationCode?:
          type: DD-T.LocationCode
        locationId?:
          type: DD-T.Identifier
      responses:
        200:
          description: Succesfully retrieved resource.
          body:
            application/json:
              type: DD-RESP.LocationListResponse
              example: !include examples/dd-locationslist-response.json

    /geojson:
      get:
        description: |
          Retrieve location resources. Response is in GeoJSON FeatureCollection format (see https://tools.ietf.org/html/rfc7946#page-12).
        is: [ TRAITS.pageable, TRAITS.has400-InvalidRequestError, TRAITS.has403-AccessDeniedError, TRAITS.has500-ServerError, TRAITS.locationFilterable ]
        queryParameters:
          process?:
            type: DD-T.ProcessName
          boundingBox?:
            type: DD-T.BoundingBox
          locationName?:
            type: DD-T.LocationName
          nodeId?:
            type: DD-T.Identifier
            description: This query parameter is deprecated.
          locationCode?:
            type: DD-T.LocationCode
          locationId?:
            type: DD-T.Identifier
        responses:
          200:
            description: Succesfully retrieved resource.
            body:
              application/json:
                type: DD-RESP.LocationListResponseGeoJSON
                example: !include examples/dd-locationslist-response-geojson.json

    /{locationId}:
      description: Request a specific location by its id. Response is always in GeoJSON Feature format (see https://tools.ietf.org/html/rfc7946#page-11).
      uriParameters:
        locationId:
          type: DD-T.Identifier
      is: [ TRAITS.has403-AccessDeniedError, TRAITS.has404-NotFoundError, TRAITS.has500-ServerError ]
      get:
        description: |
          Request a specific Location by its unique dentifier.
        queryParameters:
          process?:
            type: DD-T.ProcessName
            default: measurement
        responses:
          200:
            description: |
              Succesfully retrieved resource
            body:
              application/json:
                type: object
                example: !include examples/dd-location-response-geojson.json

######################################################

  /observationTypes:
    get:
      description: |
        ObservationType objects describe all attributes to correctly interpret what has been measured, and in what way. It is essential to have the quantity field.
      is: [ TRAITS.pageable, TRAITS.has400-InvalidRequestError, TRAITS.has403-AccessDeniedError, TRAITS.has500-ServerError, TRAITS.observationTypeFilterable ]
      queryParameters:
        process?:
          type: DD-T.ProcessName
        observationTypeId?:
          type: DD-T.Identifier
        quantity?:
          description: Retrieve only observation types that contain the specified quantity.
          type: string
        parameterCode?:
          description: Retrieve only observation types that contain the specified parameter code.
          type: string
      responses:
        200:
          description: |
            Succesfully retrieved timeseries.
          body:
            application/json:
              type: DD-RESP.ObservationTypeListResponse
              example: !include examples/dd-observationtypelist-response.json

    /{observationTypeId}:
      is: [ TRAITS.has403-AccessDeniedError, TRAITS.has404-NotFoundError, TRAITS.has500-ServerError ]
      uriParameters:
        observationTypeId:
          type: DD-T.Identifier
      get:
        description: Request a specific ObservationType by its unique identifier.
        queryParameters:
          process?:
            type: DD-T.ProcessName
        responses:
          200:
            description: |
              Succesfully retrieved resource.
            body:
              application/json:
                type: DD-RESP.ObservationTypeResponse
                example: !include examples/dd-observationtype-response.json

######################################################

  /timeseries:
    get:
      description: |
        TimeSeriesType objects describe the type of measurement the timeseries contains. These can be for example raw measurements, but also aggregations or simulations. This information could be needed to correctly interpret the measurement values.
        A request where both startTime and endTime are omitted returns a response with just the metadata.
      is: [ TRAITS.pageable, TRAITS.has400-InvalidRequestError, TRAITS.has403-AccessDeniedError, TRAITS.has500-ServerError, TRAITS.timeseriesFilterable, TRAITS.locationFilterable, TRAITS.observationTypeFilterable ]
      queryParameters:
        process?:
          type: DD-T.ProcessName
        startTime?:
          type: DD-T.StartTime
        endTime?:
          type: DD-T.EndTime
        locationCode?:
          type: DD-T.LocationCode
        locationName?:
          type: DD-T.LocationName
        sourceName?:
          type: DD-T.SourceName
        observationTypeId?:
          type: DD-T.Identifier
        realizationCount?:
          description: Added Count as this is the name in ObservationType response.
          type: integer
        parameterCode?:
          description: Implementation is optional. Preferably to be implemented by means of the generic filtering mechanism.
          type: string
        quantity?:
          description: Implementation is optional. Preferably to be implemented by means of the generic filtering mechanism.
          type: string
        valueType?:
          description: Value type (float, integer, categorized).
          type: string
        nodeId?:
          type: DD-T.Identifier
        qualifier?:
          description: Filter for the optional qualifier property.
          type: string
        aspectSet?:
          type: DD-T.AspectSetName
          description: Remark: Only required for systems that implement aspect sets
        quantityName?:
          type: DD-T.QuantityName
          description: Remark: Only required for systems that are accessed by RWS's MKK-DL
        intervalLength?:
          type: DD-T.IntervalLength
          description: Remark: Only required for systems that are accessed by RWS's MKK-DL
      responses:
        200:
          description: |
            Succesfully retrieved timeseries.
          body:
            application/json:
              type: DD-RESP.TimeseriesListResponse
              example: !include examples/dd-timeserieslist-response-verwachtingen-en-metingen-fulldd.json

    /{timeseriesId}:
      uriParameters:
        timeseriesId:
          type: DD-T.Identifier
      is: [ TRAITS.has403-AccessDeniedError, TRAITS.has404-NotFoundError, TRAITS.has500-ServerError ]
      get:
        description: Request a specific (single) Timeseries by its unique identifier.
        queryParameters:
          process?:
            type: DD-T.ProcessName
            default: measurement
        responses:
          200:
            description: |
              Succesfully retrieved resource
            body:
              application/json:
                type: DD-RESP.TimeseriesResponse
                example: !include examples/dd-timeseries-response-single.json


including authors in the article JSON content

schemas:
 - article: |
    {
      "type": "object",
      "properties": {
        "title": {
          "type": "string",
          "required": true,
          "minLength": 3,
          "maxLength": 200
        },
        "descriptionText": {
          "type": "string",
          "required": false,
          "minLength": 3,
          "maxLength": 500
        },
        "descriptionMedia": {
          "type": "object",
          "required": false,
          "schema" : picture
        },
        "isDraft": {
          "type": "boolean",
          "required": false
        },
        "authorUsers": {
          "type": "array",
          "required": false,
          "schema" : authorUser
        }
      }
    }
 - picture: |
    {
      "type": "object",
      "properties": {
        "id": {
          "type": "number",
          "required": false
        },
        "title": {
          "type": "string",
          "required": false,
          "minLength": 3,
          "maxLength": 200
        },
        "url": {
          "type": "string",
          "required": false,
          "minLength": 3,
          "maxLength": 100
        }
      }
    }
 - authorUser: |
    {
      "type": "object",
      "properties": {
        "id": {
          "type": "number",
          "required": false
        },
        "name": {
          "type": "string",
          "required": false,
          "minLength": 3,
          "maxLength": 200
        },
        "role": {
          "type": "string",
          "required": false,
          "minLength": 5,
          "maxLength": 10
        }
      }
    }

schemas:
 - article: |
    {
      "type": "object",
      "properties": {
        "title": {
          "type": "string",
          "required": true,
          "minLength": 3,
          "maxLength": 200
        },
        "descriptionText": {
          "type": "string",
          "required": false,
          "minLength": 3,
          "maxLength": 500
        },
        "descriptionMedia": {
          "type": "object",
          "required": false,
          "schema" : picture
        },
        "isDraft": {
          "type": "boolean",
          "required": false
        },
        "authorUserIds": {
          "type": "array",
          "required": false
        }
      }
    }
 - picture: |
    {
      "type": "object",
      "properties": {
        "id": {
          "type": "number",
          "required": false
        },
        "title": {
          "type": "string",
          "required": false,
          "minLength": 3,
          "maxLength": 200
        },
        "url": {
          "type": "string",
          "required": false,
          "minLength": 3,
          "maxLength": 100
        }
      }
    }


updated raml model

updated raml model

#%RAML 1.0
title: Jetlag Articles API
version: v0.1
baseUri: /api/0.1/
mediaType:  application/json
types:
    Gist:  !include types/gist.raml
    Gists: !include types/gists.raml
    collection: !include typed/collection.raml
resourceTypes:
traits:
/articles:
  get:
  post:
    body:
      application/json
        title: string
        descriptionText: string
        authorUserIds: array of numbers
        isDraft: boolean
        descriptionMedia:
          url: string
          title: string
          id: number
  /{articleId}:
    get:
    put:
    delete:

#%RAML 1.0
title: Jetlag Articles API
version: v0.1
baseUri: /api/0.1/
mediaType:  application/json
types:
    Gist:  !include types/gist.raml
    Gists: !include types/gists.raml
    collection: !include typed/collection.raml
resourceTypes:
traits:
/articles:
  get:
  post:
    body:
      application/json
        title: string
        descriptionText: string
        authorId: number
        descriptionPicture:
          url: string

  /{articleId}:
    get:
    put:
    delete: