trying English description

trying English description

#%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 lets you query for shipping methods for your shipments. If you request applicable shipping methods with all 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 methods, meaning that the actual response can be shown in a web-shop checkout without any sorting or filtering and with human readable service 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 which was always confusing for clients. This has been simplified in 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): New version of API gives ability to handle error in 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 product and along with multiple customer number in a single REST request. [How?](/api/shipping-guide_2/#get-shipment-prices-and-estimated-delivery)
      * [New restructured service models](): New product codes as part of Posten and Bring restructuring will be supported on new version only. More details on restructuring coming soon.

      ### 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](/api/shipping-guide_2/upgrade-to-version-2) will help you on your way to version 2 of the Shipping Guide API.

- title: Getting started
  content: |
      This guide will walk you through getting shipment methods 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 services `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
      * [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 service `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:RequestProperties>
                      <ns:Language>no</ns:Language>
                      <ns:Trace>true</ns:Trace>
                  </ns:RequestProperties>
                  <ns:Consignments>
                      <ns:Consignment consignmentId="101">
                          <ns:ProductIds>
                              <ns:ProductId>SERVICEPAKKE</ns:ProductId>
                              <ns:ProductId>PA_DOREN</ns:ProductId>
                          </ns:ProductIds>
                          <ns:FromCountryCode>NO</ns:FromCountryCode>
                          <ns:FromPostalCode>0015</ns:FromPostalCode>
                          <ns:ToCountryCode>NO</ns:ToCountryCode>
                          <ns:ToPostalCode>5518</ns:ToPostalCode>
                          <ns:ShippingDate>
                              <ns:Year>2018</ns:Year>
                              <ns:Month>10</ns:Month>
                              <ns:Day>10</ns:Day>
                          </ns:ShippingDate>
                          <ns:Packages>
                              <ns:Package>
                                  <ns:Height>19</ns:Height>
                                  <ns:Width>12</ns:Width>
                                  <ns:Length>30</ns:Length>
                                  <ns:GrossWeight>120</ns:GrossWeight>
                              </ns:Package>
                              <ns:Package>
                                  <ns:Height>30</ns:Height>
                                  <ns:Width>15</ns:Width>
                                  <ns:Length>22</ns:Length>
                                  <ns:GrossWeight>240</ns:GrossWeight>
                              </ns:Package>
                          </ns:Packages>
                      </ns:Consignment>
                  </ns:Consignments>
              </ns:ShippingGuideRequest>
          </soapenv:Body>
      </soapenv:Envelope>
      ```

      ### 5. Submit the request

      Post at:

      ```

        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:TraceMessages>
                      <ns2:Message>Defaulting to current time of day as no hour and minute component present in date time element.</ns2:Message>
                      <ns2:Message>Added fee 'brev-varsling' (NOK 13.00) to base price of SERVICEPAKKE since request did not have additional service 'eVarsling' specified.</ns2:Message>
                  </ns2:TraceMessages>
                  <ns2:Consignments>
                      <ns2:Consignment consignmentId="101">
                          <ns2:Products>
                              <ns2:Product>
                                  <ns2:ProductId>SERVICEPAKKE</ns2:ProductId>
                                  <ns2:ProductCodeInProductionSystem>1202</ns2:ProductCodeInProductionSystem>
                                  <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:Tip/>
                                      <ns2:MaxWeightInKgs>35</ns2:MaxWeightInKgs>
                                  </ns2:GuiInformation>
                                  <ns2:Price currencyIdentificationCode="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: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:ProductId>PA_DOREN</ns2:ProductId>
                                  <ns2:ProductCodeInProductionSystem>1736</ns2:ProductCodeInProductionSystem>
                                  <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:Tip/>
                                      <ns2:MaxWeightInKgs>35</ns2:MaxWeightInKgs>
                                  </ns2:GuiInformation>
                                  <ns2:Price currencyIdentificationCode="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:Price>
                                  <ns2:ExpectedDelivery>
                                      <ns2:WorkingDays/>
                                      <ns2:UserMessage>Ingen fremsendingstidsgaranti for oppgitt tilpostnummer.</ns2:UserMessage>
                                      <ns2:FormattedExpectedDeliveryDate/>
                                      <ns2:AlternativeDeliveryDates/>
                                      <ns2:FormattedEarliestPickupDate/>
                                  </ns2:ExpectedDelivery>
                              </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 a service 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-2.0.xsd) and [WDSL](https://api.bring.com/shippingguide/api/ws/shippingguide-2.0.wsdl) itself, making it easier for clients to parse it.

- title: Request and response structure
  content: |
      If you request shipping methods 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. The client framework used by client must not crash when unknown elements 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 services needed since the response time of some services can be slow as compared to others
      * If the request is only to find the lead time / prices of different services, the flag for withExpectedDelivery / withPrices should be set to true and others can be set to false
      * 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/services:
  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
      Content-Type:
        description: The API key needed to create a new job
    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 services 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
      additional:
        displayName: Additional service
        description: Multiple additional services can be requested by repeating this parameter
        required: false
        type: string
      service:
        description: Multiple services can be requested by repeating this parameter
        type: string
        required: true
      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 service 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

    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/services/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/services/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
      Content-Type:
        description: The API key needed to create a new job

#%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 lets you query for shipping methods for your shipments. If you request applicable shipping methods with all 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 methods, meaning that the actual response can be shown in a web-shop checkout without any sorting or filtering and with human readable service 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 which was always confusing for clients. This has been simplified in 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): New version of API gives ability to handle error in 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 product and along with multiple customer number in a single REST request. [How?](/api/shipping-guide_2/#get-shipment-prices-and-estimated-delivery)
      * [New restructured service models](): New product codes as part of Posten and Bring restructuring will be supported on new version only. More details on restructuring coming soon.

      ### 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](/api/shipping-guide_2/upgrade-to-version-2) will help you on your way to version 2 of the Shipping Guide API.

- title: Getting started
  content: |
      This guide will walk you through getting shipment methods 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 services `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
      * [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 service `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:RequestProperties>
                      <ns:Language>no</ns:Language>
                      <ns:Trace>true</ns:Trace>
                  </ns:RequestProperties>
                  <ns:Consignments>
                      <ns:Consignment consignmentId="101">
                          <ns:ProductIds>
                              <ns:ProductId>SERVICEPAKKE</ns:ProductId>
                              <ns:ProductId>PA_DOREN</ns:ProductId>
                          </ns:ProductIds>
                          <ns:FromCountryCode>NO</ns:FromCountryCode>
                          <ns:FromPostalCode>0015</ns:FromPostalCode>
                          <ns:ToCountryCode>NO</ns:ToCountryCode>
                          <ns:ToPostalCode>5518</ns:ToPostalCode>
                          <ns:ShippingDate>
                              <ns:Year>2018</ns:Year>
                              <ns:Month>10</ns:Month>
                              <ns:Day>10</ns:Day>
                          </ns:ShippingDate>
                          <ns:Packages>
                              <ns:Package>
                                  <ns:Height>19</ns:Height>
                                  <ns:Width>12</ns:Width>
                                  <ns:Length>30</ns:Length>
                                  <ns:GrossWeight>120</ns:GrossWeight>
                              </ns:Package>
                              <ns:Package>
                                  <ns:Height>30</ns:Height>
                                  <ns:Width>15</ns:Width>
                                  <ns:Length>22</ns:Length>
                                  <ns:GrossWeight>240</ns:GrossWeight>
                              </ns:Package>
                          </ns:Packages>
                      </ns:Consignment>
                  </ns:Consignments>
              </ns:ShippingGuideRequest>
          </soapenv:Body>
      </soapenv:Envelope>
      ```

      ### 5. Submit the request

      Post at:

      ```

        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:TraceMessages>
                      <ns2:Message>Defaulting to current time of day as no hour and minute component present in date time element.</ns2:Message>
                      <ns2:Message>Added fee 'brev-varsling' (NOK 13.00) to base price of SERVICEPAKKE since request did not have additional service 'eVarsling' specified.</ns2:Message>
                  </ns2:TraceMessages>
                  <ns2:Consignments>
                      <ns2:Consignment consignmentId="101">
                          <ns2:Products>
                              <ns2:Product>
                                  <ns2:ProductId>SERVICEPAKKE</ns2:ProductId>
                                  <ns2:ProductCodeInProductionSystem>1202</ns2:ProductCodeInProductionSystem>
                                  <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:Tip/>
                                      <ns2:MaxWeightInKgs>35</ns2:MaxWeightInKgs>
                                  </ns2:GuiInformation>
                                  <ns2:Price currencyIdentificationCode="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: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:ProductId>PA_DOREN</ns2:ProductId>
                                  <ns2:ProductCodeInProductionSystem>1736</ns2:ProductCodeInProductionSystem>
                                  <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:Tip/>
                                      <ns2:MaxWeightInKgs>35</ns2:MaxWeightInKgs>
                                  </ns2:GuiInformation>
                                  <ns2:Price currencyIdentificationCode="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:Price>
                                  <ns2:ExpectedDelivery>
                                      <ns2:WorkingDays/>
                                      <ns2:UserMessage>Ingen fremsendingstidsgaranti for oppgitt tilpostnummer.</ns2:UserMessage>
                                      <ns2:FormattedExpectedDeliveryDate/>
                                      <ns2:AlternativeDeliveryDates/>
                                      <ns2:FormattedEarliestPickupDate/>
                                  </ns2:ExpectedDelivery>
                              </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 a service 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-2.0.xsd) and [WDSL](https://api.bring.com/shippingguide/api/ws/shippingguide-2.0.wsdl) itself, making it easier for clients to parse it.

- title: Request and response structure
  content: |
      If you request shipping methods 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. The client framework used by client must not crash when unknown elements 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 services needed since the response time of some services can be slow as compared to others
      * If the request is only to find the lead time / prices of different services, the flag for withExpectedDelivery / withPrices should be set to true and others can be set to false
      * 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/services:
  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
      Content-Type:
        description: The API key needed to create a new job
    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 services 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
      additional:
        displayName: Additional service
        description: Multiple additional services can be requested by repeating this parameter
        required: false
        type: string
      service:
        description: Multiple services can be requested by repeating this parameter
        type: string
        required: true
      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 service 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: Leveringsbetingelser
        type: string
        example: EXW
        required: false
      unnumber:
        description: Kode for farlig gods
        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/services/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/services/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
      Content-Type:
        description: The API key needed to create a new job


api: Refactoring /reports and /builds

api: Refactoring /reports and /builds

#%RAML 0.8
---
title: Coverit
version: 0.0.1
baseUri: http://api.coverit.io/
mediaType:  application/json
securedBy: [oauth_2_0]

documentation:
    - title: Objects
      content: !include README.md

securitySchemes:
    - oauth_2_0: !include http://raml.link/securitySchemes/oauth_2_0.yml

/upload:
    displayName: Upload coverage report
    post:
        description: |
            Upload coverage report
        body:
            application/x-www-form-urlencoded:
                formParameters:
                    token:
                        description: Repo Token
                        type: string
                        required: true
                        example: AFNetworking/AFNetworking
                    report:
                        description: Report file, it's type should carried in `Content-Type`
                        type: file
                    git_commit:
                        description: Git commit sha in 10 chars
                        type: string
                        required: true
                        example: 09b26bf784
                    git_branch:
                        description: Git branch
                        type: string
                        required: true
                        example: master

/builds:
    displayName: Build
    /{build_id}:
        uriParameters:
            build_id:
                description: Build ID
                type: string
                example: '4ed2b809d7446b9a0e000014'
        get:
            description: |
                Get build info
            responses:
                200:
                    body:
                        schema: |
                            _id: string
                            git:
                                branch: string
                                commit: string
                                date: time
                                commiter: string
                                type: string
                            platform: string
                            coverage: int
                            reports: [string]

/reports:
    displayName: Report
    /{report_id}:
        uriParameters:
            report_id:
                description: Report ID
                type: string
                example: '4ed2b809d7446b9a0e000014'
        get:
            description: |
                Get report
            responses:
                200:
                    body:
                        schema: |
                            _id: string
                            user: string
                            project: string
                            build:
                                git:
                                    commit: string
                                    branch: string
                                    date: time
                            files: [
                                name: string
                                coverage: int
                                lines: int
                                hit: int
                            ]

        /{file_name}:
            uriParameters:
                file_name:
                    description: File name
                    type: string
                    example: 'coverit/main.go'
            get:
                description: |
                    Get source level coverage info
                responses:
                    200:
                        body:
                            schema: |
                                user: string
                                project: string
                                file: string
                                source: string
                                line_coverage: [
                                    line_no: int
                                    hit: int
                                ]
                                coverage: int
                                lines: int

#%RAML 0.8
---
title: Coverit
version: 0.0.1
baseUri: http://api.coverit.io/
mediaType:  application/json
securedBy: [oauth_2_0]

documentation:
    - title: Objects
      content: !include README.md

securitySchemes:
    - oauth_2_0: !include http://raml.link/securitySchemes/oauth_2_0.yml

/upload:
    displayName: Upload coverage report
    post:
        description: |
            Upload coverage report
        body:
            application/x-www-form-urlencoded:
                formParameters:
                    token:
                        description: Repo Token
                        type: string
                        required: true
                        example: AFNetworking/AFNetworking
                    report:
                        description: Report file, it's type should carried in `Content-Type`
                        type: file
                    git_commit:
                        description: Git commit sha in 10 chars
                        type: string
                        required: true
                        example: 09b26bf784
                    git_branch:
                        description: Git branch
                        type: string
                        required: true
                        example: master

/builds:
    displayName: Build
    post:
        description: |
            Create a new build
        body:
            application/x-www-form-urlencoded:
                formParameters:
                    project_name:
                        description: Project name
                        type: string
                        required: true
                        example: AFNetworking/AFNetworking
                    gcno:
                        description: gcno files archive
                        type: file
                        required: true
                    git:
                        description: A hash of Git data that can be used to display more information to users.
                        type: string
                        example: '
                            "git": {
                              "head": {
                                "id": "b31f08d07ae564b08237e5a336e478b24ccc4a65",
                                "author_name": "Nick Merwin",
                                "author_email": "...",
                                "committer_name": "Nick Merwin",
                                "committer_email": "...",
                                "message": "version bump"
                              },
                              "branch": "master",
                              "remotes": [
                                {
                                  "name": "origin",
                                  "url": "git@github.com:lemurheavy/coveralls-ruby.git"
                                }
                              ]
                            }'

/reports:
    displayName: Report
    post:
        description: |
            Create a new report
        body:
            application/x-www-form-urlencoded:
                formParameters:
                    project_name:
                        description: Project name
                        type: string
                        required: true
                        example: AFNetworking/AFNetworking
                    lcov:
                        description: lcov file
                        type: file
                        required: true
                    git:
                        description: A hash of Git data that can be used to display more information to users.
                        type: string
                        example: '
                            "git": {
                              "head": {
                                "id": "b31f08d07ae564b08237e5a336e478b24ccc4a65",
                                "author_name": "Nick Merwin",
                                "author_email": "...",
                                "committer_name": "Nick Merwin",
                                "committer_email": "...",
                                "message": "version bump"
                              },
                              "branch": "master",
                              "remotes": [
                                {
                                  "name": "origin",
                                  "url": "git@github.com:lemurheavy/coveralls-ruby.git"
                                }
                              ]
                            }'


Rename from Tracking Webhook to Event Cast

+ tweak the intro in the documentation

#%RAML 1.0
---
title: Event Cast API
version: v1
baseUri: https://api.bring.com/event-cast
mediaType: application/json
annotationTypes:
  hideInDocumentation: boolean
  hideRequired: boolean
types:
  WebhookRequest:
    type: object
    properties:
      trackingId:
        type: string
        required: true
      event_groups:
        type: string
        required: true
      configuration:
        type: Configuration
        required: true
  WebhookBatchRequest:
      type: object
      properties:
        trackingIds:
          type: string[]
          required: true
        event_groups:
          type: string
          required: true
        configuration:
          type: Configuration
          required: true
  Webhook:
    type: object
    properties:
      id:
        type: string
        required: false
        description: Represents an unique identifiaction
      authenticator:
        type: string
        required: false
        description: Represents your authentication identification
      trackingId:
        type: string
        required: true
      event_groups:
        type: string
        required: true
        description: Represents the group(s) that is part of this Webhook
      expiry:
        type: datetime
        required: false
        description: TimeZone is set to UTC. Use this format to parse the instant; `yyyy-MM-dd'T'HH:mm:ssZ`
      created:
        type: datetime
        required: false
        description: TimeZone is set to UTC. Use this format to parse the instant; `yyyy-MM-dd'T'HH:mm:ssZ`
      configuration:
        type: Configuration
        required: true
  Configuration:
    type: object
    properties:
      url:
        type: string
        required: true
      content_type:
        type: string
        required: false
      headers:
        type: ConfigurationHeader[]
        required: false
  ConfigurationHeader:
    type: object
    properties:
      key:
        type: string
        required: true
      value:
        type: string
        required: true
        description: This value will not be available in any response
  ErrorResponse:
    type: object
    properties:
      uuid:
        type: string
        description: This represents an unique identifier for the failing request. Can be used whilst contacting Bring
      status:
        type: string
        description: Represents a 3/4 digit code that can be used to identify the problem
      reason:
        type: string
        required: false
        description: Can contain some hints on what went wrong during the request

documentation:
- title: Introduction
  content: |

    The Tracking API provides the opportunity to track shipments by reference, package or shipment number. If you are interested in when a shipment is picket up by the recipient
    or some other event has happened, then it's better to be told when something happens instead of polling the current status.

    The Event Cast API makes you subscribe to such events using Webhooks.

    #### Webohook Definition
    > A Webhook in web development is a method of augmenting or altering the behaviour of a web page, or web application, with custom callbacks.
    > These callbacks may be maintained, modified, and managed by third-party users and developers who may not necessarily be affiliated with the originating website or application.

    #### Webhooks in Bring
    In the context of Bring, this means that whenever an event is registered in Bring for a subscribed parcel and/or shipment,
    we'll send a HTTP POST to your callback URL that were defined during the Webhook registration.

    Using Webhooks is quite simple, and allows for immediate feedback based on the event that occured for the subscribed entity.
    Additionally, it allows integrations of customers to become simpler, as no scheduled mechanism is required to be implemented.
    You basically just define an endpoint that accepts HTTP POST, and the event details will be sent there - quite amazing 🙌
- title: Authentication
  content: |
    In order to use the API, you will need to register with Mybring and create an API key. Whenever issuing a request, the following headers is required to be present.

    | Header | Example | Comment | Required |
    |:-------|:--------|:--------|
    | `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 you | |

    **Note:** See the [getting started guide on authentication](/api/#authentication) if you want to know more about how to get started with authentication for APIs in Mybring.
- title: API limitations
  content: |
    There is some known/deliberate limitations for the API:

    | Resource | Limitation description |
    |:--------|:---------|
    | All requests | The Webhook API allows a maximum of **50 concurrent requests** per user |
    | Batch creation | Whilst creating requests for Webhooks is a feature we encurage to use, its maximum amount of parcels and/or shipments is limited to **100 per request**. If you have more than 100 at the time, split to mulitple requests using the batch-API |
    | Webhook testing | The `/api/v1/Webhooks/{WebhookId}/test`-api allows a maximum of **10 concurrent requests** per user |
- title: Events
  content: |
    When registering for a Webhook you can choose between a range of different event groups that you can subscribe for.
    It is recommended to limit the amount of events to subscribe for. Bring will send an event on each of the events occurred which in result may send quite a few HTTP-requests to your server.
    So, as a good practise, keep the list of event groups as small as possible.

    Each of the event groups corresponds to a certain set of actions that can happen to the package/shipment you subscribe for. For instance, if you subscribe to `DELIVERED`, all internal Bring-events
    will trigger a request to your defined callback URL.

    #### Event groups

    Default set of subscribeable event groups. Notice that this list is subject for change.

    | Event | Description |
    |:-------|:--------|
    | `ARRIVED_DELIVERY` | Arrived Delivery point - This is when a container arrives at recipients address, and can start unloading.
 |
    | `ARRIVED_COLLECTION` | Arrived for collection at pickup point |
    | `ATTEMPTED_DELIVERY` | The package has been attempted delivered at the door. Depending on the service it will be tried again or sent to closest pickup point. |
    | `CUSTOMS` | Package is in customs clearance. |
    | `COLLECTED` | The parcel has been collected at pickup address. |
    | `DELIVERED` | Package has been delivered. |
    | `DELIVERED_SENDER` | Package has been returned to the sender |
    | `DELIVERY_CANCELLED` | Home delivery has been canceled by the customer. |
    | `DELIVERY_CHANGED` | Date for Home delivery has been changed by customer. |
    | `DELIVERY_ORDERED` | Home delivery has been ordered |
    | `DEVIATION` | Deviation in production. Something wrong has happened and there is a probability for delay. |
    | `HANDED_IN` | Package has been handed in to Bring. |
    | `INTERNATIONAL` | Package has been sent from origin country or arrived at destination country.
 |
    | `IN_TRANSIT` | Package is in transit. |
    | `NOTIFICATION_SENT` | Notification for this package has been sent by sms, push and/or mail. This can be informational notifications and action notification like pickup notice. |
    | `PRE_NOTIFIED` | EDI message for the package has been received by Bring. |
    | `READY_FOR_PICKUP` | Package has arrived at pickup point. |
    | `RETURN` | The package has been returned to sender.
 |
    | `TRANSPORT_TO_RECIPIENT` | Package has been loaded for delivery to the recipient. |
    | `TERMINAL` | The package is now registered/arrived at inbound/outbound storage terminal |

    There is also a specific set of events that will be sent if something deviates from the normal event flow:

    | Event | Description |
    |:-------|:--------|
    | `NOT_REGISTERED` | Webhook not registered. This might be due to the parcel-/shipment-number not being found with Bring' systems and can trigger after up to two - 2 - days |
    | `EXPIRED` | Webhook expired |

    #### Subscribing to multiple event groups

    The Webhook API supports the possibility to subscribe to multiple event groups at the same time.
    Doing so requires that groups are separated with comma and is defined as an array.
    Example:

    ```
    ['IN_TRANSIT', 'NOTIFICATION_SENT', 'TERMINAL', .., ..]
    ```

    Need more examples? See the "Create Webhook" section below.

- title: Receiving Callbacks
  content: |
    In order to receive requests from Bring, your callback URL must be accessible on the internet and able to receive requests from Bring IPs.
    Additionally, to minimize risk, you should also provide HTTPS-enabled endpoints and use some kind of authentication mechanism.
    For HTTPS, please do not use self-signed certificates, as requests may fail from Bring' side and you'll receive no requests.

    If you need a simple authentication whilst receiving requests from Bring, we recommend utilizing the header functionality provided by the Webhook configuration.

    All received callbacks from Bring will be using **UTC** as its current timezone and is based on the following format (Java):

    ```
    "yyyy-MM-dd'T'HH:mm:ssZ"
    ```

- title: Payload
  content: |

    #### Payload delivery headers

    `HTTP POST` payloads that are delivered to your Webhook's configured URL endpoint contains several Bring specific headers:

    | Header | Description |
    |:-------|:--------|
    | `X-Bring-Application` | Identifies the application that sent the request to your endpoint |
    | `X-bring-Correlation` | Correlation Id can be used whilst contacting Bring on error cases |
    | `X-bring-Version` | Indicates the version of application |
    | `<your headers>` | Any headers that were specified in the Webhook configuration will also be appended |

    #### Example

    Requests issued from Bring to your endpoint will look similar to this:

    ```
      POST /callback/Webhook HTTP/1.1
      host: localhost:80
      Accept: application/json
      User-Agent: Bringcast-Webhook/v1.0.34-SNAPSHOT
      X-Bring-Application: BMEC
      X-bring-Correlation: xA3n7
      X-some-fancy-custom-header: with-some-value-that-I-expect
      Content-Type: application/json
      Content-Length: 188

      {
        "status": "IN_TRANSIT",
        "id": "ad84cbca-2e89-43e0-a301-a8d5d7fe7804",
        "shipment": "SHIPMENTNUMBER",
        "package": "TESTPACKAGEDELIVERED",
        "created": "2019-03-16T14:58:48+0000",
        "pushed": "2019-03-16T14:58:49+0000"
      }
    ```
- title: Q & A
  content: |

    #### Can I have multiple Webhooks for the same parcel?
    You can register for multiple Webhooks on the same parcel/shipment, as long as the event groups are different for each registration.

    #### How many active Webhooks can I have simultaneously?
    Currently there is no limitation.

    #### Is the expiration duration configurable?
    No.

    #### Can I get a history of events that were sent for a subscription?
    Not in this version. It may be available in the future.

    #### Will I be able to see my previous/expired Webhooks (active and inactive)?
    No.

    #### What happens if our endpoint is down and a callback is being sent?
    We'll try issuing a request to your defined endpoint up to three - 3 - times with a delay on 30 minutes for the two first, then wait an hour for the last retry.
    After this, callbacks will not be retried.

    #### Do you support wildcard events/event groups (e.g `*` or `ALL`)?
    No.

    #### Do you support modifying existing active webhooks?
    No.

    #### My shipment is not yet registered with Bring, will registering for Webhook work related to that tracking number?
    Yes.

    When you subscribe for a parcel that does not yet exist in Bring' systems, a retry mechanism will try for up to two - 2 - days to ensure that the Webhook will be registered when the parcel is found internally.
    Eventually, if the package was not found with Bring within this timeframe - a notification will be sent on the callback URL configured for that Webhook which notifies this.

    **Note**: Retry-timing is non-configurable.

/api/v1/webhooks:
  displayName: Create Webhook
  description: |
    Create a new subscription for a Webhook.
    Webhooks lives for up to 30 days, or until the entity subscribed for is marked as "delivered by Bring".
  post:
    description: Register a new Webhook subscription for a parcel or shipment
    body:
      application/json:
        type: WebhookRequest
        examples:
          valid_request:
            displayName: Valid Request
            value: !include examples/create-Webhook-request.json
    responses:
      201:
        description: Returns the registered Webhook after creation request.
        body:
          application/json:
            type: Webhook
            examples:
              reqister_Webhook:
                displayName: Registered Webhook
                value: !include examples/Webhook-request.json
      400:
        displayName: Bad request
        description: Unable to register Webhook due to some bad request from the client side.
        body:
          application/json:
            type: ErrorResponse
            examples:
              invalid_Webhook:
                displayName: Invalid creation request
                value: !include examples/create-Webhook-invalid.json
      401:
        displayName: Error
        description: Missing authentication headers
      409:
        displayName: Conflict
        description: Webhook of similar subscription already exists
      429:
        displayName: Too many requests
        description: This may happen due to client sending too many requests. Try again a bit later, or decrease amount of requests
      500:
        displayName: Internal Bring error
        description: If this happens, try again a bit later as it might be due to some internal mechanism not working
/batch/api/v1/webhooks:
  displayName: Create multiple Webhooks
  description: |
        Create a range of new Webhooks based on a list of any parcel or shipment.
        Webhooks lives for up to 30 days, or until the entity subscribed for is marked as "delivered by Bring".
  post:
    description: Register a new Webhook subscription for an array parcels and/or shipments
    body:
      application/json:
        type: WebhookBatchRequest
        examples:
          valid_request:
            displayName: Valid Request
            value: !include examples/batch-create-Webhook-request.json
    responses:
      201:
        description: |
          Returns the registered Webhook after creation request.
        body:
          application/json:
            type: Webhook
            examples:
              reqister_Webhook:
                displayName: Registered Webhook
                value: !include examples/batch-Webhook-request.json
      400:
        displayName: Bad request
        description: |
          Unable to register Webhook due to some bad request from the client side.
        body:
          application/json:
            type: ErrorResponse
            examples:
              invalid_Webhook:
                displayName: Invalid creation request
                value: !include examples/create-Webhook-invalid.json
      401:
        displayName: Error
        description: Missing authentication headers
      429:
        displayName: Too many requests
        description: This may happen due to client sending too many requests. Try again a bit later, or decrease amount of requests
      500:
        displayName: Internal Bring error
        description: If this happens, try again a bit later as it might be due to some internal mechanism not working
/api/v1/webhooks/{Webhookid}:
  displayName: Delete Webhook
  uriParameters:
    Webhookid:
      displayName: WebhookId
      type: string
      description: This represents the specific identifier of the Webhook
  delete:
    description: Remove an existing subscribed Webhook
    queryParameters:
      includeWebhook:
        description: If set to true, the deleted Webhook will be returned
        type: boolean
        required: false
        example: true
    responses:
      200:
        body:
          application/json:
            type: Webhook
            examples:
              get_Webhook:
                displayName: Registered Webhook
                value: !include examples/Webhook-request.json
      204:
        displayName: Webhook successfully removed
        description: Webhook unregistered and removed. No content supplied in response
      401:
        displayName: Error
        description: Missing authentication headers
      404:
        displayName: Error
        description: Webhook not found (not registered?)
/api/v1/webhooks/:
  displayName: Get all Webhooks
  get:
    description: Get all your current registered and active Webhooks. Pagination is currently not supported
    responses:
      200:
        body:
          application/json:
            type: Webhook
            examples:
              get_Webhook:
                displayName: Registered Webhook
                value: !include examples/webhook-request-all.json
      400:
        displayName: Bad request
        description: Unable to register Webhook due to some bad request from the client side.
        body:
          application/json:
            type: ErrorResponse
            examples:
              invalid_request:
                displayName: Invalid creation request
                value: !include examples/create-Webhook-invalid.json
      401:
        displayName: Error
        description: Missing authentication headers.
      404:
        displayName: Error
        description: Webhook not found (not registered?)
/api/v1/webhooks/{WebhookId}:
  displayName: Get single Webhook
  uriParameters:
    WebhookId:
      displayName: WebhookId
      type: string
      description: This represents the specific identifier of the Webhook
  get:
    description: Get the specification that belongs to a registered Webhook
    responses:
      200:
        body:
          application/json:
            type: Webhook
            examples:
              get_Webhook:
                displayName: Registered Webhook
                value: !include examples/Webhook-request.json
      400:
        displayName: Bad request
        description: Unable to register Webhook due to some bad request from the client side.
        body:
          application/json:
            type: ErrorResponse
            examples:
              invalid_request:
                displayName: Invalid creation request
                value: !include examples/create-Webhook-invalid.json
      401:
        displayName: Error
        description: Missing authentication headers
      404:
        displayName: Error
        description: Webhook not found (not registered?)
/api/v1/webhooks/{WebhookId}/test:
  displayName: Test a push Webhook
  description: |
    This will trigger a Webhook to receive a dummy request to the registered Webhook.

    **Note**: There is no retry mechanism in place for this, so if a request fails for some reason, it will go on un-noticed.
  uriParameters:
    WebhookId:
      displayName: WebhookId
      type: string
      description: This represents the specific identifier of the Webhook
  post:
    description: Test the Webhook service with the provided Webhook identifier
    responses:
      202:
        displayName: Accepted
        description: The request have been registered, and a dummy-request will be sent to the registered Webhook
      401:
        displayName: Error
        description: Missing authentication headers
      404:
        displayName: Error
        description: Webhook not found (not registered?)

#%RAML 1.0
---
title: Tracking Webhook API
version: v1
baseUri: https://api.bring.com/event-cast
mediaType: application/json
annotationTypes:
  hideInDocumentation: boolean
  hideRequired: boolean
types:
  WebhookRequest:
    type: object
    properties:
      trackingId:
        type: string
        required: true
      event_groups:
        type: string
        required: true
      configuration:
        type: Configuration
        required: true
  WebhookBatchRequest:
      type: object
      properties:
        trackingIds:
          type: string[]
          required: true
        event_groups:
          type: string
          required: true
        configuration:
          type: Configuration
          required: true
  Webhook:
    type: object
    properties:
      id:
        type: string
        required: false
        description: Represents an unique identifiaction
      authenticator:
        type: string
        required: false
        description: Represents your authentication identification
      trackingId:
        type: string
        required: true
      event_groups:
        type: string
        required: true
        description: Represents the group(s) that is part of this Webhook
      expiry:
        type: datetime
        required: false
        description: TimeZone is set to UTC. Use this format to parse the instant; `yyyy-MM-dd'T'HH:mm:ssZ`
      created:
        type: datetime
        required: false
        description: TimeZone is set to UTC. Use this format to parse the instant; `yyyy-MM-dd'T'HH:mm:ssZ`
      configuration:
        type: Configuration
        required: true
  Configuration:
    type: object
    properties:
      url:
        type: string
        required: true
      content_type:
        type: string
        required: false
      headers:
        type: ConfigurationHeader[]
        required: false
  ConfigurationHeader:
    type: object
    properties:
      key:
        type: string
        required: true
      value:
        type: string
        required: true
        description: This value will not be available in any response
  ErrorResponse:
    type: object
    properties:
      uuid:
        type: string
        description: This represents an unique identifier for the failing request. Can be used whilst contacting Bring
      status:
        type: string
        description: Represents a 3/4 digit code that can be used to identify the problem
      reason:
        type: string
        required: false
        description: Can contain some hints on what went wrong during the request

documentation:
- title: Introduction
  content: |

    #### Webohook Definition
    > A Webhook in web development is a method of augmenting or altering the behaviour of a web page, or web application, with custom callbacks.
    > These callbacks may be maintained, modified, and managed by third-party users and developers who may not necessarily be affiliated with the originating website or application.

    #### Webhooks in Bring
    In the context of Bring, Webhooks allows you to get notifications for the subscribed parcels and/or shipments.

    In essence, this means that whenever an event is registered in Bring for a subscribed parcel and/or shipment,
    we'll send a HTTP POST to your callback URL that were defined during the Webhook registration.

    Using Webhooks is quite simple, and allows for immediate feedback based on the event that occured for the subscribed entity.
    Additionally, it allows integrations of customers to become simpler, as no scheduled mechanism is required to be implemented.
    You basically just define an endpoint that accepts HTTP POST, and the event details will be sent there - quite amazing 🙌
- title: Authentication
  content: |
    In order to use the API, you will need to register with Mybring and create an API key. Whenever issuing a request, the following headers is required to be present.

    | Header | Example | Comment | Required |
    |:-------|:--------|:--------|
    | `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 you | |

    **Note:** See the [getting started guide on authentication](/api/#authentication) if you want to know more about how to get started with authentication for APIs in Mybring.
- title: API limitations
  content: |
    There is some known/deliberate limitations for the API:

    | Resource | Limitation description |
    |:--------|:---------|
    | All requests | The Webhook API allows a maximum of **50 concurrent requests** per user |
    | Batch creation | Whilst creating requests for Webhooks is a feature we encurage to use, its maximum amount of parcels and/or shipments is limited to **100 per request**. If you have more than 100 at the time, split to mulitple requests using the batch-API |
    | Webhook testing | The `/api/v1/Webhooks/{WebhookId}/test`-api allows a maximum of **10 concurrent requests** per user |
- title: Events
  content: |
    When registering for a Webhook you can choose between a range of different event groups that you can subscribe for.
    It is recommended to limit the amount of events to subscribe for. Bring will send an event on each of the events occurred which in result may send quite a few HTTP-requests to your server.
    So, as a good practise, keep the list of event groups as small as possible.

    Each of the event groups corresponds to a certain set of actions that can happen to the package/shipment you subscribe for. For instance, if you subscribe to `DELIVERED`, all internal Bring-events
    will trigger a request to your defined callback URL.

    #### Event groups

    Default set of subscribeable event groups. Notice that this list is subject for change.

    | Event | Description |
    |:-------|:--------|
    | `ARRIVED_DELIVERY` | Arrived Delivery point - This is when a container arrives at recipients address, and can start unloading.
 |
    | `ARRIVED_COLLECTION` | Arrived for collection at pickup point |
    | `ATTEMPTED_DELIVERY` | The package has been attempted delivered at the door. Depending on the service it will be tried again or sent to closest pickup point. |
    | `CUSTOMS` | Package is in customs clearance. |
    | `COLLECTED` | The parcel has been collected at pickup address. |
    | `DELIVERED` | Package has been delivered. |
    | `DELIVERED_SENDER` | Package has been returned to the sender |
    | `DELIVERY_CANCELLED` | Home delivery has been canceled by the customer. |
    | `DELIVERY_CHANGED` | Date for Home delivery has been changed by customer. |
    | `DELIVERY_ORDERED` | Home delivery has been ordered |
    | `DEVIATION` | Deviation in production. Something wrong has happened and there is a probability for delay. |
    | `HANDED_IN` | Package has been handed in to Bring. |
    | `INTERNATIONAL` | Package has been sent from origin country or arrived at destination country.
 |
    | `IN_TRANSIT` | Package is in transit. |
    | `NOTIFICATION_SENT` | Notification for this package has been sent by sms, push and/or mail. This can be informational notifications and action notification like pickup notice. |
    | `PRE_NOTIFIED` | EDI message for the package has been received by Bring. |
    | `READY_FOR_PICKUP` | Package has arrived at pickup point. |
    | `RETURN` | The package has been returned to sender.
 |
    | `TRANSPORT_TO_RECIPIENT` | Package has been loaded for delivery to the recipient. |
    | `TERMINAL` | The package is now registered/arrived at inbound/outbound storage terminal |

    There is also a specific set of events that will be sent if something deviates from the normal event flow:

    | Event | Description |
    |:-------|:--------|
    | `NOT_REGISTERED` | Webhook not registered. This might be due to the parcel-/shipment-number not being found with Bring' systems and can trigger after up to two - 2 - days |
    | `EXPIRED` | Webhook expired |

    #### Subscribing to multiple event groups

    The Webhook API supports the possibility to subscribe to multiple event groups at the same time.
    Doing so requires that groups are separated with comma and is defined as an array.
    Example:

    ```
    ['IN_TRANSIT', 'NOTIFICATION_SENT', 'TERMINAL', .., ..]
    ```

    Need more examples? See the "Create Webhook" section below.

- title: Receiving Callbacks
  content: |
    In order to receive requests from Bring, your callback URL must be accessible on the internet and able to receive requests from Bring IPs.
    Additionally, to minimize risk, you should also provide HTTPS-enabled endpoints and use some kind of authentication mechanism.
    For HTTPS, please do not use self-signed certificates, as requests may fail from Bring' side and you'll receive no requests.

    If you need a simple authentication whilst receiving requests from Bring, we recommend utilizing the header funcitonality provided by the Webhook configuration.

    All received callbacks from Bring will be using **UTC** as its current timezone and is based on the following format (Java):

    ```
    "yyyy-MM-dd'T'HH:mm:ssZ"
    ```

- title: Payload
  content: |

    #### Payload delivery headers

    `HTTP POST` payloads that are delivered to your Webhook's configured URL endpoint contains several Bring specific headers:

    | Header | Description |
    |:-------|:--------|
    | `X-Bring-Application` | Identifies the application that sent the request to your endpoint |
    | `X-bring-Correlation` | Correlation Id can be used whilst contacting Bring on error cases |
    | `X-bring-Version` | Indicates the version of application |
    | `<your headers>` | Any headers that were specified in the Webhook configuration will also be appended |

    #### Example

    Requests issued from Bring to your endpoint will look similar to this:

    ```
      POST /callback/Webhook HTTP/1.1
      host: localhost:80
      Accept: application/json
      User-Agent: Bringcast-Webhook/v1.0.34-SNAPSHOT
      X-Bring-Application: BMEC
      X-bring-Correlation: xA3n7
      X-some-fancy-custom-header: with-some-value-that-I-expect
      Content-Type: application/json
      Content-Length: 188

      {
        "status": "IN_TRANSIT",
        "id": "ad84cbca-2e89-43e0-a301-a8d5d7fe7804",
        "shipment": "SHIPMENTNUMBER",
        "package": "TESTPACKAGEDELIVERED",
        "created": "2019-03-16T14:58:48+0000",
        "pushed": "2019-03-16T14:58:49+0000"
      }
    ```
- title: Q & A
  content: |

    #### Can I have multiple Webhooks for the same parcel?
    You can register for multiple Webhooks on the same parcel/shipment, as long as the event groups are different for each registration.

    #### How many active Webhooks can I have simultaneously?
    Currently there is no limitation.

    #### Is the expiration duration configurable?
    No.

    #### Can I get a history of events that were sent for a subscription?
    Not in this version. It may be available in the future.

    #### Will I be able to see my previous/expired Webhooks (active and inactive)?
    No.

    #### What happens if our endpoint is down and a callback is being sent?
    We'll try issuing a request to your defined endpoint up to three - 3 - times with a delay on 30 minutes for the two first, then wait an hour for the last retry.
    After this, callbacks will not be retried.

    #### Do you support wildcard events/event groups (e.g `*` or `ALL`)?
    No.

    #### Do you support modifying existing active webhooks?
    No.

    #### My shipment is not yet registered with Bring, will registering for Webhook work related to that tracking number?
    Yes.

    When you subscribe for a parcel that does not yet exist in Bring' systems, a retry mechanism will try for up to two - 2 - days to ensure that the Webhook will be registered when the parcel is found internally.
    Eventually, if the package was not found with Bring within this timeframe - a notification will be sent on the callback URL configured for that Webhook which notifies this.

    **Note**: Retry-timing is non-configurable.

/api/v1/webhooks:
  displayName: Create Webhook
  description: |
    Create a new subscription for a Webhook.
    Webhooks lives for up to 30 days, or until the entity subscribed for is marked as "delivered by Bring".
  post:
    description: Register a new Webhook subscription for a parcel or shipment
    body:
      application/json:
        type: WebhookRequest
        examples:
          valid_request:
            displayName: Valid Request
            value: !include examples/create-Webhook-request.json
    responses:
      201:
        description: Returns the registered Webhook after creation request.
        body:
          application/json:
            type: Webhook
            examples:
              reqister_Webhook:
                displayName: Registered Webhook
                value: !include examples/Webhook-request.json
      400:
        displayName: Bad request
        description: Unable to register Webhook due to some bad request from the client side.
        body:
          application/json:
            type: ErrorResponse
            examples:
              invalid_Webhook:
                displayName: Invalid creation request
                value: !include examples/create-Webhook-invalid.json
      401:
        displayName: Error
        description: Missing authentication headers
      409:
        displayName: Conflict
        description: Webhook of similar subscription already exists
      429:
        displayName: Too many requests
        description: This may happen due to client sending too many requests. Try again a bit later, or decrease amount of requests
      500:
        displayName: Internal Bring error
        description: If this happens, try again a bit later as it might be due to some internal mechanism not working
/batch/api/v1/webhooks:
  displayName: Create multiple Webhooks
  description: |
        Create a range of new Webhooks based on a list of any parcel or shipment.
        Webhooks lives for up to 30 days, or until the entity subscribed for is marked as "delivered by Bring".
  post:
    description: Register a new Webhook subscription for an array parcels and/or shipments
    body:
      application/json:
        type: WebhookBatchRequest
        examples:
          valid_request:
            displayName: Valid Request
            value: !include examples/batch-create-Webhook-request.json
    responses:
      201:
        description: |
          Returns the registered Webhook after creation request.
        body:
          application/json:
            type: Webhook
            examples:
              reqister_Webhook:
                displayName: Registered Webhook
                value: !include examples/batch-Webhook-request.json
      400:
        displayName: Bad request
        description: |
          Unable to register Webhook due to some bad request from the client side.
        body:
          application/json:
            type: ErrorResponse
            examples:
              invalid_Webhook:
                displayName: Invalid creation request
                value: !include examples/create-Webhook-invalid.json
      401:
        displayName: Error
        description: Missing authentication headers
      429:
        displayName: Too many requests
        description: This may happen due to client sending too many requests. Try again a bit later, or decrease amount of requests
      500:
        displayName: Internal Bring error
        description: If this happens, try again a bit later as it might be due to some internal mechanism not working
/api/v1/webhooks/{Webhookid}:
  displayName: Delete Webhook
  uriParameters:
    Webhookid:
      displayName: WebhookId
      type: string
      description: This represents the specific identifier of the Webhook
  delete:
    description: Remove an existing subscribed Webhook
    queryParameters:
      includeWebhook:
        description: If set to true, the deleted Webhook will be returned
        type: boolean
        required: false
        example: true
    responses:
      200:
        body:
          application/json:
            type: Webhook
            examples:
              get_Webhook:
                displayName: Registered Webhook
                value: !include examples/Webhook-request.json
      204:
        displayName: Webhook successfully removed
        description: Webhook unregistered and removed. No content supplied in response
      401:
        displayName: Error
        description: Missing authentication headers
      404:
        displayName: Error
        description: Webhook not found (not registered?)
/api/v1/webhooks/:
  displayName: Get all Webhooks
  get:
    description: Get all your current registered and active Webhooks. Pagination is currently not supported
    responses:
      200:
        body:
          application/json:
            type: Webhook
            examples:
              get_Webhook:
                displayName: Registered Webhook
                value: !include examples/webhook-request-all.json
      400:
        displayName: Bad request
        description: Unable to register Webhook due to some bad request from the client side.
        body:
          application/json:
            type: ErrorResponse
            examples:
              invalid_request:
                displayName: Invalid creation request
                value: !include examples/create-Webhook-invalid.json
      401:
        displayName: Error
        description: Missing authentication headers.
      404:
        displayName: Error
        description: Webhook not found (not registered?)
/api/v1/webhooks/{WebhookId}:
  displayName: Get single Webhook
  uriParameters:
    WebhookId:
      displayName: WebhookId
      type: string
      description: This represents the specific identifier of the Webhook
  get:
    description: Get the specification that belongs to a registered Webhook
    responses:
      200:
        body:
          application/json:
            type: Webhook
            examples:
              get_Webhook:
                displayName: Registered Webhook
                value: !include examples/Webhook-request.json
      400:
        displayName: Bad request
        description: Unable to register Webhook due to some bad request from the client side.
        body:
          application/json:
            type: ErrorResponse
            examples:
              invalid_request:
                displayName: Invalid creation request
                value: !include examples/create-Webhook-invalid.json
      401:
        displayName: Error
        description: Missing authentication headers
      404:
        displayName: Error
        description: Webhook not found (not registered?)
/api/v1/webhooks/{WebhookId}/test:
  displayName: Test a push Webhook
  description: |
    This will trigger a Webhook to receive a dummy request to the registered Webhook.

    **Note**: There is no retry mechanism in place for this, so if a request fails for some reason, it will go on un-noticed.
  uriParameters:
    WebhookId:
      displayName: WebhookId
      type: string
      description: This represents the specific identifier of the Webhook
  post:
    description: Test the Webhook service with the provided Webhook identifier
    responses:
      202:
        displayName: Accepted
        description: The request have been registered, and a dummy-request will be sent to the registered Webhook
      401:
        displayName: Error
        description: Missing authentication headers
      404:
        displayName: Error
        description: Webhook not found (not registered?)