Bounce webhooks for Oxpoint

openapi.yml

openapi: 3.0.1
info:
  title: "Bounce API"
  description: "API documentation for Bounce locker events integration."
  version: "1.0.0"
servers:
  - url: "https://bounce-api-preview-deploy-test.onrender.com"
    description: "Bounce API preview environment"
  - url: "https://luggage-storage-api.usebounce.com"
    description: "Bounce API production environment"
components:
  securitySchemes:
    basicAuth:
      type: http
      scheme: basic
  schemas:
    AccessCredentialsActionDto:
      type: string
      enum:
        - Store
        - Peek
        - Pickup
        - StockIn
        - StockOut
      description: >-
        Specify allowed action for given access credentials.
        Members:
        - Store: End user can store content
        - Peek: End user can access contents without ending reservation
        - Pickup: End user can pick up content
        - StockIn: Courier delivers contents
        - StockOut: Courier stocks out contents not picked up by end user

    AccessCredentialsDto:
      type: object
      properties:
        personIdentifier:
          type: string
          nullable: true
          description: Optional person identifier created and owned by integrated partner
        pinCode:
          type: string
          nullable: true
          description: PIN code
        phoneNumber:
          type: string
          nullable: true
          description: Phone number - must be valid according to E.164 standard
        actions:
          type: array
          items:
            $ref: '#/components/schemas/AccessCredentialsActionDto'
          description: Possible actions for which the access credentials can be used
        pointId:
          type: string
          format: uuid
          nullable: true
          description: Unique identifier of point where access credentials can be used
        installationId:
          type: string
          format: uuid
          nullable: true
          description: Unique identifier of installation where access credentials can be used
        reservationId:
          type: string
          format: uuid
          nullable: true
          description: Unique identifier of reservation for which the access credentials can be used
        validFrom:
          type: string
          format: date-time
          nullable: true
          description: Validity from
        validTo:
          type: string
          format: date-time
          nullable: true
          description: Validity to
      additionalProperties: false
      description: Access credentials locality, validity boundaries, and purposes details

    StatusEnum:
      type: string
      enum:
        - ReservationCancelled
        - ContentRefusedOversized
        - ContentRefusedNoSuitableStorageUnit
        - ReservationStarted
        - ReservationExpired
        - AllocationStarted
        - ContentPickedUp
        - AllocationExpired
        - ContentStockedOut
      description: Reservation status enumeration

    TrackingIdentifierDto:
      type: object
      properties:
        identifier:
          type: string
          description: Unique identifier
        personIdentifier:
          type: string
          nullable: true
          description: Optional person identifier created and owned by integrated partner
        pinCode:
          type: string
          nullable: true
          description: PIN code
        phoneNumber:
          type: string
          nullable: true
          description: Phone number - must be valid according to E.164 standard
        actions:
          type: array
          items:
            $ref: '#/components/schemas/AccessCredentialsActionDto'
          description: Possible actions for which the access credentials can be used
        pointId:
          type: string
          format: uuid
          nullable: true
          description: Unique identifier of point
        installationId:
          type: string
          format: uuid
          nullable: true
          description: Unique identifier of installation
        reservationId:
          type: string
          format: uuid
          nullable: true
          description: Unique identifier of reservation
        validFrom:
          type: string
          format: date-time
          nullable: true
          description: Validity from
        validTo:
          type: string
          format: date-time
          nullable: true
          description: Validity to
      additionalProperties: false
      description: Parcel tracking identifier and access rules

    StatusChangeDto:
      type: object
      properties:
        reservationId:
          type: string
          format: uuid
          nullable: true
          description: Id of the reservation
        trackingIdentifiers:
          type: array
          items:
            $ref: '#/components/schemas/TrackingIdentifierDto'
          nullable: true
          description: Tracking identifiers for reservation
        pointId:
          type: string
          format: uuid
          description: Point id for reservation
        status:
          $ref: '#/components/schemas/StatusEnum'
          description: New status for reservation
        accessCredential:
          $ref: '#/components/schemas/AccessCredentialsDto'
          nullable: true
          description: Access credential used for the status change
      additionalProperties: false
      description: Dto for reservation status change details

    SuccessResponse:
      type: object
      properties:
        status:
          type: string
          enum: [ok]
      example:
        status: ok

    ErrorResponse:
      type: object
      properties:
        status:
          type: string
          enum: [error]
      example:
        status: error

paths:
  /oxpoint-hooks:
    post:
      summary: "Listen to reservation state change events"
      description: "This endpoint receives events when a reservation changes state due to a dropoff or pickup code being used."
      security:
        - basicAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/StatusChangeDto'
      responses:
        '200':
          description: "Event logged successfully"
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SuccessResponse'
        '400':
          description: "Bad request due to invalid payload or validation error"
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: "Server error while processing the event"

security:
  - basicAuth: []