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

openapi: 3.0.3
info: {title: Ocean Booking API, version: 2.0.0}
paths:
  /api/platform/v1/ocean-bookings:
    get: {summary: List DRAFT and RELEASED bookings, responses: {'200': {description: Booking page}}}
    post:
      summary: Create an editable DRAFT
      description: Creates only the booking aggregate and container requirements; no containerNo, container row, or allocation is created.
      parameters: [{$ref: '#/components/parameters/IdempotencyKey'}]
      requestBody: {required: true, content: {application/json: {schema: {$ref: '#/components/schemas/CreateRequest'}}}}
      responses: {'200': {description: DRAFT detail}}
  /api/platform/v1/ocean-bookings/{oceanBookingId}:
    get: {summary: Get booking detail, parameters: [{$ref: '#/components/parameters/OceanBookingId'}], responses: {'200': {description: Detail}}}
    put:
      summary: Replace a DRAFT
      parameters: [{$ref: '#/components/parameters/OceanBookingId'}, {$ref: '#/components/parameters/IdempotencyKey'}]
      requestBody: {required: true, content: {application/json: {schema: {$ref: '#/components/schemas/UpdateRequest'}}}}
      responses: {'200': {description: Updated DRAFT}}
    delete:
      summary: Delete a DRAFT; RELEASED is immutable
      parameters: [{$ref: '#/components/parameters/OceanBookingId'}, {$ref: '#/components/parameters/IdempotencyKey'}]
      requestBody: {required: true, content: {application/json: {schema: {$ref: '#/components/schemas/ActionRequest'}}}}
      responses: {'200': {description: Deleted}}
  /api/platform/v1/ocean-bookings/{oceanBookingId}/release:
    post:
      summary: Validate and permanently release a DRAFT
      description: Release validates the persisted aggregate and never requires or creates a real container number.
      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}}
  /api/platform/v1/ocean-bookings/channels:
    get:
      summary: List ACTIVE channels for an origin warehouse
      description: Requires platform:firstleg:ocean-booking:list. Channel names are resolved from the current ACTIVE price book and frozen by the server on save.
      parameters:
        - {name: originWarehouseId, in: query, required: true, schema: {type: integer, format: int64, minimum: 1}}
      responses:
        '200':
          description: Channel options
          content:
            application/json:
              schema: {type: array, items: {$ref: '#/components/schemas/ChannelOption'}}
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'}}}
    UpdateRequest: {type: object, required: [expectedVersion, data], properties: {expectedVersion: {type: integer, minimum: 0}, data: {$ref: '#/components/schemas/DraftData'}}}
    DraftData:
      type: object
      description: Fields may be incomplete in DRAFT. RELEASE validates the complete persisted aggregate.
      properties:
        customerId: {type: integer, format: int64, nullable: true}
        customerName: {type: string, nullable: true}
        channelCode: {type: string, nullable: true}
        warehouseId: {type: integer, format: int64, nullable: true}
        billOfLadingNo: {type: string, nullable: true}
        shippingCompanyId: {type: integer, format: int64, nullable: true}
        shippingCompanyName: {type: string, nullable: true}
        bookingAgentId:
          type: integer
          format: int64
          nullable: true
          description: Warehouse supplier ID; release validates ACTIVE category BOOKING; booking suppliers do not use domestic/international scope.
        bookingAgentName:
          type: string
          nullable: true
          description: Read-only consistency hint; the persisted snapshot always comes from Warehouse.
        vesselName: {type: string, nullable: true}
        voyageNo: {type: string, nullable: true}
        departurePortCode: {type: string, nullable: true}
        departurePortName: {type: string, nullable: true}
        destinationPortCode: {type: string, nullable: true}
        destinationPortName: {type: string, nullable: true}
        placeOfDelivery: {type: string, nullable: true}
        serviceTerm: {type: string, nullable: true}
        freightTerm: {type: string, nullable: true}
        estimatedSailingAt: {type: string, format: date-time, nullable: true}
        estimatedArrivalAt: {type: string, format: date-time, nullable: true}
        remark: {type: string, nullable: true}
        parties: {type: array, nullable: true, items: {$ref: '#/components/schemas/PartyRequest'}}
        containerRequirements: {type: array, nullable: true, items: {$ref: '#/components/schemas/ContainerRequirementRequest'}}
    PartyRequest: {type: object, required: [partyType, partyName], properties: {partyType: {type: string, enum: [SHIPPER, CONSIGNEE, NOTIFY_PARTY]}, partyName: {type: string}, address: {type: string, nullable: true}, contactName: {type: string, nullable: true}, contactPhone: {type: string, nullable: true}}}
    ContainerRequirementRequest: {type: object, required: [containerType, containerKind, quantity, capacityCbm, maxWeightKg], properties: {containerType: {type: string}, containerKind: {type: string}, quantity: {type: integer, minimum: 1}, capacityCbm: {type: number, exclusiveMinimum: true, minimum: 0}, maxWeightKg: {type: number, exclusiveMinimum: true, minimum: 0}}}
    ReleaseRequest: {type: object, required: [expectedVersion], properties: {expectedVersion: {type: integer, minimum: 0}, reason: {type: string, nullable: true}}}
    ActionRequest: {type: object, required: [expectedVersion], properties: {expectedVersion: {type: integer, minimum: 0}, reason: {type: string, nullable: true}}}
    ChannelOption:
      type: object
      required: [priceBookVersionId, channelCode, channelName, priceModel, pricingTaxModes]
      properties:
        priceBookVersionId: {type: integer, format: int64}
        channelCode: {type: string}
        channelName: {type: string}
        priceModel: {type: string}
        pricingTaxModes: {type: array, items: {type: string}}
    Detail: {type: object, required: [oceanBooking, parties, containerRequirements, containers, histories], properties: {oceanBooking: {type: object}, parties: {type: array}, containerRequirements: {type: array}, containers: {type: array, description: Existing containers allocated after port pickup linking}, histories: {type: array}}}