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

Giới thiệu

Tài liệu này hướng dẫn khách hàng tích hợp API với Hệ thống quản lý vận tải (TMS) — nhận thông tin đơn nhập - xuất từ bộ phận vận hành và tra cứu các danh mục master.

Base URL​

Mọi request gửi tới:

http://api-gateway.autotms.vn

Ví dụ endpoint nhận đơn nhập - xuất:

POST http://api-gateway.autotms.vn/v1/tms/order-requests

Quy ước dữ liệu​

  • Định dạng: JSON, tên trường dùng snake_case.
  • Batch: Một request có thể gửi từ 1 đến 200 đơn trong một mảng JSON.
  • Xử lý từng phần tử: Mỗi đơn trong mảng được xử lý độc lập; kết quả trả về có thể vừa có đơn thành công vừa có đơn lỗi.
  • Tổ chức: Tổ chức vận hành được xác định từ token đăng nhập — không cần gửi org_id trong body.
  • Định danh đơn: dùng cặp (shown_code, type) với type = IMPORT_CARGO | EXPORT_CARGO.

Danh mục tự động​

Nếu mã khách hàng, mã địa điểm, loại container, loại hàng, loại chi phí, vật tư đóng gói... chưa có trong hệ thống, API sẽ tự tạo danh mục tương ứng rồi gắn vào đơn. Tra cứu theo code, name hoặc key tùy từng loại danh mục.

Tài khoản người dùng​

Trường username phải đã tồn tại trong hệ thống — API không tự tạo tài khoản. Nếu tài khoản không tồn tại, request sẽ báo lỗi.

participants khi tạo đơn là tùy chọn (có thể bỏ qua hoặc gửi mảng rỗng). Nếu gửi participants[].username, các username đó cũng phải đã tồn tại trong hệ thống.

contacts là tùy chọn trên tạo / cập nhật / truy vấn đơn. Khi tạo hoặc cập nhật danh sách, mỗi phần tử bắt buộc full_name; phone_number và email tùy chọn. Cập nhật thay thế toàn bộ danh sách ([] để xóa).

Cấu trúc tài liệu​

Trong mục Hệ thống quản lý vận tải:

  1. Xác thực — header và cookie bắt buộc.
  2. Truy vấn đơn hàng — GET /v1/tms/order-requests/{shownCode}.
  3. Truy vấn hàng loạt đơn hàng — POST /v1/tms/order-requests/batch-query.
  4. Tạo hàng loạt đơn hàng — POST /v1/tms/order-requests.
  5. Cập nhật đơn hàng — PUT /v1/tms/order-requests/{shownCode}.
  6. Cập nhật hàng loạt đơn hàng — PUT /v1/tms/order-requests.
  7. Hủy hàng loạt đơn hàng — POST /v1/tms/order-requests/cancel.
  8. Hủy thay đổi đơn hàng — POST /v1/tms/order-requests/pending-update-cancel.
  9. Phản hồi duyệt đề xuất thay đổi — POST /v1/tms/order-requests/pending-update-callback.
  10. Webhook thông báo cập nhật danh mục master — POST /v1/webhooks/gom/master-changed (draft, chưa implement).
  11. Danh mục Khách hàng — GET /v1/tms/customers.
  12. Danh mục Xe — GET /v1/tms/vehicles.
  13. Truy vấn kho — GET /v1/tms/warehouses.
  14. Truy vấn một kho — GET /v1/tms/warehouses/{code}.
  15. Đồng bộ đặc tính kho — POST /v1/tms/route-point-attributes/sync.
  16. Xóa đặc tính kho — POST /v1/tms/route-point-attributes/delete.
  17. Danh mục Tài xế — GET /v1/tms/drivers.
  18. Danh mục Lý do hủy — GET /v1/tms/reason-catalogs.
  19. Danh mục Nhà thầu phụ — GET /v1/tms/subcontractors.
  20. Danh mục Rơ-moóc — GET /v1/tms/trailers.
  21. Danh mục Tuyến đường — GET /v1/tms/routes.
  22. Danh mục Điều phối viên — GET /v1/tms/dispatchers. Mục Hệ thống quản lý đơn hàng dành cho API OMS — sẽ bổ sung sau.