138 lines
5.3 KiB
YAML
138 lines
5.3 KiB
YAML
openapi: 3.0.3
|
|
info:
|
|
title: Truck Appointment API
|
|
version: 1.1.0
|
|
paths:
|
|
/api/platform/v1/truck-appointments:
|
|
get:
|
|
summary: Query truck appointments
|
|
responses:
|
|
'200': {description: Paged truck appointments}
|
|
post:
|
|
summary: Create a truck appointment linked to a released ocean booking
|
|
requestBody:
|
|
required: true
|
|
content:
|
|
application/json:
|
|
schema: {$ref: '#/components/schemas/SaveRequest'}
|
|
responses:
|
|
'200': {description: Created appointment}
|
|
/api/platform/v1/truck-appointments/{id}:
|
|
parameters: [{$ref: '#/components/parameters/AppointmentId'}]
|
|
get:
|
|
summary: Query a truck appointment
|
|
responses:
|
|
'200': {description: Appointment detail}
|
|
put:
|
|
summary: Update an editable truck appointment with optimistic locking
|
|
requestBody:
|
|
required: true
|
|
content:
|
|
application/json:
|
|
schema: {$ref: '#/components/schemas/SaveRequest'}
|
|
responses:
|
|
'200': {description: Updated appointment}
|
|
/api/platform/v1/truck-appointments/{id}/{action}:
|
|
parameters:
|
|
- {$ref: '#/components/parameters/AppointmentId'}
|
|
- {$ref: '#/components/parameters/Action'}
|
|
- {$ref: '#/components/parameters/IdempotencyKey'}
|
|
- {$ref: '#/components/parameters/RequestHash'}
|
|
post:
|
|
summary: Apply an idempotent appointment lifecycle action
|
|
description: ARRIVE, LOAD and DEPART persist their actual event timestamps atomically with the status transition.
|
|
requestBody:
|
|
required: true
|
|
content:
|
|
application/json:
|
|
schema: {$ref: '#/components/schemas/ActionRequest'}
|
|
responses:
|
|
'200': {description: Updated or replayed appointment}
|
|
/api/platform/v1/truck-appointments/{id}/reschedule:
|
|
parameters:
|
|
- {$ref: '#/components/parameters/AppointmentId'}
|
|
- {$ref: '#/components/parameters/IdempotencyKey'}
|
|
- {$ref: '#/components/parameters/RequestHash'}
|
|
- name: plannedLoadingAt
|
|
in: query
|
|
required: true
|
|
schema: {type: string, format: date-time}
|
|
post:
|
|
summary: Idempotently reschedule an appointment
|
|
requestBody:
|
|
required: true
|
|
content:
|
|
application/json:
|
|
schema: {$ref: '#/components/schemas/ActionRequest'}
|
|
responses:
|
|
'200': {description: Rescheduled or replayed appointment}
|
|
/api/platform/v1/truck-appointments/{id}/history:
|
|
parameters: [{$ref: '#/components/parameters/AppointmentId'}]
|
|
get:
|
|
summary: Query immutable appointment status history
|
|
responses:
|
|
'200': {description: History entries including action, from/to status, operator, reason and time}
|
|
/api/platform/v1/truck-appointments/{id}/attachments:
|
|
parameters: [{$ref: '#/components/parameters/AppointmentId'}]
|
|
get:
|
|
summary: Query attachment references owned by the appointment
|
|
responses:
|
|
'200': {description: Attachment references}
|
|
post:
|
|
summary: Reference a file already owned by the appointment customer and business scope
|
|
responses:
|
|
'200': {description: Created attachment reference}
|
|
/api/platform/v1/truck-appointments/{id}/attachments/upload:
|
|
parameters: [{$ref: '#/components/parameters/AppointmentId'}]
|
|
post:
|
|
summary: Upload and reference a truck appointment attachment
|
|
requestBody:
|
|
required: true
|
|
content:
|
|
multipart/form-data:
|
|
schema:
|
|
type: object
|
|
required: [file]
|
|
properties:
|
|
attachmentType: {type: string, maxLength: 32}
|
|
file: {type: string, format: binary}
|
|
responses:
|
|
'200': {description: Uploaded attachment reference}
|
|
/api/platform/v1/truck-appointments/{id}/attachments/{attachmentId}:
|
|
parameters:
|
|
- {$ref: '#/components/parameters/AppointmentId'}
|
|
- {$ref: '#/components/parameters/AttachmentId'}
|
|
delete:
|
|
summary: Delete an attachment reference owned by the appointment
|
|
responses:
|
|
'200': {description: Reference deleted}
|
|
components:
|
|
parameters:
|
|
AppointmentId: {name: id, in: path, required: true, schema: {type: string, pattern: '^[1-9][0-9]*$'}}
|
|
AttachmentId: {name: attachmentId, in: path, required: true, schema: {type: string, pattern: '^[1-9][0-9]*$'}}
|
|
Action:
|
|
name: action
|
|
in: path
|
|
required: true
|
|
schema:
|
|
type: string
|
|
enum: [SUBMIT, DISPATCH, PICKUP, ARRIVE, LOAD, DEPART, COMPLETE, EXCEPTION, CANCEL]
|
|
IdempotencyKey: {name: Idempotency-Key, in: header, required: true, schema: {type: string, maxLength: 128}}
|
|
RequestHash: {name: X-Request-Hash, in: header, required: false, schema: {type: string, pattern: '^[0-9a-fA-F]{64}$'}}
|
|
schemas:
|
|
ActionRequest:
|
|
type: object
|
|
required: [expectedVersion]
|
|
properties:
|
|
expectedVersion: {type: integer, minimum: 0}
|
|
reason: {type: string, maxLength: 500}
|
|
SaveRequest:
|
|
type: object
|
|
required: [oceanBookingId, plannedLoadingAt, expectedVersion]
|
|
properties:
|
|
oceanBookingId: {type: integer, format: int64, minimum: 1}
|
|
containerBookingId: {type: integer, format: int64, minimum: 1}
|
|
loadingPlanId: {type: integer, format: int64, minimum: 1}
|
|
plannedLoadingAt: {type: string, format: date-time}
|
|
expectedVersion: {type: integer, minimum: 0}
|