Mục lục tài liệu

Tài liệu API

Đây là các nhóm endpoint dành cho đối tác tích hợp. Tài liệu được tạo từ một phiên bản cố định của bản đặc tả OpenAPI, không truy vấn trực tiếp hệ thống đang vận hành.

Phạm vi tài liệu này

Trang này chỉ công bố các nhóm endpoint dành cho đối tác. Các phần thuộc vận hành nội bộ của hệ thống TMS không nằm trong tài liệu công khai và sẽ không xuất hiện ở đây.

Xác thực

Cách xác thực phụ thuộc vào nhóm endpoint, không phụ thuộc vào khóa của bạn. Trang chi tiết của từng endpoint ghi rõ cách xác thực được chấp nhận, ở mục Xác thực yêu cầu.

Khóa API

Nhóm tối ưu tuyến đường xác thực bằng khóa API. Gửi khóa trong header api-key ở mọi request. Mọi endpoint tối ưu tuyến trong tài liệu này chỉ nhận khóa API, không nhận token.

api-key: YOUR_KEY

Token JWT

Các nhóm endpoint còn lại xác thực bằng token. Gửi token trong header Authorization theo dạng Bearer. Riêng nhóm lập kế hoạch chuyến chấp nhận cả hai cách.

Authorization: Bearer YOUR_TOKEN

Điều kiện để một khóa gọi được tối ưu tuyến

Khóa phải đáp ứng đủ cả ba điều kiện. Thiếu một điều kiện, request sẽ bị từ chối; thông báo trả về được liệt kê ở phần Mã lỗi bên dưới.

Khóa còn hiệu lực, chưa hết hạn.
Khóa được cấp Quyền dùng API tối ưu tuyến. Quyền này do đội Route4Green cấp cho từng khóa, bạn không tự bật được.
Tính năng đang được bật ở phía máy chủ. Đây là công tắc chung, không phải thiết lập riêng của từng tài khoản, nên một khóa đủ quyền vẫn có thể bị từ chối.

Không nhúng khóa vào mã chạy phía trình duyệt hay ứng dụng di động. Khóa chỉ dùng ở phía máy chủ của bạn.

Cách nhận khóa API

Bạn đăng ký khóa API ở trang dùng thử. Nếu bài toán phù hợp, chúng tôi liên hệ lại và cấp khóa thử nghiệm cho bạn.

Đăng ký khóa API

Muốn xem kết quả lập tuyến trước khi tích hợp, bạn có thể dùng bản demo tại sandbox.route4green.com.

Địa chỉ gốc

Chỉ có một địa chỉ máy chủ, được cấp khi bạn nhận khóa. Đường dẫn trong tài liệu này là phần nối sau địa chỉ đó.

Môi trường thử nghiệm và môi trường thật dùng chung địa chỉ đó, phân biệt bằng khóa bạn gửi kèm chứ không bằng đường dẫn khác. Đổi môi trường là đổi khóa, không phải đổi cấu hình địa chỉ.

Nhóm endpoint

8 nhóm

Tối ưu tuyến đường

Tạo job tối ưu, theo dõi trạng thái và lấy kết quả. Đây là nhóm trung tâm của Route4Green.

7 endpoint

Lập kế hoạch chuyến

Tạo và điều chỉnh kế hoạch chuyến theo ngày, gắn xe và tài xế vào chuyến.

6 endpoint

Đơn hàng

Nhập đơn hàng và điểm giao vào hệ thống làm đầu vào cho bài toán tối ưu.

7 endpoint

Hàng chờ ghép

Gom các yêu cầu vận chuyển vào hàng chờ (pool) để Route4Green quyết định ghép chúng thành chuyến.

5 endpoint

Phương tiện

Khai báo xe, tải trọng và thuộc tính vận hành của đội xe.

6 endpoint

Kế hoạch xe

Lịch khả dụng của từng xe, để kết quả tối ưu bám đúng đội xe thật.

7 endpoint

Webhook

Đăng ký nhận thông báo khi có sự kiện, thay vì hỏi liên tục.

5 endpoint

Khóa API

Tạo, xem và thu hồi khóa truy cập cho từng hệ thống tích hợp.

3 endpoint

Hướng dẫn và SDK

6 trang

Sáu trang hướng dẫn dưới đây dành cho đội tích hợp. Chưa có bộ SDK đóng gói sẵn, nên mỗi trang hướng dẫn cách gọi API bằng HTTP thuần, cách bạn dùng được ngay hôm nay.

Cài đặt

Chưa có gói để cài. Sinh client từ bản đặc tả tải về.

Bắt đầu nhanh

Gửi một job và lấy kết quả, từ đầu tới cuối.

Xử lý job bất đồng bộ

Sáu trạng thái, bốn trạng thái kết thúc, và khi nào nên dừng.

Kiểm tra chữ ký webhook

Xác minh chữ ký trước khi xử lý, tính trên phần thân thô.

Tích hợp từ một hệ thống TMS, ERP hoặc WMS

Ánh xạ dữ liệu từ hệ thống bạn đang dùng vào đúng một nội dung gửi job tối ưu tuyến.

Về bản đặc tả

Tài liệu này sinh từ một bản đặc tả OpenAPI được lưu lại, cập nhật lần gần nhất vào ngày dưới đây. Mỗi lần cập nhật đều được rà soát trước khi đăng.

Cập nhật2026-08-20

Tải bản đặc tả dành cho đối tác

Bản JSON dưới đây chứa đúng những endpoint xuất hiện trong tài liệu này, kèm các cấu trúc dữ liệu mà chúng tham chiếu tới. Phần vận hành nội bộ đã được lọc bỏ chứ không chỉ ẩn đi, nên bạn có thể đưa thẳng vào công cụ sinh mã.

Tải file JSON

46 endpoint trong file