openapi: 3.0.3
info:
  title: CargoSpot Shipments API
  version: 1.0.0
  description: >
    All endpoints share the same base URL. Shipments endpoints are secured using
    JWT Bearer tokens. Obtain a token from /v1/token, then call Shipments APIs
    with: Authorization: Bearer <access_token>
  x-gitbook-description-document:
    object: document
    data:
      schemaVersion: 9
    nodes:
      - object: block
        type: paragraph
        isVoid: false
        data: {}
        nodes:
          - object: text
            leaves:
              - object: leaf
                text: >-
                  All endpoints share the same base URL. Shipments endpoints are
                  secured using JWT Bearer tokens. Obtain a token from
                  /v1/token, then call Shipments APIs with: Authorization:
                  Bearer <access_token>
                marks: []
            key: mqgd1PZdQB2x
        key: RMRGKL7WGst8
    key: bVjPKi4ksBU1
  x-gitbook-description-html: >-
    <p>All endpoints share the same base URL. Shipments endpoints are secured
    using JWT Bearer tokens. Obtain a token from /v1/token, then call Shipments
    APIs with: Authorization: Bearer &#x3C;access_token></p>
servers:
  - url:
      base_url: null
    description: CargoSpot API Base URL
    x-gitbook-description-html: <p>CargoSpot API Base URL</p>
paths:
  /v1/token:
    post:
      summary: Get JWT Token (Client Credentials)
      operationId: getToken
      tags:
        - Auth
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/TokenRequest'
            example:
              access_key_id: YOUR_ACCESS_KEY_ID
              access_key_secret: YOUR_ACCESS_KEY_SECRET
              grant_type: client_credentials
      responses:
        '200':
          description: Token generated successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TokenResponse'
          x-gitbook-description-html: <p>Token generated successfully</p>
        '400':
          description: Invalid request
          x-gitbook-description-html: <p>Invalid request</p>
        '401':
          description: Unauthorized (invalid credentials)
          x-gitbook-description-html: <p>Unauthorized (invalid credentials)</p>
  /v1/shipments:
    post:
      summary: Create Shipment
      operationId: createShipment
      tags:
        - Shipments
      security:
        - bearerAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ShipmentCreateRequest'
            example:
              basicDetails:
                shipmentNo: string
                bolNumber: string
                instruction: string
                proNumber: string
                tmsRefNo: string
                shipmentStatus: string
                shipmentMode: string
                pickupDate: '2025-07-07'
                pickupStartTime: '2025-07-07T04:00:00.000Z'
                pickupEndTime: '2025-07-08T03:30:00.000Z'
                deliveryDate: '2025-07-08'
                deliveryStartTime: '2025-07-08T04:00:00.000Z'
                deliveryEndTime: '2025-07-09T03:30:00.000Z'
                billTo:
                  companyName: string
                  address: string
                  city: string
                  state: string
                  postalCode: string
                  contactName: string
                  contactEmail: string
                  contactPhone: string
                  phonePrefix: string
                refNums:
                  - type: string
                    value: string
              itemDetails:
                - itemName: string
                  description: string
                  quantity: 0
                  itemUnit: string
                  freightClass: string
                  nmfcNumber: string
                  totalWeight: 0
                  weightUnit: string
                  length: 0
                  width: 0
                  height: 0
                  dimensionUnit: string
                  isHazmat: false
                  isStackable: false
                  isPerishable: false
                  minimumTemperature: 0
                  maximumTemperature: 0
                  temperatureUnit: string
                  x-gitbook-description-html: <p>string</p>
              stops:
                - sequence: 1
                  stopName: string
                  address: string
                  postalCode: string
                  city: string
                  state: string
                  country: string
                  actionType: string
                  message: string
                  latitude: string
                  longitude: string
                  timeZone: US/Central
                  accessorial:
                    - accessorialName: string
                      stopActionType: string
                  contact:
                    - contactName: string
                      contactEmail: string
                      contactPhone: string
                      phonePrefix: string
                      contactType: string
              notes:
                - note: string
      responses:
        '201':
          description: Shipment created successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ShipmentCreateResponse'
          x-gitbook-description-html: <p>Shipment created successfully</p>
        '400':
          description: Invalid request
          x-gitbook-description-html: <p>Invalid request</p>
        '401':
          description: Unauthorized (missing/invalid token)
          x-gitbook-description-html: <p>Unauthorized (missing/invalid token)</p>
        '403':
          description: Forbidden
          x-gitbook-description-html: <p>Forbidden</p>
  /v1/shipments/list:
    post:
      tags:
      - Shipment Controller
      summary: Get list of shipments for the authenticated org.
      description: "Get list of shipments for the authenticated org. Same response\
        \ shape as GET /shipments/{uniqueId} but returns a list. Accepts filter in\
        \ body (pagination/filters same as shipment-dashboard)."
      operationId: getShipmentsList
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ShipmentFilterDTO'
        required: true
      responses:
        "200":
          description: getShipmentsList 200 response
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/CreateShipmentDTO'        
  /v1/shipments/{uniqueId}:
    get:
      summary: Get Shipment by ID
      operationId: getShipmentById
      tags:
        - Shipments
      security:
        - bearerAuth: []
      parameters:
        - name: uniqueId
          in: path
          required: true
          schema:
            type: string
      responses:
        '200':
          description: Shipment details retrieved successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ShipmentGetResponse'
          x-gitbook-description-html: <p>Shipment details retrieved successfully</p>
        '401':
          description: Unauthorized (missing/invalid token)
          x-gitbook-description-html: <p>Unauthorized (missing/invalid token)</p>
        '403':
          description: Forbidden
          x-gitbook-description-html: <p>Forbidden</p>
        '404':
          description: Shipment not found
          x-gitbook-description-html: <p>Shipment not found</p>
    put:
      summary: Update Shipment
      operationId: updateShipment
      tags:
        - Shipments
      security:
        - bearerAuth: []
      parameters:
        - name: uniqueId
          in: path
          required: true
          schema:
            type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ShipmentUpdateRequest'
      responses:
        '200':
          description: Shipment updated successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ShipmentGetResponse'
          x-gitbook-description-html: <p>Shipment updated successfully</p>
        '400':
          description: Invalid request
          x-gitbook-description-html: <p>Invalid request</p>
        '401':
          description: Unauthorized (missing/invalid token)
          x-gitbook-description-html: <p>Unauthorized (missing/invalid token)</p>
        '403':
          description: Forbidden
          x-gitbook-description-html: <p>Forbidden</p>
        '404':
          description: Shipment not found
          x-gitbook-description-html: <p>Shipment not found</p>
