baiyue-firstleg/firstleg/src/main/resources/openapi/ocean-bookings-v1.yaml

openapi: 3.0.3
info: {title: Phase 3 Ocean Booking API, version: 1.1.0}
paths:
  /api/platform/v1/ocean-bookings/channels:
    get:
      summary: List logistics channels from the current ACTIVE price book for an origin warehouse
      description: 'Requires platform:firstleg:ocean-booking:list. Returns only channels with an ACTIVE price row; the selected channel name is frozen server-side when the offline-confirmed booking is registered.'
      parameters:
        - {name: originWarehouseId, in: query, required: true, schema: {type: integer, format: int64, minimum: 1}}
      responses: {'200': {description: Available channel options, content: {application/json: {schema: {type: array, items: {$ref: '#/components/schemas/ChannelOption'}}}}}}
  /api/platform/v1/ocean-bookings:
    get:
      summary: List only real confirmed booking records
      description: 'Requires platform:firstleg:ocean-booking:list. The operational list exposes only CONFIRMED, CHANGE_PENDING, RELEASED and CANCELLED bookings; DRAFT is internal to the create transaction and legacy SUBMITTED/FAILED values are invalid.'
      parameters:
        - {name: customerId, in: query, schema: {type: integer, format: int64, minimum: 1}}
        - {name: status, in: query, schema: {type: string, enum: [CONFIRMED, CHANGE_PENDING, RELEASED, CANCELLED]}}
        - {name: keyword, in: query, schema: {type: string, maxLength: 128}}
        - {name: page, in: query, schema: {type: integer, minimum: 1, default: 1}}
        - {name: size, in: query, schema: {type: integer, minimum: 1, maximum: 200, default: 20}}
      responses: {'200': {description: Operational real booking page}}
    post:
      summary: Register an offline-confirmed ocean booking with complete transport snapshots
      description: 'Requires platform:firstleg:ocean-booking:create. The booking has already been completed offline, so registration persists it directly as CONFIRMED. RELEASED remains a separate later action.'
      parameters: [{$ref: '#/components/parameters/IdempotencyKey'}]
      requestBody: {required: true, content: {application/json: {schema: {$ref: '#/components/schemas/CreateRequest'}}}}
      responses: {'200': {description: CONFIRMED real booking detail}}
  /api/platform/v1/ocean-bookings/{oceanBookingId}/release:
    post:
      summary: Release an already registered booking and synchronize associated cabinet transport snapshots
      description: 'The transport fields were registered at create time. The request must repeat the same bill of lading, vessel, voyage, ETD and ETA values; mismatches are rejected. This action does not create cabinets, change channels, replace cabinetNo, or recreate loading plans.'
      parameters: [{$ref: '#/components/parameters/OceanBookingId'}, {$ref: '#/components/parameters/IdempotencyKey'}]
      requestBody: {required: true, content: {application/json: {schema: {$ref: '#/components/schemas/ReleaseRequest'}}}}
      responses: {'200': {description: RELEASED detail}}
components:
  parameters:
    OceanBookingId: {name: oceanBookingId, in: path, required: true, schema: {type: integer, format: int64, minimum: 1}}
    IdempotencyKey: {name: Idempotency-Key, in: header, required: true, schema: {type: string, maxLength: 128}}
  schemas:
    CreateRequest:
      type: object
      required: [expectedVersion, data]
      properties:
        expectedVersion: {type: integer, enum: [0]}
        data: {$ref: '#/components/schemas/DraftData'}
    DraftData:
      type: object
      required: [channelCode, warehouseId, warehouseName, billOfLadingNo, vesselName, voyageNo, serviceTerm, freightTerm, estimatedSailingAt, estimatedArrivalAt, parties, containerRequirements]
      properties:
        customerId: {type: integer, format: int64, minimum: 1, nullable: true, description: Optional customer snapshot; must be supplied together with customerName.}
        customerName: {type: string, maxLength: 128, nullable: true, description: Optional customer snapshot; must be supplied together with customerId.}
        channelCode: {type: string, maxLength: 64, description: Selected from GET /api/platform/v1/ocean-bookings/channels; server validates it against the current ACTIVE price book and freezes channelName.}
        warehouseId: {type: integer, format: int64, minimum: 1}
        warehouseName: {type: string, maxLength: 128}
        bookingAgentId: {type: integer, format: int64, minimum: 1, nullable: true, description: Optional ACTIVE Warehouse supplier ID validated as BOOKING with INTERNATIONAL scope.}
        bookingAgentName: {type: string, maxLength: 128, nullable: true, description: Optional consistency hint only; the persisted snapshot always comes from Warehouse and cannot be supplied without bookingAgentId.}
        serviceTerm: {type: string, maxLength: 32, description: Required free-text Service Term snapshot, for example CY-CY.}
        freightTerm: {type: string, maxLength: 32, description: Required free-text Freight Term snapshot, for example NINGBO.}
        billOfLadingNo: {type: string, maxLength: 128, description: Required offline-confirmed bill of lading snapshot.}
        vesselName: {type: string, maxLength: 128, description: Required offline-confirmed vessel snapshot.}
        voyageNo: {type: string, maxLength: 64, description: Required offline-confirmed voyage snapshot.}
        estimatedSailingAt: {type: string, format: date-time, description: Required offline-confirmed ETD snapshot.}
        estimatedArrivalAt: {type: string, format: date-time, description: Required offline-confirmed ETA snapshot; cannot be earlier than ETD.}
        parties: {type: array, minItems: 3, items: {type: object}}
        containerRequirements: {type: array, minItems: 1, maxItems: 20, items: {$ref: '#/components/schemas/ContainerRequirement'}}
    ContainerRequirement:
      type: object
      required: [containerType, containerKind, capacityCbm, maxWeightKg, quantity]
      properties:
        containerType: {type: string, enum: [20GP, 40GP, 40HC, 40NR, 45HC], description: Platform-controlled container type}
        containerKind: {type: string, maxLength: 32}
        capacityCbm: {type: number, exclusiveMinimum: true, minimum: 0, description: Must match the fixed platform specification for containerType}
        maxWeightKg: {type: number, exclusiveMinimum: true, minimum: 0, description: Must match the fixed platform specification for containerType}
        quantity: {type: integer, minimum: 1}
    ChannelOption:
      type: object
      required: [priceBookVersionId, channelCode, channelName, priceModel, pricingTaxModes]
      properties:
        priceBookVersionId: {type: integer, format: int64}
        channelCode: {type: string, maxLength: 64}
        channelName: {type: string, maxLength: 128}
        priceModel: {type: string}
        pricingTaxModes: {type: array, items: {type: string}}
    ActionRequest:
      type: object
      required: [expectedVersion]
      properties: {expectedVersion: {type: integer, minimum: 0}, reason: {type: string, maxLength: 1000}}
    ReleaseRequest:
      type: object
      required: [expectedVersion, billOfLadingNo, vesselName, voyageNo, estimatedSailingAt, estimatedArrivalAt]
      properties:
        expectedVersion: {type: integer, minimum: 0}
        billOfLadingNo: {type: string, maxLength: 128}
        vesselName: {type: string, maxLength: 128}
        voyageNo: {type: string, maxLength: 64}
        estimatedSailingAt: {type: string, format: date-time}
        estimatedArrivalAt: {type: string, format: date-time}
        reason: {type: string, maxLength: 1000}