Update api.raml

Update api.raml

#%RAML 0.8
---
title: Pickup Point API
baseUri: https://api.bring.com/pickuppoint/api/pickuppoint

documentation:

        The Pickup Point API becomes authenticated from 01.11.2020

            Our customers are increasingly demanding new functionality and solutions that are easy to use. To meet these expectations, we must know which customers and partners are using our APIs and how they are using them.

            To further develop the value proposition of our Pickup Point API, the solution becomes authenticated from 01.11.2020.

            We recommend making the adjustment already now, well in advance of summer vacations and peak season.

- title: Introduction
  content: |
      The Pickup point API provides a list of locations for package pickup. Based on a specified postal code or a geographical location, the 10 nearest pickup points are returned, sorted by driving time by car(source: Google). In instances where google is unable to retrieve driving times from a location to a pickup point(e.g. location on mainland and pickup point on an island), these pickup points will be sorted by aerial distance and placed last in the list. Response is available as either XML or JSON.

      A pickup point is defined as any location delivering shipments on behalf of Bring and Posten, such as post offices, selected grocery stores, lockers, etc.

      It is important to note, there are two sets of addresses in the response, postbox(address, postalCode) and visiting address(visitingAddress,visitingPostalCode).Postbox address is required to get a package produced correctly, use this AS RECIPIENT address on label. Visiting address is more appropriate for user interface (Street address of the PIB).

      ### Filtering results

      In addition to postal code or location, one or more optional parameters can be added to the request, adding additional restrictions to the pickup points being returned. One such parameter is `searchForText=<texts>`, resulting in a response where all pickup points have at least a partial match with the search string given in `<texts>`. This can be the name of the pickup point, its address, city, county, municipality or location. Go to the reference table or see additional examples for more information.

      ### Rate limiting

      The Pickup point API has a rate limit, primarily considered on a per-user basis. Currently it limits API users to no more than 60 requests within a minute from a single IP address.

      Once you go over the rate limit, you will receive a response with an HTTP response code of 429 (Too Many Requests). The body of the response will consist of the following fields:

      - `code`: `429`
      - `error_message`: `The maximum number of requests per minute has been exceeded.`

      As an additional note, While accessing the Pickup point API together with Shipping Guide API, the service list should be displayed even in the case that the request has been rate limited by the Pickup point API.

      #### High-volume users

      If you're a high-volume user of the Pickup Point API, please [contact us](mailto:developer@bring.com) to discuss your options.

      When contacting Bring support include a description of how you are using the Pickup Point API, also an estimate of current request volumes.

      #### Distinct PickupPointType

      Norway :
        - Type 4  : Post i Butikk
        - Type 19 : Posten pakkeutlevering
        - Type 21 : Postkontor
        - Type 27 : Pakkeautomat
        - Type 32 : Postpunkt, egendrevet
        - Type 33 : Postpunkt
        - Type 37 : Pakkeboks

      Sweden :
        - Type 28 : Manned
        - Type 29 : Locker

      Denmark :
        - Type 85 : Manned
        - Type 86 : Locker

      Finland :
        - Type SmartPOST  : Finland Smart Post Pickup
        - Type Posti      : Finland Posti Pickup Point
        - Type Noutopiste : Finland Pickup Point
        - Type LOCKER     : Finland Locker Pickup Point

- title: Steps for Authentication
  content: |

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

      ### 1. Get your API key from Mybring
      To make API requests you will need an API key. Click the link 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).

