openapi: 3.0.3
info:
  title: VenixPin Merchant Delivery API
  version: 1.0.0
  description: Tenant-scoped merchant order and customer delivery confirmation API.
servers:
  - url: https://www.venixpin.app
security:
  - merchantBearer: []
components:
  securitySchemes:
    merchantBearer:
      type: http
      scheme: bearer
      bearerFormat: VenixPin merchant API key
  schemas:
    OrderInput:
      type: object
      required: [reference]
      properties:
        reference: { type: string, minLength: 2, maxLength: 60 }
        customer_name: { type: string, maxLength: 80 }
        customer_phone: { type: string, maxLength: 16 }
        instructions: { type: string, maxLength: 500 }
    Error:
      type: object
      properties:
        error: { type: string }
paths:
  /api/v1/orders:
    get:
      summary: List current merchant orders
      parameters:
        - in: query
          name: limit
          schema: { type: integer, minimum: 1, maximum: 100 }
        - in: query
          name: status
          schema: { type: string }
      responses:
        '200': { description: Orders returned }
        '401': { description: Invalid API key }
        '429': { description: Hourly quota exceeded }
    post:
      summary: Create a merchant delivery order
      parameters:
        - in: header
          name: Idempotency-Key
          schema: { type: string }
      requestBody:
        required: true
        content:
          application/json:
            schema: { $ref: '#/components/schemas/OrderInput' }
      responses:
        '201': { description: Order created }
        '409': { description: Duplicate order reference }
  /api/v1/orders/{id}:
    parameters:
      - in: path
        name: id
        required: true
        schema: { type: string, format: uuid }
    get:
      summary: Retrieve an order and confirmation state
      responses:
        '200': { description: Order returned }
        '404': { description: Order not found }
    patch:
      summary: Update order status, assign an existing rider or record fees/costs
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [status]
              properties:
                status: { type: string, enum: [pending, assigned, out_for_delivery, failed, cancelled] }
                rider_user_id: { type: string, format: uuid }
                fee_naira: { type: integer, minimum: 0 }
                cost_naira: { type: integer, minimum: 0 }
      responses:
        "200": { description: Order updated }
        "409": { description: Order is closed }
    post:
      summary: Generate one-time customer confirmation link
      responses:
        '201': { description: URL generated, valid seven days }
        '409': { description: Order cannot be confirmed }