openapi: 3.0.3
info:
  title: Bringg Fleet Partners (Self-Integrated Fleets) API
  version: '1.0'
  description: |
    Bringg's Fleet Partners API is the integration surface for delivery providers
    and self-integrated fleets connecting to the Bringg Delivery Hub. Partners
    implement webhook endpoints Bringg calls (Delivery Created, Get Quote, Order
    Updated, Order Cancelled, Return Delivery Created, Merchant Registered) and
    expose endpoints for accepting orders, updating order status, posting driver
    locations, adding proof of delivery, and managing tokens / merchant credentials.
    Authentication is OAuth 2.0 plus per-partner shared secrets for webhook
    signature verification.
  contact:
    name: Bringg Developer Support
    url: https://developers.bringg.com
  license:
    name: Bringg API Terms of Service
    url: https://developers.bringg.com/reference/terms-of-service
servers:
- url: https://app.bringg.com
  description: Bringg security gateway
- url: https://partner.example.com
  description: Partner-hosted endpoints (replace with your base URL for callbacks)
security:
- OAuth2ClientCredentials: []
paths:
  /partner/get-token:
    post:
      summary: Get Token
      description: Exchange partner credentials for an access token used to call Bringg from the partner side.
      tags: [Authentication]
      operationId: getToken
      responses:
        '200': {description: Token returned.}
  /partner/merchant-credentials:
    get:
      summary: Get Merchant Credentials
      description: Retrieve merchant-specific credentials issued by Bringg to the fleet partner.
      tags: [Authentication]
      operationId: getMerchantCredentials
      responses:
        '200': {description: Credentials returned.}
  /partner/request-driver:
    post:
      summary: Request Driver
      description: Create a delivery request from a merchant or third-party system asking the partner to fulfill an order.
      tags: [Orders]
      operationId: requestDriver
      responses:
        '200': {description: Request created.}
  /partner/cancel-order:
    post:
      summary: Cancel Order
      description: Cancel a delivery order at the partner side.
      tags: [Orders]
      operationId: cancelOrder
      responses:
        '200': {description: Cancelled.}
  /partner/complete-order:
    post:
      summary: Complete Order
      description: Notify Bringg the partner has completed the delivery.
      tags: [Orders]
      operationId: completeOrder
      responses:
        '200': {description: Completed.}
  /partner/update-order:
    post:
      summary: Update Order
      description: Update order status, driver, or other fields from the partner side.
      tags: [Orders]
      operationId: updateOrder
      responses:
        '200': {description: Updated.}
  /partner/start-order:
    post:
      summary: Start Order
      description: Indicate the partner driver has started an order.
      tags: [Orders]
      operationId: startOrder
      responses:
        '200': {description: Started.}
  /partner/check-in:
    post:
      summary: Check In / Driver Arrived To Location
      description: Partner driver arrived at a waypoint.
      tags: [Waypoints]
      operationId: partnerCheckIn
      responses:
        '200': {description: Arrived.}
  /partner/check-out:
    post:
      summary: Check Out / Driver Left Location
      description: Partner driver left a waypoint.
      tags: [Waypoints]
      operationId: partnerCheckOut
      responses:
        '200': {description: Departed.}
  /partner/cluster-checkin-checkout:
    post:
      summary: Cluster Check-in / Check-out
      description: Indicate multiple bulk arrival or departure events for clustered orders.
      tags: [Waypoints]
      operationId: clusterCheckInCheckOut
      responses:
        '200': {description: Cluster recorded.}
  /partner/driver-is-assigned-to-order:
    post:
      summary: Assign Driver
      description: Notify Bringg a partner driver has been assigned to an order.
      tags: [Drivers]
      operationId: driverIsAssignedToOrder
      responses:
        '200': {description: Assigned.}
  /partner/update-driver-location:
    post:
      summary: Update Driver Location
      description: Partner pushes driver GPS coordinates to Bringg.
      tags: [Drivers]
      operationId: partnerUpdateDriverLocation
      responses:
        '200': {description: Location updated.}
  /partner/driver-location:
    get:
      summary: Driver Location
      description: Retrieve current driver location.
      tags: [Drivers]
      operationId: getDriverLocation
      responses:
        '200': {description: Location returned.}
  /partner/note-added:
    post:
      summary: Add Note Or POD
      description: Add a note or proof-of-delivery artifact (photo, signature) to an order.
      tags: [Notes]
      operationId: noteAdded
      responses:
        '200': {description: Note added.}
  /webhooks/delivery-created:
    post:
      summary: Delivery Created Webhook
      description: Bringg notifies the partner of a new delivery to fulfill.
      tags: [Webhooks]
      operationId: webhookDeliveryCreated
      responses:
        '200': {description: Acknowledged.}
  /webhooks/get-quote:
    post:
      summary: Get Quote Webhook
      description: Bringg requests a delivery quote (price and ETA) from the partner.
      tags: [Webhooks]
      operationId: webhookGetQuote
      responses:
        '200': {description: Quote returned.}
  /webhooks/order-updated:
    post:
      summary: Delivery Updated Webhook
      description: Bringg notifies the partner an order has been updated.
      tags: [Webhooks]
      operationId: webhookOrderUpdated
      responses:
        '200': {description: Acknowledged.}
  /webhooks/order-cancelled:
    post:
      summary: Delivery Cancelled Webhook
      description: Bringg notifies the partner an order has been cancelled.
      tags: [Webhooks]
      operationId: webhookOrderCancelled
      responses:
        '200': {description: Acknowledged.}
  /webhooks/merchant-registered:
    post:
      summary: Merchant Registered Webhook
      description: Bringg notifies the partner a new merchant has subscribed to the partner's fleet.
      tags: [Webhooks]
      operationId: webhookMerchantRegistered
      responses:
        '200': {description: Acknowledged.}
  /webhooks/return-delivery-created:
    post:
      summary: Return Delivery Created Webhook
      description: Bringg notifies the partner of a return delivery to pick up.
      tags: [Webhooks]
      operationId: webhookReturnDeliveryCreated
      responses:
        '200': {description: Acknowledged.}
components:
  securitySchemes:
    OAuth2ClientCredentials:
      type: oauth2
      description: OAuth 2.0 Client Credentials Grant. Webhook callbacks are signed with a shared secret.
      flows:
        clientCredentials:
          tokenUrl: https://admin-api.bringg.com/oauth/token
          scopes:
            request_driver: Request driver fulfillment
            cancel_order: Cancel orders
            complete_order: Complete orders
            update_driver_location: Update driver location