URURL Updates

URURL Updates

#%RAML 1.0
---
title: Shipment API
version: v1
baseUri: https://bapi.bring.com/shipment
mediaType: application/json
annotationTypes:
  hideInDocumentation: boolean
  hideRequired: boolean
types:
  Address:
    type: object
    description: An address
    properties:
      name:
        type: string
        required: true
        description: Name
      streetAddress:
        type: string
        required: true
        description: Senders address
      postalCode:
        type: string
        required: true
        description: Postal code. Must be a valid Norwegian postal code.
        pattern: "[0-9]{4}"
        example: "0150"
  AddressWithPostalName:
    type: object
    description: An address
    properties:
      name:
        type: string
        required: true
        description: Name
      streetAddress:
        type: string
        required: true
        description: Senders address
      postalCode:
        type: string
        required: true
        description: Senders postal code. Must be a valid Norwegian postal code.
        pattern: "[0-9]{4}"
        example: "0150"
      postalName:
        type: string
        required: true
        description: Name of the postalCode
  Order:
    type: object
    description: An order to place in Mybring.
    properties:
      customerNumber:
        type: string
        description: API customer number for which to place the order.
      senderName:
        type: string
        description: Sender's name.
        example: Min Bedrift
      senderEmail:
        required: false
        type: string
        description: Sender's email address. Defaults to the user's email address.
      postalCode:
        type: string
        description: Sender's postal code. Must be a valid Norwegian postal code.
      streetAddress:
        type: string
        description: Sender's street address.
      reference:
        required: false
        description: A reference for the shipment that will be shown on the invoice.
      testIndicator:
        required: false
        type: boolean
        description: Set to true when testing API implementation.
      returnAddress:
        required: false
        type: Address
        description: An optional return address. If set will override the return address in generated label.
      packages:
        minItems: 1
        maxItems: 500
        type: Package[]
        description: The packages to send in this shipment.
  Package:
    type: object
    description: A single package in a shipment.
    properties:
      rfid:
        type: boolean
        description: Whether to activate [tracking with RFID](#tracking-with-rfid) for the package.
      weight:
        maximum: 2000
        type: integer
        description: Weight in grams.
      recipientName:
        type: string
        description: Recipient name.
      postalCode:
        type: string
        description: A valid Norwegian postal code.
      streetAddress:
        type: string
        description: Recipient's street address.
      phoneNumber:
        type: string
        pattern: "\\+[0-9 ]+"
        description: Recipient's phone number, including country code.
        example: "+4700000000"
      email:
        type: string
        description: Recipient's email address.
  SuccessfulOrder:
    (hideRequired): true
    displayName: Successful Order
    description: A successfully placed order that contains links to labels and waybill.
    properties:
      testIndicator:
        type: boolean
        description: Whether the placed order had the testIndicator flag set or not.
      id:
        type: number
        description: The ID of the order that was placed.
      customerNumber:
        type: string
        description: The API customer number for which the order was placed.
      customerName:
        type: string
        description: The name of the customer for which the order was placed.
      customerOrganizationNumber:
        type: string
        description: The organization number of the customer for which the order was placed.
      senderName:
        type: string
        description: Sender's name.
      streetAddress:
        type: string
        description: Sender's street address.
      postalCode:
        type: string
        description: Sender's postal code.
      postalPlace:
        type: string
        description: The city/place for the postal code.
      email:
        type: string
        description: Sender's email address for the order that was placed.
      reference:
        type: string
        description: A reference for the shipment that will be shown on the invoice.
      labelUri:
        type: string
        description: URL to PDF label(s) for packages ordered without tracking.
      rfidLabelUri:
        type: string
        description: URL to ZPL label(s) for packages ordered with tracking.
      waybillUri:
        type: string
        description: URL to waybill PDF that has to be printed and sent with the shipment.
      orderNumberReference:
        type: string
        description: The order number reference for the placed order. This is the number on the waybill.
      priceWithoutVat:
        type: number
        description: Price of shipment without VAT (MVA).
      priceWithVat:
        type: number
        description: Price of shipment with VAT (MVA).
      vat:
        type: number
        description: How much of the price was VAT (MVA).
      currency:
        type: string
        default: NOK
        description: The currency for the price.
      orderTime:
        type: datetime
        example: 2017-09-01T14:00:00.000Z
        description: Timestamp for when the order was placed.
      returnAddress:
        type: AddressWithPostalName
        required: false
        description: Return address for the order if one is set
      packages:
        minItems: 1
        description: Packages in this shipment.
        type: OrderedPackage[]
  OrderedPackage:
    (hideRequired): true
    displayName: Ordered Package
    description: A single package in a successfully ordered shipment.
    properties:
      rfid:
        type: boolean
        description: Whether to [tracking for the package](#tracking-with-rfid) was activated.
      recipientName:
        type: string
        description: Recipient name.
      streetAddress:
        type: string
        description: Recipient's street address.
      postalCode:
        type: string
        description: Recipient's postal code.
      postalPlace:
        type: string
        description: The city/place for the postal code.
      phoneNumber:
        type: string
        pattern: "\\+[0-9 ]+"
        description: Recipient's phone number.
      email:
        type: string
        description: Recipient's email address.
      weight:
        maximum: 2000
        type: integer
        description: Package weight in grams.
      shipmentNumber:
        type: string
        description: The shipment number for this package. A package in a PIP shipment will have both a shipment number and a package number.
      packageNumber:
        type: string
        description: The package number for this package. This goes on the label.
      agreementNumber:
        type: boolean
        description: Whether the customer has an agreement price for this package.
  ValidatedOrder:
    (hideRequired): true
    displayName: Validated Order
    description: A valid order that can be placed.
    properties:
      testIndicator:
        type: boolean
        description: Whether the validated order had the testIndicator flag set or not.
      customerNumber:
        type: string
        description: The API customer number for the validated order.
      customerName:
        type: string
        description: The name of the customer for the validated order.
      customerOrganizationNumber:
        type: string
        description: The organization number of the customer for the validated order.
      senderName:
        type: string
        description: The sender's name.
      streetAddress:
        type: string
        description: The sender's street address.
      postalCode:
        type: string
        description: The sender's postal code.
      postalPlace:
        type: string
        description: The city/place for the postal code.
      email:
        type: string
        description: The sender's email address.
      reference:
        type: string
        description: A reference for the shipment that will be shown on the invoice.
      priceWithoutVat:
        type: number
        description: Calculated price without VAT (MVA).
      priceWithVat:
        type: number
        description: Calulated price with VAT (MVA).
      vat:
        type: number
        description: Calculated VAT (MVA).
      currency:
        type: string
        description: The price's currency.
      orderTime:
        type: datetime
        description: Timestamp for when the order was validated.
      returnAddress:
        type: AddressWithPostalName
        required: false
        description: Return address for the order if one is set
      packages:
        minItems: 1
        description: Packages in this validated shipment. The packages in the response will correspond to same order as it was in the request to make it easier for clients to do any mapping if needed.
        type: ValidatedPackage[]
  ValidatedPackage:
    (hideRequired): true
    displayName: Validated Package
    description: A single, valid package in a valid shipment.
    properties:
      rfid:
        type: boolean
        description: Whether to [tracking with RFID](#tracking-with-rfid) was activated for the package.
      recipientName:
        type: string
        description: Recipient's name.
      streetAddress:
        type: string
        description: Recipient's email address.
      postalCode:
        type: string
        description: Recipient's postal code.
      postalPlace:
        type: string
        description: The city/place for the postal code.
      phoneNumber:
        type: string
        description: Recipient's phone number.
      email:
        type: string
        description: Recipient's email address.
      weight:
        type: integer
        description: Package weight in grams.
      agreementNumber:
        type: boolean
        description: Whether the customer has an agreement price for this package.
  OrderRequest:
    (hideInDocumentation): true
    type: object
    properties:
      data:
        type: object
        description: JSON-API data object.
        properties:
          type:
            type: string
            enum: [ orders ]
            description: JSON-API type.
          attributes:
            type: Order
            description: Order properties.
  SuccessfulOrderResponse:
    (hideRequired): true
    (hideInDocumentation): true
    type: object
    properties:
      data:
        type: object
        description: JSON-API data object.
        properties:
          type:
            type: string
            description: JSON-API type.
          id: string
          attributes:
            type: SuccessfulOrder
            description: Order properties.
  ValidatedOrderResponse:
    (hideRequired): true
    (hideInDocumentation): true
    type: object
    properties:
      data:
        type: object
        description: JSON-API data object.
        properties:
          type:
            type: string
            pattern: "order"
            description: JSON-API type.
          attributes:
            type: ValidatedOrder
            description: Order properties.
  ErrorResponse:
    (hideRequired): true
    (hideInDocumentation): true
    type: object
    properties:
      errors:
        type: ErrorObject[]
        description: List of errors.
  ErrorObject:
    (hideRequired): true
    (hideInDocumentation): true
    type: object
    properties:
      code:
        type: string
        description: Machine-readable description of error.
      title:
        type: string
        description: Human-readable description of error.
      source:
        type: object
        properties:
          pointer:
            type: string
            description: A JSON pointer to the invalid field.
  PackageWithNumbers:
    displayName: Package Details
    description: Package Details with OrderID
    properties:
      rfid:
        type: boolean
        description: Whether to activate [tracking with RFID](#tracking-with-rfid) for the package.
      recipientName:
        type: string
        description: Recipient name.
      streetAddress:
        type: string
        description: Recipient's Street address.
      postalCode:
        type: string
        description: A valid Norwegian postal code.
      postalPlace:
        type: string
        description: The city/place for the postal code.
      phoneNumber:
        type: string
        pattern: "\\+[0-9 ]+"
        description: Recipient's phone number, including country code.
        example: "+4700000000"
      email:
        type: string
        description: Recipient's email address.
      weight:
        maximum: 2000
        type: integer
        description: Package weight in grams.
      shipmentNumber:
        type: string
        description: The shipment number for this package. A package in a PIP shipment will have both a shipment number and a package number.
      packageNumber:
        type: string
        description: The package number for this package. This goes on the label.
      priceType:
        type: string
        description: Whether the Price is Agreement or List
        enum: [ AGREEMENT_PRICE,  LIST_PRICE]
  OrderWithLabelResponse:
    (hideRequired): true
    displayName: Successful Order
    description: A successfully label generation that contains links to labels.
    properties:
      reference:
        type: string
        description: A reference for the shipment that will be shown on the invoice.
      senderName:
        type: string
        description: Sender's name.
      streetAddress:
        type: string
        description: Sender's street address.
      email:
        type: string
        description: Sender's email address for the order that was placed.
      labelUri:
        type: string
        description: URL to PDF label(s) for packages ordered without tracking.
      rfidLabelUri:
        type: string
        description: URL to ZPL label(s) for packages ordered with tracking.
      orderTime:
        type: datetime
        example: 2017-09-01T14:00:00.000Z
        description: Timestamp for when the order was placed.
      postalCode:
        type: string
        description: Sender's postal code.
      postalPlace:
        type: string
        description: The city/place for the postal code.
      customerNumber:
        type: string
        description: The API customer number for the validated order.
      customerName:
        type: string
        description: The API customer name for which the order was placed.
      customerOrganizationNumber:
        type: string
        description: The organization number of the customer for which the order was placed.
      testIndicator:
        type: boolean
        description: Whether the placed order had the testIndicator flag set or not.
      packages:
        minItems: 1
        description: Packages Number for the shipment.
        type: PackageWithNumbers[]
  SuccessfulLabelGenerationResponse:
    (hideRequired): true
    (hideInDocumentation): true
    type: object
    properties:
      data:
        type: object
        description: JSON-API data object.
        properties:
          type:
            type: string
            enum: [ labels ]
            description: JSON-API type.
          attributes:
            type: OrderWithLabelResponse
            description: Order properties.
  LabelRequest:
    (hideInDocumentation): true
    type: object
    properties:
      data:
        type: object
        description: JSON-API data object.
        properties:
          type:
            type: string
            enum: [ labels ]
            description: JSON-API type.
          attributes:
            type: CreateOrderRequest
            description: Order properties.
  CreateOrderRequest:
    displayName: Create Order Request
    description: It creates the Request for Label Generation.
    properties:
      customerNumber:
        type: string
        description: The API customer number for the validated order.
      senderName:
        type: string
        description: The sender's name.
      senderEmail:
        required: false
        type: string
        description: Sender's email address. Defaults to the user's email address.
      postalCode:
        type: string
        description: Sender's postal code. Must be a valid Norwegian postal code.
      streetAddress:
        type: string
        description: Recipient's email address.
      reference:
        required: false
        description: A reference for the shipment that will be shown on the invoice.
      testIndicator:
        type: boolean
        description: Whether the validated order had the testIndicator flag set or not.
      packages:
        minItems: 1
        maxItems: 500
        type: Package[]
        description: The packages to send in this shipment. Response will have packages in same order as requested to make it easier for clients to do any mapping if needed.
  LabelOrderRequest:
      (hideInDocumentation): true
      type: object
      properties:
        data:
          type: object
          description: JSON-API data object.
          properties:
            type:
              type: string
              enum: [ label_orders ]
              description: JSON-API type.
            attributes:
              type: CreateLabelOrderRequest
              description: Create Order properties.
  CreateLabelOrderRequest:
    displayName: Create Label Order Request
    description: Create Label Order Request
    properties:
      customerNumber:
        type: string
        description: The API customer number.
      packageNumbers:
        minItems: 1
        maxItems: 500
        type: string[]
        description: List of Package Numbers.
  OrderWithIdAndEdiMessage:
    displayName: Reponse of Create Order Request
    description: Reponse of Create Order Request
    properties:
      id:
        type: number
        description: The ID of the order that was placed.
      customerNumber:
        type: string
        description: The API customer number for the validated order.
      customerName:
        type: string
        description: The API customer name for which the order was placed.
      customerOrganizationNumber:
        type: string
        description: The organization number of the customer for which the order was placed.
      senderName:
        type: string
        description: Sender's name.
      streetAddress:
        type: string
        description: Sender's street address.
      email:
        type: string
        description: Sender's email address for the order that was placed.
      postalCode:
        type: string
        description: Sender's postal code.
      reference:
        type: string
        description: A reference for the shipment that will be shown on the invoice.
      labelUri:
        type: string
        description: URL to PDF label(s) for packages ordered without tracking.
      rfidLabelUri:
        type: string
        description: URL to ZPL label(s) for packages ordered with tracking.
      waybillUri:
        type: string
        description: URL to waybill PDF that has to be printed and sent with the shipment.
      orderNumberReference:
        type: string
        description: The order number reference for the placed order. This is the number on the waybill.
      priceWithoutVat:
        type: number
        description: Price of shipment without VAT (MVA).
      priceWithVat:
        type: number
        description: Price of shipment with VAT (MVA).
      vat:
        type: number
        description: How much of the price was VAT (MVA).
      currency:
        type: string
        default: NOK
        description: The currency for the price.
      orderTime:
        type: datetime
        example: 2017-09-01T14:00:00.000Z
        description: Timestamp for when the order was placed.
      returnAddress:
        type: AddressWithPostalName
        required: false
        description: Return address for the order if one is set
      packages:
        minItems: 1
        description: Packages Number for the shipment.
        type: PackageWithNumbers[]
  SuccessfulLabelOrderResponse:
     (hideRequired): true
     (hideInDocumentation): true
     type: object
     properties:
       data:
         type: object
         description: JSON-API data object.
         properties:
           type:
             type: string
             enum: [ order ]
             description: JSON-API type.
           id:
             type: string
             description: Order Id
           attributes:
             type: OrderWithIdAndEdiMessage
             description: Label Order properties.

documentation:
- title: Introduction
  content: |
    The Shipment API is a logged-in service that lets Mybring users (customers of Mybring) programatically create a instruction or a booking by invoking a Web Service by posting XML/JSON over HTTP.

    The Shipment API uses Shipping Guide as the source for price and availability (when supported in the Shipping Guide) for the different products. We advise clients of the Shipment API to use Shipping Guide API for getting the list price and checking availability before sending a booking request. Note that invoice payment is the only available payment option for the Shipment API. This means that the Mybring user ID used in the booking request must have access to the customer number specified as payer of the booking.

    We are continually rolling out support for more of Posten / Brings products and aim to support all available products in this API withing a short time. In addition to the documentation on this pages feel free to check out our [swagger page](https://bapiqa.bring.com/Shipment/swagger) for this API.

    This API has similarities with the Booking API, but there are differences. Read more about the [differences between the Booking API and the Shipment API](/api/booking-shipment/).

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

    | Header | Example | Comment |
    |:-------|:--------|:--------|
    | `X-MyBring-API-Uid` | `john.doe@example.com` | Mybring login ID |
    | `X-MyBring-API-Key` | `1234abc-abcd-1234-5678-abcd1234abcd ` | Mybring login's API key |

    Those headers must be present for authenticating requests.

/sendshipment?shipmentId={createShipmentId}&packageIds={createPackageId}:
  displayName: Create shipment
  description: |
        Sends a shipment consisting of one consignment, that must include at least one package (transportunit), from one sender to one receiver. The shipment might include additional information in regards to cash on delivery, dangerousgoods etc. If requested through the query parameteres the service will create shipmentid (for the whole shipment) in addition to package ids. The packageids will be returned in the order of the packages (ie. package 1 in the input wil have packageid 1 in returned array).

        A valid combination of an additional party, with party type TransportCompany and a valid partyId and optionally subPartyId, and service is required. In addition there might be several valueadded services that can be added. Please refer to this link for both [valid product codes/services and VASes](https://bapiqa.bring.com/Shipment/Documentation/GetServiceAndVAS?responseType=XML).

        The structure and most of the content will be validated.

  uriParameters:
    createShipmentId:
      displayName: If "true" the API will assign a shipment ID for you and return it in the response.
      type: boolean
    createPackageId:
      displayName: If "true" the API will assign all package IDs for you and return them in the response.
      type: boolean
  description: |
      Request is used to either create, update or delete an instruction for Bring.

  post:
    description: Request is used to either create, update or delete an instruction for Bring.
    headers:
          Content-Type:
            description: Specify request format (application/json, application/xml)
            required: true
            enum: [ application/json,application/xml ]
          Accept:
            description: Specify response format (application/json, application/xml)
            required: true
            enum: [ application/json,application/xml ]
    body:
      application/xml:
        examples:
          valid_request:
            displayName: Valid Request
            value: !include examples/basic_example.xml
        type:
      application/json:
        examples:
          valid_request:
            displayName: Valid Request
            value: !include examples/basic_example.json
        type:
    responses:
      200:
        description: |
          Returns a confirmation of successfull delivery and package IDs / shipment IDs if requested.
        body:
          application/xml:
            type: CreateShipmentResponse
            examples:
              valid_shipment:
                displayName: Valid Shipment
                value: !include examples/valid_shipment_response.xml
          application/json:
            type: CreateShipmentResponse
            examples:
              valid_shipment:
                displayName: Valid Shipment
                value: !include examples/valid_shipment_response.json
      400:
        displayName: Error
        description: |
          Error in validation of request or error in data structure of request.

      417:
        displayName: Error
        description: |
          Missing authentication headers.

      500:
        displayName: Error
        description: |
          Unknown error. Error sending data to destination.

      250:
        displayName: Bring Express Courier
        description: Sample request to book a Bring Express Courier shipment.
        body:
          application/xml:
            example: !include examples/basic_example.xml
          application/json:
            example: !include examples/basic_example.json

/sendbooking?shipmentId={createShipmentId}&packageIds={createPackageId}:
  displayName: Create shipment booking
  description: |
        Sends a shipment consisting of one consignment, that must include at least one package (transportunit), from one sender to one receiver. The shipment might include additional information in regards to cash on delivery, dangerousgoods etc. If requested through the query parameteres the service will create shipmentid (for the whole shipment) in addition to package ids. The packageids will be returned in the order of the packages (ie. package 1 in the input wil have packageid 1 in returned array).

        A valid combination of an additional party, with party type TransportCompany and a valid partyId and optionally subPartyId, and service is required. In addition there might be several valueadded services that can be added. Please refer to this link for both [valid product codes/services and VASes](https://bapiqa.bring.com/Shipment/Documentation/GetServiceAndVAS?responseType=XML).

        The structure and most of the content will be validated.

  uriParameters:
    createShipmentId:
      displayName: If "true" the API will assign a shipment ID for you and return it in the response.
      type: boolean
    createPackageId:
      displayName: If "true" the API will assign all package IDs for you and return them in the response.
      type: boolean
  description: |
      Request is used to either create, update or delete an instruction for Bring.

  post:
    description: Request is used to either create, update or delete an instruction for Bring.
    headers:
          Content-Type:
            description: Specify request format (application/json, application/xml)
            required: true
            enum: [ application/json,application/xml ]
          Accept:
            description: Specify response format (application/json, application/xml)
            required: true
            enum: [ application/json,application/xml ]
    body:
      application/xml:
        examples:
          valid_request:
            displayName: Valid Request
            value: !include examples/basic_example_booking.xml
        type:
      application/json:
        examples:
          valid_request:
            displayName: Valid Request
            value: !include examples/basic_example_booking.json
        type:
    responses:
      200:
        displayName: Success
        description: |
          Returns a confirmation of successfull delivery and package IDs / shipment IDs if requested.

      400:
        displayName: Error
        description: |
          Error in validation of request or error in data structure of request.

      417:
        displayName: Error
        description: |
          Missing authentication headers.

      500:
        displayName: Error
        description: |
          Unknown error. Error sending data to destination.

#%RAML 1.0
---
title: Shipment API
version: v1
baseUri: https://api.bring.com/shipment
mediaType: application/json
annotationTypes:
  hideInDocumentation: boolean
  hideRequired: boolean
types:
  Address:
    type: object
    description: An address
    properties:
      name:
        type: string
        required: true
        description: Name
      streetAddress:
        type: string
        required: true
        description: Senders address
      postalCode:
        type: string
        required: true
        description: Postal code. Must be a valid Norwegian postal code.
        pattern: "[0-9]{4}"
        example: "0150"
  AddressWithPostalName:
    type: object
    description: An address
    properties:
      name:
        type: string
        required: true
        description: Name
      streetAddress:
        type: string
        required: true
        description: Senders address
      postalCode:
        type: string
        required: true
        description: Senders postal code. Must be a valid Norwegian postal code.
        pattern: "[0-9]{4}"
        example: "0150"
      postalName:
        type: string
        required: true
        description: Name of the postalCode
  Order:
    type: object
    description: An order to place in Mybring.
    properties:
      customerNumber:
        type: string
        description: API customer number for which to place the order.
      senderName:
        type: string
        description: Sender's name.
        example: Min Bedrift
      senderEmail:
        required: false
        type: string
        description: Sender's email address. Defaults to the user's email address.
      postalCode:
        type: string
        description: Sender's postal code. Must be a valid Norwegian postal code.
      streetAddress:
        type: string
        description: Sender's street address.
      reference:
        required: false
        description: A reference for the shipment that will be shown on the invoice.
      testIndicator:
        required: false
        type: boolean
        description: Set to true when testing API implementation.
      returnAddress:
        required: false
        type: Address
        description: An optional return address. If set will override the return address in generated label.
      packages:
        minItems: 1
        maxItems: 500
        type: Package[]
        description: The packages to send in this shipment.
  Package:
    type: object
    description: A single package in a shipment.
    properties:
      rfid:
        type: boolean
        description: Whether to activate [tracking with RFID](#tracking-with-rfid) for the package.
      weight:
        maximum: 2000
        type: integer
        description: Weight in grams.
      recipientName:
        type: string
        description: Recipient name.
      postalCode:
        type: string
        description: A valid Norwegian postal code.
      streetAddress:
        type: string
        description: Recipient's street address.
      phoneNumber:
        type: string
        pattern: "\\+[0-9 ]+"
        description: Recipient's phone number, including country code.
        example: "+4700000000"
      email:
        type: string
        description: Recipient's email address.
  SuccessfulOrder:
    (hideRequired): true
    displayName: Successful Order
    description: A successfully placed order that contains links to labels and waybill.
    properties:
      testIndicator:
        type: boolean
        description: Whether the placed order had the testIndicator flag set or not.
      id:
        type: number
        description: The ID of the order that was placed.
      customerNumber:
        type: string
        description: The API customer number for which the order was placed.
      customerName:
        type: string
        description: The name of the customer for which the order was placed.
      customerOrganizationNumber:
        type: string
        description: The organization number of the customer for which the order was placed.
      senderName:
        type: string
        description: Sender's name.
      streetAddress:
        type: string
        description: Sender's street address.
      postalCode:
        type: string
        description: Sender's postal code.
      postalPlace:
        type: string
        description: The city/place for the postal code.
      email:
        type: string
        description: Sender's email address for the order that was placed.
      reference:
        type: string
        description: A reference for the shipment that will be shown on the invoice.
      labelUri:
        type: string
        description: URL to PDF label(s) for packages ordered without tracking.
      rfidLabelUri:
        type: string
        description: URL to ZPL label(s) for packages ordered with tracking.
      waybillUri:
        type: string
        description: URL to waybill PDF that has to be printed and sent with the shipment.
      orderNumberReference:
        type: string
        description: The order number reference for the placed order. This is the number on the waybill.
      priceWithoutVat:
        type: number
        description: Price of shipment without VAT (MVA).
      priceWithVat:
        type: number
        description: Price of shipment with VAT (MVA).
      vat:
        type: number
        description: How much of the price was VAT (MVA).
      currency:
        type: string
        default: NOK
        description: The currency for the price.
      orderTime:
        type: datetime
        example: 2017-09-01T14:00:00.000Z
        description: Timestamp for when the order was placed.
      returnAddress:
        type: AddressWithPostalName
        required: false
        description: Return address for the order if one is set
      packages:
        minItems: 1
        description: Packages in this shipment.
        type: OrderedPackage[]
  OrderedPackage:
    (hideRequired): true
    displayName: Ordered Package
    description: A single package in a successfully ordered shipment.
    properties:
      rfid:
        type: boolean
        description: Whether to [tracking for the package](#tracking-with-rfid) was activated.
      recipientName:
        type: string
        description: Recipient name.
      streetAddress:
        type: string
        description: Recipient's street address.
      postalCode:
        type: string
        description: Recipient's postal code.
      postalPlace:
        type: string
        description: The city/place for the postal code.
      phoneNumber:
        type: string
        pattern: "\\+[0-9 ]+"
        description: Recipient's phone number.
      email:
        type: string
        description: Recipient's email address.
      weight:
        maximum: 2000
        type: integer
        description: Package weight in grams.
      shipmentNumber:
        type: string
        description: The shipment number for this package. A package in a PIP shipment will have both a shipment number and a package number.
      packageNumber:
        type: string
        description: The package number for this package. This goes on the label.
      agreementNumber:
        type: boolean
        description: Whether the customer has an agreement price for this package.
  ValidatedOrder:
    (hideRequired): true
    displayName: Validated Order
    description: A valid order that can be placed.
    properties:
      testIndicator:
        type: boolean
        description: Whether the validated order had the testIndicator flag set or not.
      customerNumber:
        type: string
        description: The API customer number for the validated order.
      customerName:
        type: string
        description: The name of the customer for the validated order.
      customerOrganizationNumber:
        type: string
        description: The organization number of the customer for the validated order.
      senderName:
        type: string
        description: The sender's name.
      streetAddress:
        type: string
        description: The sender's street address.
      postalCode:
        type: string
        description: The sender's postal code.
      postalPlace:
        type: string
        description: The city/place for the postal code.
      email:
        type: string
        description: The sender's email address.
      reference:
        type: string
        description: A reference for the shipment that will be shown on the invoice.
      priceWithoutVat:
        type: number
        description: Calculated price without VAT (MVA).
      priceWithVat:
        type: number
        description: Calulated price with VAT (MVA).
      vat:
        type: number
        description: Calculated VAT (MVA).
      currency:
        type: string
        description: The price's currency.
      orderTime:
        type: datetime
        description: Timestamp for when the order was validated.
      returnAddress:
        type: AddressWithPostalName
        required: false
        description: Return address for the order if one is set
      packages:
        minItems: 1
        description: Packages in this validated shipment. The packages in the response will correspond to same order as it was in the request to make it easier for clients to do any mapping if needed.
        type: ValidatedPackage[]
  ValidatedPackage:
    (hideRequired): true
    displayName: Validated Package
    description: A single, valid package in a valid shipment.
    properties:
      rfid:
        type: boolean
        description: Whether to [tracking with RFID](#tracking-with-rfid) was activated for the package.
      recipientName:
        type: string
        description: Recipient's name.
      streetAddress:
        type: string
        description: Recipient's email address.
      postalCode:
        type: string
        description: Recipient's postal code.
      postalPlace:
        type: string
        description: The city/place for the postal code.
      phoneNumber:
        type: string
        description: Recipient's phone number.
      email:
        type: string
        description: Recipient's email address.
      weight:
        type: integer
        description: Package weight in grams.
      agreementNumber:
        type: boolean
        description: Whether the customer has an agreement price for this package.
  OrderRequest:
    (hideInDocumentation): true
    type: object
    properties:
      data:
        type: object
        description: JSON-API data object.
        properties:
          type:
            type: string
            enum: [ orders ]
            description: JSON-API type.
          attributes:
            type: Order
            description: Order properties.
  SuccessfulOrderResponse:
    (hideRequired): true
    (hideInDocumentation): true
    type: object
    properties:
      data:
        type: object
        description: JSON-API data object.
        properties:
          type:
            type: string
            description: JSON-API type.
          id: string
          attributes:
            type: SuccessfulOrder
            description: Order properties.
  ValidatedOrderResponse:
    (hideRequired): true
    (hideInDocumentation): true
    type: object
    properties:
      data:
        type: object
        description: JSON-API data object.
        properties:
          type:
            type: string
            pattern: "order"
            description: JSON-API type.
          attributes:
            type: ValidatedOrder
            description: Order properties.
  ErrorResponse:
    (hideRequired): true
    (hideInDocumentation): true
    type: object
    properties:
      errors:
        type: ErrorObject[]
        description: List of errors.
  ErrorObject:
    (hideRequired): true
    (hideInDocumentation): true
    type: object
    properties:
      code:
        type: string
        description: Machine-readable description of error.
      title:
        type: string
        description: Human-readable description of error.
      source:
        type: object
        properties:
          pointer:
            type: string
            description: A JSON pointer to the invalid field.
  PackageWithNumbers:
    displayName: Package Details
    description: Package Details with OrderID
    properties:
      rfid:
        type: boolean
        description: Whether to activate [tracking with RFID](#tracking-with-rfid) for the package.
      recipientName:
        type: string
        description: Recipient name.
      streetAddress:
        type: string
        description: Recipient's Street address.
      postalCode:
        type: string
        description: A valid Norwegian postal code.
      postalPlace:
        type: string
        description: The city/place for the postal code.
      phoneNumber:
        type: string
        pattern: "\\+[0-9 ]+"
        description: Recipient's phone number, including country code.
        example: "+4700000000"
      email:
        type: string
        description: Recipient's email address.
      weight:
        maximum: 2000
        type: integer
        description: Package weight in grams.
      shipmentNumber:
        type: string
        description: The shipment number for this package. A package in a PIP shipment will have both a shipment number and a package number.
      packageNumber:
        type: string
        description: The package number for this package. This goes on the label.
      priceType:
        type: string
        description: Whether the Price is Agreement or List
        enum: [ AGREEMENT_PRICE,  LIST_PRICE]
  OrderWithLabelResponse:
    (hideRequired): true
    displayName: Successful Order
    description: A successfully label generation that contains links to labels.
    properties:
      reference:
        type: string
        description: A reference for the shipment that will be shown on the invoice.
      senderName:
        type: string
        description: Sender's name.
      streetAddress:
        type: string
        description: Sender's street address.
      email:
        type: string
        description: Sender's email address for the order that was placed.
      labelUri:
        type: string
        description: URL to PDF label(s) for packages ordered without tracking.
      rfidLabelUri:
        type: string
        description: URL to ZPL label(s) for packages ordered with tracking.
      orderTime:
        type: datetime
        example: 2017-09-01T14:00:00.000Z
        description: Timestamp for when the order was placed.
      postalCode:
        type: string
        description: Sender's postal code.
      postalPlace:
        type: string
        description: The city/place for the postal code.
      customerNumber:
        type: string
        description: The API customer number for the validated order.
      customerName:
        type: string
        description: The API customer name for which the order was placed.
      customerOrganizationNumber:
        type: string
        description: The organization number of the customer for which the order was placed.
      testIndicator:
        type: boolean
        description: Whether the placed order had the testIndicator flag set or not.
      packages:
        minItems: 1
        description: Packages Number for the shipment.
        type: PackageWithNumbers[]
  SuccessfulLabelGenerationResponse:
    (hideRequired): true
    (hideInDocumentation): true
    type: object
    properties:
      data:
        type: object
        description: JSON-API data object.
        properties:
          type:
            type: string
            enum: [ labels ]
            description: JSON-API type.
          attributes:
            type: OrderWithLabelResponse
            description: Order properties.
  LabelRequest:
    (hideInDocumentation): true
    type: object
    properties:
      data:
        type: object
        description: JSON-API data object.
        properties:
          type:
            type: string
            enum: [ labels ]
            description: JSON-API type.
          attributes:
            type: CreateOrderRequest
            description: Order properties.
  CreateOrderRequest:
    displayName: Create Order Request
    description: It creates the Request for Label Generation.
    properties:
      customerNumber:
        type: string
        description: The API customer number for the validated order.
      senderName:
        type: string
        description: The sender's name.
      senderEmail:
        required: false
        type: string
        description: Sender's email address. Defaults to the user's email address.
      postalCode:
        type: string
        description: Sender's postal code. Must be a valid Norwegian postal code.
      streetAddress:
        type: string
        description: Recipient's email address.
      reference:
        required: false
        description: A reference for the shipment that will be shown on the invoice.
      testIndicator:
        type: boolean
        description: Whether the validated order had the testIndicator flag set or not.
      packages:
        minItems: 1
        maxItems: 500
        type: Package[]
        description: The packages to send in this shipment. Response will have packages in same order as requested to make it easier for clients to do any mapping if needed.
  LabelOrderRequest:
      (hideInDocumentation): true
      type: object
      properties:
        data:
          type: object
          description: JSON-API data object.
          properties:
            type:
              type: string
              enum: [ label_orders ]
              description: JSON-API type.
            attributes:
              type: CreateLabelOrderRequest
              description: Create Order properties.
  CreateLabelOrderRequest:
    displayName: Create Label Order Request
    description: Create Label Order Request
    properties:
      customerNumber:
        type: string
        description: The API customer number.
      packageNumbers:
        minItems: 1
        maxItems: 500
        type: string[]
        description: List of Package Numbers.
  OrderWithIdAndEdiMessage:
    displayName: Reponse of Create Order Request
    description: Reponse of Create Order Request
    properties:
      id:
        type: number
        description: The ID of the order that was placed.
      customerNumber:
        type: string
        description: The API customer number for the validated order.
      customerName:
        type: string
        description: The API customer name for which the order was placed.
      customerOrganizationNumber:
        type: string
        description: The organization number of the customer for which the order was placed.
      senderName:
        type: string
        description: Sender's name.
      streetAddress:
        type: string
        description: Sender's street address.
      email:
        type: string
        description: Sender's email address for the order that was placed.
      postalCode:
        type: string
        description: Sender's postal code.
      reference:
        type: string
        description: A reference for the shipment that will be shown on the invoice.
      labelUri:
        type: string
        description: URL to PDF label(s) for packages ordered without tracking.
      rfidLabelUri:
        type: string
        description: URL to ZPL label(s) for packages ordered with tracking.
      waybillUri:
        type: string
        description: URL to waybill PDF that has to be printed and sent with the shipment.
      orderNumberReference:
        type: string
        description: The order number reference for the placed order. This is the number on the waybill.
      priceWithoutVat:
        type: number
        description: Price of shipment without VAT (MVA).
      priceWithVat:
        type: number
        description: Price of shipment with VAT (MVA).
      vat:
        type: number
        description: How much of the price was VAT (MVA).
      currency:
        type: string
        default: NOK
        description: The currency for the price.
      orderTime:
        type: datetime
        example: 2017-09-01T14:00:00.000Z
        description: Timestamp for when the order was placed.
      returnAddress:
        type: AddressWithPostalName
        required: false
        description: Return address for the order if one is set
      packages:
        minItems: 1
        description: Packages Number for the shipment.
        type: PackageWithNumbers[]
  SuccessfulLabelOrderResponse:
     (hideRequired): true
     (hideInDocumentation): true
     type: object
     properties:
       data:
         type: object
         description: JSON-API data object.
         properties:
           type:
             type: string
             enum: [ order ]
             description: JSON-API type.
           id:
             type: string
             description: Order Id
           attributes:
             type: OrderWithIdAndEdiMessage
             description: Label Order properties.

documentation:
- title: Introduction
  content: |
    The Shipment API is a logged-in service that lets Mybring users (customers of Mybring) programatically create a instruction or a booking by invoking a Web Service by posting XML/JSON over HTTP.

    The Shipment API uses Shipping Guide as the source for price and availability (when supported in the Shipping Guide) for the different products. We advise clients of the Shipment API to use Shipping Guide API for getting the list price and checking availability before sending a booking request. Note that invoice payment is the only available payment option for the Shipment API. This means that the Mybring user ID used in the booking request must have access to the customer number specified as payer of the booking.

    We are continually rolling out support for more of Posten / Brings products and aim to support all available products in this API withing a short time. In addition to the documentation on this pages feel free to check out our [swagger page](https://bapiqa.bring.com/Shipment/swagger) for this API.

    This API has similarities with the Booking API, but there are differences. Read more about the [differences between the Booking API and the Shipment API](/api/booking-shipment/).

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

    | Header | Example | Comment |
    |:-------|:--------|:--------|
    | `X-MyBring-API-Uid` | `john.doe@example.com` | Mybring login ID |
    | `X-MyBring-API-Key` | `1234abc-abcd-1234-5678-abcd1234abcd ` | Mybring login's API key |

    Those headers must be present for authenticating requests.

/sendshipment/shipmentId={createShipmentId}&packageIds={createPackageId}:
  displayName: Create shipment
  description: |
        Sends a shipment consisting of one consignment, that must include at least one package (transportunit), from one sender to one receiver. The shipment might include additional information in regards to cash on delivery, dangerousgoods etc. If requested through the query parameteres the service will create shipmentid (for the whole shipment) in addition to package ids. The packageids will be returned in the order of the packages (ie. package 1 in the input wil have packageid 1 in returned array).

        A valid combination of an additional party, with party type TransportCompany and a valid partyId and optionally subPartyId, and service is required. In addition there might be several valueadded services that can be added. Refer to the documentation for [valid values](https://bapiqa.bring.com/Shipment/Documentation/GetServiceAndVAS?responseType=XML).

        The structure and most of the content will be validated.

  uriParameters:
    createShipmentId:
      displayName: If "true" the API will assign a shipment ID for you and return it in the response.
      type: boolean
    createPackageId:
      displayName: If "true" the API will assign all package IDs for you and return them in the response.
      type: boolean
  description: |
      Request is used to either create, update or delete an instruction for Bring.

  post:
    description: Request is used to either create, update or delete an instruction for Bring.
    headers:
          Content-Type:
            description: Specify request format (application/json, application/xml)
            required: true
            enum: [ application/json,application/xml ]
          Accept:
            description: Specify response format (application/json, application/xml)
            required: true
            enum: [ application/json,application/xml ]
    body:
      application/xml:
        examples:
          valid_request:
            displayName: Valid Request
            value: !include examples/basic_example.xml
        type:
      application/json:
        examples:
          valid_request:
            displayName: Valid Request
            value: !include examples/basic_example.json
        type:
    responses:
      200:
        description: |
          Returns a confirmation of successfull delivery and package IDs / shipment IDs if requested.
        body:
          application/xml:
            type: CreateShipmentResponse
            examples:
              valid_shipment:
                displayName: Valid Shipment
                value: !include examples/valid_shipment_response.xml
          application/json:
            type: CreateShipmentResponse
            examples:
              valid_shipment:
                displayName: Valid Shipment
                value: !include examples/valid_shipment_response.json
      400:
        displayName: Error
        description: |
          Error in validation of request or error in data structure of request.

      417:
        displayName: Error
        description: |
          Missing authentication headers.

      500:
        displayName: Error
        description: |
          Unknown error. Error sending data to destination.

      250:
        displayName: Bring Express Courier
        description: Sample request to book a Bring Express Courier shipment.
        body:
          application/xml:
            example: !include examples/basic_example.xml
          application/json:
            example: !include examples/basic_example.json

/sendbooking/shipmentId={createShipmentId}&packageIds={createPackageId}:
  displayName: Create shipment booking
  description: |
        Sends a shipment consisting of one consignment, that must include at least one package (transportunit), from one sender to one receiver. The shipment might include additional information in regards to cash on delivery, dangerousgoods etc. If requested through the query parameteres the service will create shipmentid (for the whole shipment) in addition to package ids. The packageids will be returned in the order of the packages (ie. package 1 in the input wil have packageid 1 in returned array).

        A valid combination of an additional party, with party type TransportCompany and a valid partyId and optionally subPartyId, and service is required. In addition there might be several valueadded services that can be added. Refer to the documentation for [valid values](https://bapiqa.bring.com/Shipment/Documentation/GetServiceAndVAS?responseType=XML).

        The structure and most of the content will be validated.

  uriParameters:
    createShipmentId:
      displayName: If "true" the API will assign a shipment ID for you and return it in the response.
      type: boolean
    createPackageId:
      displayName: If "true" the API will assign all package IDs for you and return them in the response.
      type: boolean
  description: |
      Request is used to either create, update or delete an instruction for Bring.

  post:
    description: Request is used to either create, update or delete an instruction for Bring.
    headers:
          Content-Type:
            description: Specify request format (application/json, application/xml)
            required: true
            enum: [ application/json,application/xml ]
          Accept:
            description: Specify response format (application/json, application/xml)
            required: true
            enum: [ application/json,application/xml ]
    body:
      application/xml:
        examples:
          valid_request:
            displayName: Valid Request
            value: !include examples/basic_example_booking.xml
        type:
      application/json:
        examples:
          valid_request:
            displayName: Valid Request
            value: !include examples/basic_example_booking.json
        type:
    responses:
      200:
        displayName: Success
        description: |
          Returns a confirmation of successfull delivery and package IDs / shipment IDs if requested.

      400:
        displayName: Error
        description: |
          Error in validation of request or error in data structure of request.

      417:
        displayName: Error
        description: |
          Missing authentication headers.

      500:
        displayName: Error
        description: |
          Unknown error. Error sending data to destination.


Removed High Volume customers and updated related for rate limit

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

documentation:
- title: Introduction
  content: |

        The Pickup Point API became authenticated from 01.11.2020

            We have now started to limit the data in the responses for unauthenticated requests:

             - From 01.11.2020, coordinates and map links have been removed from all responses.
             - From 09.11.2020, only 1 pickup point will be returned in the responses for the postal code and location endpoints

            We recommend making the adjustment as soon as possible to avoid any problems with your integration setup during peak.

      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 had a rate limit, primarily considered on a per-user basis.

      Since the Pickup Point API became authenticated from 01.11.2020, it is mandatory to be authenticated.

      There will be no rate limiting once you authenticate yourself before calling Pickuppoint API.

      #### 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 34 : Manned

      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: Authentication
  content: |
      The Pickup Point API requires authentication. To make API requests, you will need an API key from Mybring. Steps for getting a key and description of headers can be found on the general API [Getting Started / Authentication](/api/#authentication) page.

/{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

/{countryCode}/postalCode/{postalCode}/default/{mediaTypeExtension}:
  displayName: Default pickup point(s) for a postal code
  uriParameters:
    countryCode:
      displayName: Country
      enum: [ "NO" ]
    postalCode:
      displayName: Postal code
      type: string
    mediaTypeExtension:
      enum: [ .json, .xml ]
      description: Use .json to get application/json or .xml to get application/xml.
  get:
    description: List default pickup point(s) for a postal code
    responses:
      200:
        displayName: Example response for postal code 1481
        body:
          application/json:
            example: !include examples/default_pickup_point_by_postal_code.json
          application/xml:
            example: !include examples/default_pickup_point_by_postal_code.xml

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

documentation:
- title: Introduction
  content: |

        The Pickup Point API became authenticated from 01.11.2020

            We have now started to limit the data in the responses for unauthenticated requests:

             - From 01.11.2020, coordinates and map links have been removed from all responses.
             - From 09.11.2020, only 1 pickup point will be returned in the responses for the postal code and location endpoints

            We recommend making the adjustment as soon as possible to avoid any problems with your integration setup during peak.

      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 34 : Manned

      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: Authentication
  content: |
      The Pickup Point API requires authentication. To make API requests, you will need an API key from Mybring. Steps for getting a key and description of headers can be found on the general API [Getting Started / Authentication](/api/#authentication) page.

/{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

/{countryCode}/postalCode/{postalCode}/default/{mediaTypeExtension}:
  displayName: Default pickup point(s) for a postal code
  uriParameters:
    countryCode:
      displayName: Country
      enum: [ "NO" ]
    postalCode:
      displayName: Postal code
      type: string
    mediaTypeExtension:
      enum: [ .json, .xml ]
      description: Use .json to get application/json or .xml to get application/xml.
  get:
    description: List default pickup point(s) for a postal code
    responses:
      200:
        displayName: Example response for postal code 1481
        body:
          application/json:
            example: !include examples/default_pickup_point_by_postal_code.json
          application/xml:
            example: !include examples/default_pickup_point_by_postal_code.xml