components:
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT
  schemas:
    TokenRequest:
      type: object
      required:
        - access_key_id
        - access_key_secret
        - grant_type
      properties:
        access_key_id:
          type: string
        access_key_secret:
          type: string
        grant_type:
          type: string
          example: client_credentials
    TokenResponse:
      type: object
      required:
        - access_token
        - token_type
      properties:
        access_token:
          type: string
          description: JWT access token
          x-gitbook-description-html: <p>JWT access token</p>
        token_type:
          type: string
          example: Bearer
        expires_in:
          type: integer
          description: Token lifetime in seconds
          x-gitbook-description-html: <p>Token lifetime in seconds</p>
        scope:
          type: string
          description: Optional scope string returned by the auth server
          x-gitbook-description-html: <p>Optional scope string returned by the auth server</p>
    ShipmentCreateRequest:
      $ref: '#/components/schemas/ShipmentPayload'
    ShipmentUpdateRequest:
      $ref: '#/components/schemas/ShipmentPayload'
    ShipmentCreateResponse:
      type: object
      required:
        - uniqueId
      properties:
        uniqueId:
          type: string
          example: 8f3b2d90
    ShipmentGetResponse:
      allOf:
        - type: object
          required:
            - uniqueId
          properties:
            uniqueId:
              type: string
              example: 8f3b2d90
        - $ref: '#/components/schemas/ShipmentPayload'
    ShipmentPayload:
      type: object
      required:
        - basicDetails
      properties:
        basicDetails:
          $ref: '#/components/schemas/BasicDetails'
        itemDetails:
          type: array
          items:
            $ref: '#/components/schemas/ItemDetail'
        stops:
          type: array
          items:
            $ref: '#/components/schemas/Stop'
        notes:
          type: array
          items:
            $ref: '#/components/schemas/Note'
    BasicDetails:
      type: object
      properties:
        shipmentNo:
          type: string
        bolNumber:
          type: string
        instruction:
          type: string
        proNumber:
          type: string
        tmsRefNo:
          type: string
        shipmentStatus:
          type: string
        shipmentMode:
          type: string
        pickupDate:
          type: string
          format: date
          example: '2025-07-07'
        pickupStartTime:
          type: string
          format: date-time
          example: '2025-07-07T04:00:00.000Z'
        pickupEndTime:
          type: string
          format: date-time
          example: '2025-07-08T03:30:00.000Z'
        deliveryDate:
          type: string
          format: date
          example: '2025-07-08'
        deliveryStartTime:
          type: string
          format: date-time
          example: '2025-07-08T04:00:00.000Z'
        deliveryEndTime:
          type: string
          format: date-time
          example: '2025-07-09T03:30:00.000Z'
        billTo:
          $ref: '#/components/schemas/BillTo'
        refNums:
          type: array
          items:
            $ref: '#/components/schemas/RefNum'
    BillTo:
      type: object
      properties:
        companyName:
          type: string
        address:
          type: string
        city:
          type: string
        state:
          type: string
        postalCode:
          type: string
        contactName:
          type: string
        contactEmail:
          type: string
          format: email
        contactPhone:
          type: string
        phonePrefix:
          type: string
    RefNum:
      type: object
      properties:
        type:
          type: string
        value:
          type: string
    ItemDetail:
      type: object
      properties:
        itemName:
          type: string
        description:
          type: string
        quantity:
          type: integer
          format: int32
        itemUnit:
          type: string
        freightClass:
          type: string
        nmfcNumber:
          type: string
        totalWeight:
          type: number
          format: double
        weightUnit:
          type: string
        length:
          type: number
          format: double
        width:
          type: number
          format: double
        height:
          type: number
          format: double
        dimensionUnit:
          type: string
        isHazmat:
          type: boolean
        isStackable:
          type: boolean
        isPerishable:
          type: boolean
        minimumTemperature:
          type: number
          format: double
        maximumTemperature:
          type: number
          format: double
        temperatureUnit:
          type: string
    Stop:
      type: object
      properties:
        sequence:
          type: integer
          format: int32
          example: 1
        stopName:
          type: string
        address:
          type: string
        postalCode:
          type: string
        city:
          type: string
        state:
          type: string
        country:
          type: string
        actionType:
          type: string
        message:
          type: string
        latitude:
          type: string
        longitude:
          type: string
        timeZone:
          type: string
          example: US/Central
        accessorial:
          type: array
          items:
            $ref: '#/components/schemas/Accessorial'
        contact:
          type: array
          items:
            $ref: '#/components/schemas/StopContact'
    Accessorial:
      type: object
      properties:
        accessorialName:
          type: string
        stopActionType:
          type: string
    StopContact:
      type: object
      properties:
        contactName:
          type: string
        contactEmail:
          type: string
          format: email
        contactPhone:
          type: string
        phonePrefix:
          type: string
        contactType:
          type: string
    Note:
      type: object
      properties:
        note:
          type: string
    ShipmentFilterDTO:
      type: object
      properties:
        shipmentNo:
          type: string
        bolNumber:
          type: string
          description: Filter by BOL number (partial match).
        proNumber:
          type: string
          description: Filter by PRO number (partial match).
        referenceNumber:
          type: string
          description: Filter by any reference number on the shipment (partial match).
        uniqueId:
          type: string
        status:
          type: array
          items:
            type: string
        deliveryEndDate:
          type: string
          format: date
        deliveryStartDate:
          type: string
          format: date
        pickupEndDate:
          type: string
          format: date
        pickupStartDate:
          type: string
          format: date
        trackerTypes:
          type: array
          items:
            type: string
        shipmentModeCd:
          type: integer
          format: int64
        isFlagged:
          type: boolean
        actionRequired:
          type: boolean
        page:
          type: integer
          format: int32
        size:
          type: integer
          format: int32
        sortColumn:
          type: string
        sortOrder:
          type: string
        shipmentMode:
          type: array
          items:
            type: string
        carrierOrgIds:
          type: array
          items:
            type: integer
            format: int64
        driverIds:
          type: array
          items:
            type: integer
            format: int64
        sourceLocationIds:
          type: array
          items:
            type: string
            format: uuid
        destinationLocationIds:
          type: array
          items:
            type: string
            format: uuid
        customerIds:
          type: array
          items:
            type: string
            format: uuid
        vehicleIds:
          type: array
          items:
            type: string
            format: uuid
        itemIds:
          type: array
          items:
            type: string
            format: uuid