description:Every truck appointment must select one RELEASED ocean booking and its allocated ACTIVE internal container identity. A real ISO 6346 container number is not required for create, edit, submit or dispatch. PICKUP may omit it and still advances normally; when supplied, PICKUP atomically records it if still missing or reuses the existing valid number. The bill-of-lading number is frozen from the booking, and the booking must own at least one active BOOKING_CONFIRMATION or BILL_OF_LADING file under OCEAN_BOOKING_DOCUMENT. Booking and bill files are not owned by truck appointments. After a PDA loading transaction commits, the server best-effort completes the unique active appointment explicitly linked to that container in an isolated transaction; absence, duplicates or concurrent truck edits never roll back loading completion.
description:If the real container already has a non-terminal appointment, the server returns A0409 with the existing appointment number and instructs the operator to continue editing. This duplicate guard runs before booking-document validation; the database unique key provides the same response for concurrent creates.
'409':{description:'A0409 - this container already has a non-terminal appointment; message includes its appointment number and asks the operator to continue editing'}
summary:Query authoritative create-time ocean-booking and internal-container candidates
description:Requires platform:firstleg:truck-appointment:list. Returns only RELEASED bookings with an active booking-owned confirmation or bill file and allocated ACTIVE internal containers that have no non-terminal truck appointment and whose loading plan is absent or not COMPLETED. A missing containerNo remains eligible. Completed/LOADED containers, occupied containers and bookings without any remaining eligible allocated container are absent. Edit pages must display their current binding from appointment detail rather than injecting it into this create-only candidate result.
parameters:
- {name:keyword, in:query, required:false, schema:{type:string, maxLength:64}, description:Matches booking number, bill of lading, cabinet number or real container number}
description:PICKUP accepts optional containerNo. Omitting it never blocks the transition to PICKUP_IN_PROGRESS; when supplied, the server atomically records it on the linked internal container if missing. An existing valid ISO 6346 number may be omitted or resubmitted unchanged; a different value is rejected and must use the preload correction flow. Other actions reject containerNo. ARRIVE, LOAD and DEPART persist their actual event timestamps atomically with the status transition.
summary:Reference a platform-owned file already scoped to this appointment
description:'Requires platform:firstleg:truck-appointment:edit. The file must belong to platform scope + TRUCK_APPOINTMENT_ATTACHMENT + appointmentId.'
attachmentType:{type:string, enum:[DISPATCH_ORDER, DRIVER_DOCUMENT, VEHICLE_DOCUMENT, OTHER], description:Booking confirmations and bills of lading belong to the ocean-booking aggregate}
containerNo:{type:string, maxLength:32, nullable:true, description:Optional and only valid for PICKUP. Omission does not block PICKUP; when supplied it is normalized and validated as unique ISO 6346 before being written atomically. A different value from an existing number is rejected and must use preload correction.}
oceanBookingId:{type:integer, format:int64, minimum:1, description:Required RELEASED booking; must own an active BOOKING_CONFIRMATION or BILL_OF_LADING file.}
containerBookingId:{type:integer, format:int64, minimum:1, description:Required ACTIVE internal container already allocated to oceanBookingId. Its real ISO 6346 number may remain empty until PICKUP.}
loadingPlanId:{type:integer, format:int64, minimum:1, nullable:true, description:Optional loading-plan association. It may be supplied only with containerBookingId and must be that container's current plan.}
warehouseId:{type:integer, format:int64, minimum:1, nullable:true, description:Optional warehouse scope. Linked booking/container warehouse facts must agree; when omitted the linked fact is frozen if available.}
carrierId:{type:integer, format:int64, minimum:1, description:Required ACTIVE Warehouse supplier ID validated as TRUCKING.}
carrierName:{type:string, maxLength:128, nullable:true, description:Optional consistency hint only; the persisted snapshot comes from Warehouse supplier master data.}
billOfLadingNo:{type:string, maxLength:128, nullable:true, description:Optional consistency hint; the persisted snapshot is always frozen from the selected RELEASED booking.}
description:Stable IDs plus server-resolved saved resource names returned by appointment detail. Ocean booking and container associations are always present.
