Chuyển tới nội dung chính

Tạo hàng loạt đơn nhập - xuất từ vận hành

POST 
/v1/tms/order-requests

Nhận một hoặc nhiều đơn nhập - xuất từ vận hành. Mỗi phần tử trong mảng được xử lý riêng; kết quả có thể vừa thành công vừa lỗi.

Trước khi tạo đơn, API gom và upsert danh mục (khách hàng, tuyến, loại chi phí, …) trong batch. Cùng key/code chỉ tạo một bản ghi master rồi gắn chung cho các đơn.

Định danh: Unique theo (shown_code, type). Cùng shown_code khác type (Nhập/Xuất) được phép tạo hai đơn riêng. Response batch kèm type trên mỗi item.

Quy tắc theo loại dịch vụ (type):

booking_number và bill_number không bắt buộc. Schema chỉ cấm gửi sai loại.

LoạiBắt buộc trên details[]Không được gửi
EXPORT_CARGO (xuất khẩu)container_pickup_date, gross_weightbill_number; details[].container_delivery_date, details[].container_return_date, details[].storage_start_date
IMPORT_CARGO (nhập khẩu)container_number, seal_number, container_delivery_date, gross_weightbooking_number; details[].container_pickup_date

Ý nghĩa địa điểm trên tuyến (route):

  • pickup_place: Nơi lấy container — xuất khẩu là depot lấy cont rỗng; nhập khẩu là cảng nhập (ICD trên OR).
  • warehouse hoặc warehouses[] (XOR — không gửi cả hai): Kho hàng theo thứ tự trên tuyến — xuất khẩu là kho đóng hàng; nhập khẩu là kho trả hàng. Một kho → warehouse; nhiều kho → warehouses (ordered).
  • dropoff_place: Nơi hạ container — xuất khẩu là cảng hạ hàng; nhập khẩu là depot trả cont rỗng.

Tra cứu / tạo tuyến: khớp theo route.code (nếu có) + danh sách mã kho theo thứ tự + mã dropoff_place. Trùng thì tái sử dụng; không thì tạo mới (trùng mã tổ chức có thể thêm hậu tố -1, -2, …).

inventory_check nhận Có/Không; nếu gửi boolean thì được chuẩn hóa thành Có/Không. shipping_schedule.services vẫn được Create chấp nhận để tương thích, nhưng không thuộc contract GOM khuyến nghị.

Request​

Responses​

HTTP 200: tạo thành công toàn bộ hoặc một phần (body status 200), hoặc lỗi xác thực trong body (status 401). Khi partial success, body có thêm error: string[] (cùng nội dung tóm tắt với data.error_items).