/{countryCode}/postalCode/{postalCode}{mediaTypeExtension}:
  displayName: Pickup points for postal code
  uriParameters:
    countryCode:
      displayName: Country
      enum: [ "NO", "DK", "SE", "FI" ]
    postalCode:
      displayName: Postal code
      type: string
    mediaTypeExtension:
      enum: [ .json, .xml ]
      description: Use .json to get application/json, .xml to get application/xml or .html to get HTML.
  get:
    description: List pickup points for postal code
    queryParameters:
      searchForText:
        displayName: Text filter
        type: string
      openingHoursSearchType:
        displayName: Filter using opening hours
        enum: [ ALL_WEEKDAYS, MONDAY, TUESDAY, WEDNESDAY, THURSDAY, FRIDAY, SATURDAY, SUNDAY ]
      openOnOrBefore:
        description: Format `HHmm`. Return only pickup points that are open on or before the specified time.
        type: string
        pattern: ^([01][0-9]|2[0-3])[0-5][0-9]$
      openOnOrAfter:
        description: Format `HHmm`. Return only pickup points that are open on or after the specified time.
        type: string
        pattern: ^([01][0-9]|2[0-3])[0-5][0-9]$
      pickupPointType:
        displayName: Pickup-point type
        description: Currently available for Swedish, Finnish and Danish pickup point request only.
        enum: [ manned, locker ]
      numberOfResponses:
        description: Return the specified number of pickup points instead of the default. Try this param to get more pickup points, if a desired pickup point is missing in the response.
        type: integer
        default: 10
      street:
        description: Searches for the nearest pickup points to the given street. Use this param to get more accurate result.
        type: string
      streetNumber:
        description: Searches for the nearest pickup points to the given street number.Use this param to get more accurate result.
        type: string
      callback:
        description: JSONP callback function name.
        type: string
      requestCountryCode:
        description: Country code of the requester. Only applicable for Norwegian pickup points.
        type: string
    responses:
      200:
        displayName: Example response for NO/postalCode/1407
        body:
          application/json:
            example: !include examples/by_postal_code.json
          application/xml:
            example: !include examples/by_postal_code.xml
      250:
        displayName: Using postal code and street address
        description: |
          Sometimes (especially in Denmark) it's a good idea to also specify the address when searching for pickup points, to get more accurate results.

          In [this example](https://api.bring.com/pickuppoint/api/pickuppoint/DK/postalCode/2000.json?street=Smallegade&streetNumber=3), we look for pickup points in Smallegade 3, 2000 Frederiksberg.
        body:
          application/json:
            example: !include examples/filter_address.json
          application/xml:
            example: !include examples/filter_address.xml
      251:
        displayName: Find pickup points containing a specific string
        description: |
          If you want to return only the pickup points matching a specific string, you may use the `searchForText` query param. The given text can be the name of the pickup point, its address, city, county, municipality or location. Partial matches are also allowed.

          In [this example](https://api.bring.com/pickuppoint/api/pickuppoint/NO/postalCode/1407.json?searchForText=KIWI), we look for pickup points near NO/1407 cotaining "Kiwi".
        body:
          application/json:
            example: !include examples/filter_search.json
          application/xml:
            example: !include examples/filter_search.xml
      252:
        displayName: Find pickup points open on specific days
        description: |
          If you want to return only the pickup points open on specified days, you may use the `openingHoursSearchType=<day>` query param. `<day>` be:

          - `ALL_WEEKDAYS` (default)
          - `MONDAY`
          - `TUESDAY`
          - `WEDNESDAY`
          - `THURSDAY`
          - `FRIDAY`
          - `SATURDAY`
          - `SUNDAY`

          If you want you can also add `openOnOrBefore` and / or `openOnOrAfter`, to limit the search even more.

          In [this example](https://api.bring.com/pickuppoint/api/pickuppoint/NO/postalCode/1407.json?openingHoursSearchType=SUNDAY), we look for pickup points near NO/1407 that are open Sundays.
        body:
          application/json:
            example: !include examples/filter_days.json
          application/xml:
            example: !include examples/filter_days.xml
      253:
        displayName: Find pickup points open at specific hours
        description: |
          If you want to return only the pickup points open on specific hours, you may use the `openOnOrBefore=<time>` and/or `openOnOrAfter=<time>` query params.

          The format of `<time>` is `HHmm`.

          In [this example](https://api.bring.com/pickuppoint/api/pickuppoint/NO/postalCode/1407.json?openOnOrBefore=0800), we look for pickup points near NO/1407 open on or before 08:00.
        body:
          application/json:
            example: !include examples/filter_hours.json
          application/xml:
            example: !include examples/filter_hours.xml

/{countryCode}/location/{latitude},{longitude}{mediaTypeExtension}:
  displayName: Pickup points for location
  uriParameters:
    countryCode:
      displayName: Country
      enum: [ "NO", "DK", "SE", "FI" ]
    latitude:
      displayName: Latitude
      description: Geographic coordinate specifying the north-south position.
      type: string
    longitude:
      displayName: Longitude
      description: Geographic coordinate specifying the east-west position.
      type: string
    mediaTypeExtension:
      enum: [ .json, .xml ]
      description: Use .json to get application/json or .xml to get application/xml.
  get:
    description: List pickup points closest to location
    queryParameters:
      searchForText:
        displayName: Text filter
        type: string
      openingHoursSearchType:
        displayName: Filter using opening hours
        enum: [ ALL_WEEKDAYS, MONDAY, TUESDAY, WEDNESDAY, THURSDAY, FRIDAY, SATURDAY, SUNDAY ]
      openOnOrBefore:
        description: Format `HHmm`. Return only pickup points that are open on or before the specified time.
        type: string
        pattern: ^([01][0-9]|2[0-3])[0-5][0-9]$
      openOnOrAfter:
        description: Format `HHmm`. Return only pickup points that are open on or after the specified time.
        type: string
        pattern: ^([01][0-9]|2[0-3])[0-5][0-9]$
      pickupPointType:
        displayName: Pickup-point type
        description: Currently available for Swedish, Finnish and Danish pickup point request only.
        enum: [ manned, locker ]
      numberOfResponses:
        description: Return the specified number of pickup points instead of the default.
        type: integer
        default: 10
      street:
        description: Searches for the nearest pickup points to the given street.
        type: string
      streetNumber:
        description: Searches for the nearest pickup points to the given street number.
        type: string
      callback:
        description: JSONP callback function name.
        type: string
      requestCountryCode:
        description: Country code of the requester. Only applicable for Norwegian pickup points.
        type: string
    responses:
      200:
        displayName: Example response for location/60.395226,5.321725
        body:
          application/json:
            example: !include examples/by_coordinates.json
          application/xml:
            example: !include examples/by_coordinates.xml

/{countryCode}/id/{id}{mediaTypeExtension}:
  displayName: A specific pickup point
  uriParameters:
    countryCode:
      displayName: Country
      enum: [ "NO", DK, SE, FI ]
    mediaTypeExtension:
      enum: [ .json, .xml ]
      description: Use .json to get application/json or .xml to get application/xml.
  get:
    description: Look up a specific pickup point
    queryParameters:
      callback:
        displayName: JSONP support
        description: Callback function name.
        type: string
      requestCountryCode:
        description: Country code of the requester. Only applicable for Norwegian pickup points.
        type: string
    responses:
      200:
        displayName: Example response for id/121110
        body:
          application/json:
            example: !include examples/by_id.json
          application/xml:
            example: !include examples/by_id.xml

/{countryCode}/all{mediaTypeExtension}:
  displayName: All pickup points in a country
  uriParameters:
    countryCode:
      displayName: Country
      enum: [ "NO", DK, SE, FI ]
    mediaTypeExtension:
      enum: [ .json, .xml ]
      description: Use .json to get application/json or .xml to get application/xml.
  get:
    description: All pickup points in a country
    queryParameters:
      callback:
        displayName: JSONP support
        description: Callback function name.
        type: string
      requestCountryCode:
        description: Country code of the requester. Only applicable for Norwegian pickup points.
        type: string

#%RAML 0.8
---
title: Pickup Point API
baseUri: https://api.bring.com/pickuppoint/api/pickuppoint

documentation:

        The Pickup Point API becomes authenticated from 01.11.2020

            Our customers are increasingly demanding new functionality and solutions that are easy to use. To meet these expectations, we must know which customers and partners are using our APIs and how they are using them.

            To further develop the value proposition of our Pickup Point API, the solution becomes authenticated from 01.11.2020.

            We recommend making the adjustment already now, well in advance of summer vacations and peak season.

    {% include apiflock.html %}

- title: Introduction
  content: |
      The Pickup point API provides a list of locations for package pickup. Based on a specified postal code or a geographical location, the 10 nearest pickup points are returned, sorted by driving time by car(source: Google). In instances where google is unable to retrieve driving times from a location to a pickup point(e.g. location on mainland and pickup point on an island), these pickup points will be sorted by aerial distance and placed last in the list. Response is available as either XML or JSON.

      A pickup point is defined as any location delivering shipments on behalf of Bring and Posten, such as post offices, selected grocery stores, lockers, etc.

      It is important to note, there are two sets of addresses in the response, postbox(address, postalCode) and visiting address(visitingAddress,visitingPostalCode).Postbox address is required to get a package produced correctly, use this AS RECIPIENT address on label. Visiting address is more appropriate for user interface (Street address of the PIB).

      ### Filtering results

      In addition to postal code or location, one or more optional parameters can be added to the request, adding additional restrictions to the pickup points being returned. One such parameter is `searchForText=<texts>`, resulting in a response where all pickup points have at least a partial match with the search string given in `<texts>`. This can be the name of the pickup point, its address, city, county, municipality or location. Go to the reference table or see additional examples for more information.

      ### Rate limiting

      The Pickup point API has a rate limit, primarily considered on a per-user basis. Currently it limits API users to no more than 60 requests within a minute from a single IP address.

      Once you go over the rate limit, you will receive a response with an HTTP response code of 429 (Too Many Requests). The body of the response will consist of the following fields:

      - `code`: `429`
      - `error_message`: `The maximum number of requests per minute has been exceeded.`

      As an additional note, While accessing the Pickup point API together with Shipping Guide API, the service list should be displayed even in the case that the request has been rate limited by the Pickup point API.

      #### High-volume users

      If you're a high-volume user of the Pickup Point API, please [contact us](mailto:developer@bring.com) to discuss your options.

      When contacting Bring support include a description of how you are using the Pickup Point API, also an estimate of current request volumes.

      #### Distinct PickupPointType

      Norway :
        - Type 4  : Post i Butikk
        - Type 19 : Posten pakkeutlevering
        - Type 21 : Postkontor
        - Type 27 : Pakkeautomat
        - Type 32 : Postpunkt, egendrevet
        - Type 33 : Postpunkt
        - Type 37 : Pakkeboks

      Sweden :
        - Type 28 : Manned
        - Type 29 : Locker

      Denmark :
        - Type 85 : Manned
        - Type 86 : Locker

      Finland :
        - Type SmartPOST  : Finland Smart Post Pickup
        - Type Posti      : Finland Posti Pickup Point
        - Type Noutopiste : Finland Pickup Point
        - Type LOCKER     : Finland Locker Pickup Point

- title: Steps for Authentication
  content: |

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

      ### 1. Get your API key from Mybring
      To make API requests you will need an API key. Click the link 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).

/{countryCode}/postalCode/{postalCode}{mediaTypeExtension}:
  displayName: Pickup points for postal code
  uriParameters:
    countryCode:
      displayName: Country
      enum: [ "NO", "DK", "SE", "FI" ]
    postalCode:
      displayName: Postal code
      type: string
    mediaTypeExtension:
      enum: [ .json, .xml ]
      description: Use .json to get application/json, .xml to get application/xml or .html to get HTML.
  get:
    description: List pickup points for postal code
    queryParameters:
      searchForText:
        displayName: Text filter
        type: string
      openingHoursSearchType:
        displayName: Filter using opening hours
        enum: [ ALL_WEEKDAYS, MONDAY, TUESDAY, WEDNESDAY, THURSDAY, FRIDAY, SATURDAY, SUNDAY ]
      openOnOrBefore:
        description: Format `HHmm`. Return only pickup points that are open on or before the specified time.
        type: string
        pattern: ^([01][0-9]|2[0-3])[0-5][0-9]$
      openOnOrAfter:
        description: Format `HHmm`. Return only pickup points that are open on or after the specified time.
        type: string
        pattern: ^([01][0-9]|2[0-3])[0-5][0-9]$
      pickupPointType:
        displayName: Pickup-point type
        description: Currently available for Swedish, Finnish and Danish pickup point request only.
        enum: [ manned, locker ]
      numberOfResponses:
        description: Return the specified number of pickup points instead of the default. Try this param to get more pickup points, if a desired pickup point is missing in the response.
        type: integer
        default: 10
      street:
        description: Searches for the nearest pickup points to the given street. Use this param to get more accurate result.
        type: string
      streetNumber:
        description: Searches for the nearest pickup points to the given street number.Use this param to get more accurate result.
        type: string
      callback:
        description: JSONP callback function name.
        type: string
      requestCountryCode:
        description: Country code of the requester. Only applicable for Norwegian pickup points.
        type: string
    responses:
      200:
        displayName: Example response for NO/postalCode/1407
        body:
          application/json:
            example: !include examples/by_postal_code.json
          application/xml:
            example: !include examples/by_postal_code.xml
      250:
        displayName: Using postal code and street address
        description: |
          Sometimes (especially in Denmark) it's a good idea to also specify the address when searching for pickup points, to get more accurate results.

          In [this example](https://api.bring.com/pickuppoint/api/pickuppoint/DK/postalCode/2000.json?street=Smallegade&streetNumber=3), we look for pickup points in Smallegade 3, 2000 Frederiksberg.
        body:
          application/json:
            example: !include examples/filter_address.json
          application/xml:
            example: !include examples/filter_address.xml
      251:
        displayName: Find pickup points containing a specific string
        description: |
          If you want to return only the pickup points matching a specific string, you may use the `searchForText` query param. The given text can be the name of the pickup point, its address, city, county, municipality or location. Partial matches are also allowed.

          In [this example](https://api.bring.com/pickuppoint/api/pickuppoint/NO/postalCode/1407.json?searchForText=KIWI), we look for pickup points near NO/1407 cotaining "Kiwi".
        body:
          application/json:
            example: !include examples/filter_search.json
          application/xml:
            example: !include examples/filter_search.xml
      252:
        displayName: Find pickup points open on specific days
        description: |
          If you want to return only the pickup points open on specified days, you may use the `openingHoursSearchType=<day>` query param. `<day>` be:

          - `ALL_WEEKDAYS` (default)
          - `MONDAY`
          - `TUESDAY`
          - `WEDNESDAY`
          - `THURSDAY`
          - `FRIDAY`
          - `SATURDAY`
          - `SUNDAY`

          If you want you can also add `openOnOrBefore` and / or `openOnOrAfter`, to limit the search even more.

          In [this example](https://api.bring.com/pickuppoint/api/pickuppoint/NO/postalCode/1407.json?openingHoursSearchType=SUNDAY), we look for pickup points near NO/1407 that are open Sundays.
        body:
          application/json:
            example: !include examples/filter_days.json
          application/xml:
            example: !include examples/filter_days.xml
      253:
        displayName: Find pickup points open at specific hours
        description: |
          If you want to return only the pickup points open on specific hours, you may use the `openOnOrBefore=<time>` and/or `openOnOrAfter=<time>` query params.

          The format of `<time>` is `HHmm`.

          In [this example](https://api.bring.com/pickuppoint/api/pickuppoint/NO/postalCode/1407.json?openOnOrBefore=0800), we look for pickup points near NO/1407 open on or before 08:00.
        body:
          application/json:
            example: !include examples/filter_hours.json
          application/xml:
            example: !include examples/filter_hours.xml

/{countryCode}/location/{latitude},{longitude}{mediaTypeExtension}:
  displayName: Pickup points for location
  uriParameters:
    countryCode:
      displayName: Country
      enum: [ "NO", "DK", "SE", "FI" ]
    latitude:
      displayName: Latitude
      description: Geographic coordinate specifying the north-south position.
      type: string
    longitude:
      displayName: Longitude
      description: Geographic coordinate specifying the east-west position.
      type: string
    mediaTypeExtension:
      enum: [ .json, .xml ]
      description: Use .json to get application/json or .xml to get application/xml.
  get:
    description: List pickup points closest to location
    queryParameters:
      searchForText:
        displayName: Text filter
        type: string
      openingHoursSearchType:
        displayName: Filter using opening hours
        enum: [ ALL_WEEKDAYS, MONDAY, TUESDAY, WEDNESDAY, THURSDAY, FRIDAY, SATURDAY, SUNDAY ]
      openOnOrBefore:
        description: Format `HHmm`. Return only pickup points that are open on or before the specified time.
        type: string
        pattern: ^([01][0-9]|2[0-3])[0-5][0-9]$
      openOnOrAfter:
        description: Format `HHmm`. Return only pickup points that are open on or after the specified time.
        type: string
        pattern: ^([01][0-9]|2[0-3])[0-5][0-9]$
      pickupPointType:
        displayName: Pickup-point type
        description: Currently available for Swedish, Finnish and Danish pickup point request only.
        enum: [ manned, locker ]
      numberOfResponses:
        description: Return the specified number of pickup points instead of the default.
        type: integer
        default: 10
      street:
        description: Searches for the nearest pickup points to the given street.
        type: string
      streetNumber:
        description: Searches for the nearest pickup points to the given street number.
        type: string
      callback:
        description: JSONP callback function name.
        type: string
      requestCountryCode:
        description: Country code of the requester. Only applicable for Norwegian pickup points.
        type: string
    responses:
      200:
        displayName: Example response for location/60.395226,5.321725
        body:
          application/json:
            example: !include examples/by_coordinates.json
          application/xml:
            example: !include examples/by_coordinates.xml

/{countryCode}/id/{id}{mediaTypeExtension}:
  displayName: A specific pickup point
  uriParameters:
    countryCode:
      displayName: Country
      enum: [ "NO", DK, SE, FI ]
    mediaTypeExtension:
      enum: [ .json, .xml ]
      description: Use .json to get application/json or .xml to get application/xml.
  get:
    description: Look up a specific pickup point
    queryParameters:
      callback:
        displayName: JSONP support
        description: Callback function name.
        type: string
      requestCountryCode:
        description: Country code of the requester. Only applicable for Norwegian pickup points.
        type: string
    responses:
      200:
        displayName: Example response for id/121110
        body:
          application/json:
            example: !include examples/by_id.json
          application/xml:
            example: !include examples/by_id.xml

/{countryCode}/all{mediaTypeExtension}:
  displayName: All pickup points in a country
  uriParameters:
    countryCode:
      displayName: Country
      enum: [ "NO", DK, SE, FI ]
    mediaTypeExtension:
      enum: [ .json, .xml ]
      description: Use .json to get application/json or .xml to get application/xml.
  get:
    description: All pickup points in a country
    queryParameters:
      callback:
        displayName: JSONP support
        description: Callback function name.
        type: string
      requestCountryCode:
        description: Country code of the requester. Only applicable for Norwegian pickup points.
        type: string


Include formatting of json example for beautification

#%RAML 1.0
---
title: Tracking Webhook API
version: v1
baseUri: https://api.bring.com/events
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 |
    |:-------|:--------|
    | `NO_REG` | 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: Get all your current registered and active Webhooks
    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/events
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 |
    |:-------|:--------|
    | `NO_REG` | 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: Get all your current registered and active Webhooks
    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?)