1. Giới thiệu chung
Nhằm hỗ trợ các đối tác tối ưu quy trình quản lý đơn hàng Nhật – Việt, S1 Cargo cung cấp hệ thống API RESTful và Webhook mạnh mẽ. Hệ thống này cho phép:
-
Tạo đơn hàng tự động: Đồng bộ mã vận đơn từ website đối tác sang S1 Cargo ngay lập tức.
-
Cập nhật dữ liệu thời gian thực: Tự động nhận thông tin cân nặng và trạng thái đơn hàng mà không cần thao tác thủ công.
2. Thông tin kết nối
Đối tác cần liên hệ Quản trị viên S1 Cargo để nhận API Key riêng biệt trước khi bắt đầu tích hợp.
-
Base URL:
https://s1cargo.com/api/v1 -
Header xác thực:
X-S1-API-KEY: [Mã-Key-Của-Bạn] -
Định dạng dữ liệu:
Application/json
3. Chiều nhận dữ liệu (Inbound API)
Sử dụng Endpoint này khi khách hàng của bạn tạo đơn trên website của bạn và bạn muốn đẩy thông tin đó sang hệ thống S1 Cargo.
-
Endpoint:
/create-order -
Phương thức:
POST -
Cấu trúc dữ liệu mẫu:
JSON
{
"tracking_number": "75012345678"
}
Mã mẫu tích hợp bằng C# (.NET):
C#
public async Task PushOrderToS1(string trackingNo) {
using (var client = new HttpClient()) {
client.DefaultRequestHeaders.Add("X-S1-API-KEY", "YOUR_API_KEY");
var content = new StringContent(JsonSerializer.Serialize(new {
tracking_number = trackingNo
}), Encoding.UTF8, "application/json");
var response = await client.PostAsync("https://s1cargo.com/api/v1/create-order", content);
// Xử lý kết quả trả về...
}
}
4. Chiều gửi dữ liệu (Webhook Outbound)
Khi S1 Cargo cập nhật trạng thái hoặc cân nặng, hệ thống sẽ tự động gọi (POST) đến URL Webhook mà bạn cung cấp.
-
Sự kiện:
shipment_updated -
Dữ liệu phản hồi mẫu:
JSON
{
"tracking_number": "75012345678",
"status": "Arrived at Warehouse",
"weight": "5.5",
"event": "shipment_updated",
"server_time": "2026-02-03 11:30:00"
}
Mã xử lý đầu nhận (Webhook Controller) bằng C#:
C#
[HttpPost("s1-webhook")]
public IActionResult HandleS1Update([FromBody] S1Data data) {
// Logic cập nhật database của bạn tại đây
// Cập nhật Cân nặng: data.weight
// Cập nhật Trạng thái: data.status
return Ok();
}
5. Danh mục Trạng thái Đơn hàng
Để đồng bộ hóa hiển thị, đối tác nên ánh xạ (map) các trạng thái sau từ S1 Cargo:
| Mã trạng thái | Ý nghĩa |
| Shop Giao Hàng | Đơn hàng đã ghi nhận trên hệ thống S1 |
| Kho Nhận | Đã nhận hàng tại kho Nhật Bản |
| Đang về VN | Hàng đang trên đường vận chuyển về VN |
| Chờ giao | Hàng đã về kho Việt Nam (Chờ giao) |
| Hoàn Thành | Đã hoàn thành giao hàng |
6. Hỗ trợ kỹ thuật
Trong quá trình tích hợp, nếu gặp bất kỳ lỗi kết nối hoặc cần nâng cấp thêm các trường dữ liệu tùy chỉnh (ví dụ: phí dịch vụ, loại hàng hóa…), quý đối tác vui lòng liên hệ
