openapi: 3.0.3
info:
  title: Topping Courier GTA API
  version: "1.0"
  description: >
    Submit GTA delivery requests, monitor status, and cancel jobs. Authenticate every request with
    `Authorization: Bearer {API_KEY}`. Credits are required for every automated shipment.
servers:
  - url: https://toppingcourier.com
components:
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: API_KEY
  schemas:
    ShipmentRequest:
      type: object
      required:
        - service_level
        - pickup_phone
        - pickup_address
        - customer_name
        - customer_phone
        - customer_address
        - pickup_date
        - pickup_time
      properties:
        service_level:
          type: string
          enum: [regular_same_day, express_3h, rush_90min]
          description: Service level for the delivery
        customer_type:
          type: string
          enum: [retail, corporate]
          default: corporate
          description: Type of customer
        distance_km:
          type: number
          minimum: 0.1
          description: Pre-calculated distance in kilometers (optional, will be calculated if omitted)
        distance_text:
          type: string
          maxLength: 191
          description: Human-readable distance text
        duration_text:
          type: string
          maxLength: 191
          description: Human-readable duration text
        duration_seconds:
          type: number
          minimum: 0
          description: Duration in seconds
        zone_label:
          type: string
          maxLength: 191
          description: Zone label for pricing
        flags:
          type: object
          description: Additional flags
        distance_meta:
          type: object
          description: Additional distance metadata
        surcharges:
          type: array
          items:
            type: object
            required:
              - code
            properties:
              code:
                type: string
                description: Surcharge code (e.g., after_hours, signature_required)
              quantity:
                type: integer
                minimum: 0
                default: 1
                description: Quantity of surcharge
        pickup_name:
          type: string
          maxLength: 191
          description: Name of pickup contact
        pickup_phone:
          type: string
          maxLength: 191
          description: Phone number of pickup contact
        pickup_address:
          type: string
          maxLength: 500
          description: Full pickup address
        pickup_lat:
          type: number
          description: Pickup latitude coordinate
        pickup_lng:
          type: number
          description: Pickup longitude coordinate
        pickup_postal_code:
          type: string
          maxLength: 50
          description: Pickup postal code
        customer_name:
          type: string
          maxLength: 191
          description: Name of recipient
        customer_phone:
          type: string
          maxLength: 191
          description: Phone number of recipient
        customer_address:
          type: string
          maxLength: 500
          description: Full delivery address
        customer_lat:
          type: number
          description: Delivery latitude coordinate
        customer_lng:
          type: number
          description: Delivery longitude coordinate
        customer_postal_code:
          type: string
          maxLength: 50
          description: Delivery postal code
        pickup_date:
          type: string
          format: date
          description: Pickup date in YYYY-MM-DD format (must be today or future)
        pickup_time:
          type: string
          pattern: '^([0-1][0-9]|2[0-3]):[0-5][0-9]$'
          description: Pickup time in HH:mm format (24-hour)
        note:
          type: string
          description: Delivery instructions or notes
        promo_code:
          type: string
          maxLength: 191
          description: Promotional code
    QuoteResponse:
      type: object
      properties:
        quote:
          type: object
          description: Quote details
        distance:
          type: object
          properties:
            km:
              type: number
            text:
              type: string
            duration_text:
              type: string
    ShipmentResponse:
      type: object
      properties:
        message:
          type: string
        tracking_id:
          type: string
        parcel_id:
          type: integer
        grand_total:
          type: number
    ShipmentDetails:
      type: object
      properties:
        tracking_id:
          type: string
        status:
          type: string
        customer_name:
          type: string
        customer_phone:
          type: string
        pickup_date:
          type: string
        pickup_time:
          type: string
        grand_total:
          type: number
    ErrorResponse:
      type: object
      properties:
        message:
          type: string
        errors:
          type: array
          items:
            type: string
security:
  - bearerAuth: []
paths:
  /api/gta-api/shipments/quote:
    post:
      summary: Get price quote for a shipment
      description: Get a price quote for a GTA delivery without creating the shipment. Useful for displaying pricing to customers before they commit.
      tags: [Shipments]
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ShipmentRequest'
      responses:
        "200":
          description: Quote calculated successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/QuoteResponse'
        "401":
          description: Unauthorized - Missing or invalid API key
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        "422":
          description: Validation error or unable to calculate distance
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /api/gta-api/shipments:
    post:
      summary: Create GTA shipment
      description: Create a GTA delivery request. Credits will be deducted from your GTA API wallet upon successful creation.
      tags: [Shipments]
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ShipmentRequest'
            example:
              service_level: express_3h
              distance_km: 12.4
              pickup_name: Operations
              pickup_phone: "416-555-0123"
              pickup_address: "124 Front St W, Toronto, ON"
              pickup_date: "2025-11-16"
              pickup_time: "14:30"
              customer_name: "GTA Retail Store"
              customer_phone: "647-555-9977"
              customer_address: "55 Bloor St W, Toronto, ON"
              note: "Signature required"
              surcharges:
                - code: after_hours
                  quantity: 1
      responses:
        "201":
          description: Shipment created successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ShipmentResponse'
              example:
                message: "Shipment created successfully."
                tracking_id: "GT12345678"
                parcel_id: 9123
                grand_total: 18.75
        "401":
          description: Unauthorized - Missing or invalid API key
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        "402":
          description: Payment Required - Insufficient GTA API credits
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        "422":
          description: Validation error or unable to calculate distance
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /api/gta-api/shipments/{tracking_id}:
    get:
      summary: Get GTA shipment details
      description: Retrieve the current status and details of a GTA API shipment.
      tags: [Shipments]
      parameters:
        - in: path
          name: tracking_id
          required: true
          schema:
            type: string
          description: Tracking ID of the shipment
      responses:
        "200":
          description: Shipment details returned
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ShipmentDetails'
        "401":
          description: Unauthorized - Missing or invalid API key
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        "404":
          description: Shipment not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /api/gta-api/shipments/{tracking_id}/cancel:
    post:
      summary: Cancel GTA shipment
      description: Cancel a pending shipment. Credits will be refunded to your GTA API wallet if the shipment is still in a cancellable state (pending or pickup assigned).
      tags: [Shipments]
      parameters:
        - in: path
          name: tracking_id
          required: true
          schema:
            type: string
          description: Tracking ID of the shipment to cancel
      responses:
        "200":
          description: Shipment cancelled and credits refunded
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    example: "Shipment cancelled and credits refunded."
        "401":
          description: Unauthorized - Missing or invalid API key
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        "404":
          description: Shipment not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        "409":
          description: Shipment is no longer cancellable
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
