Kết nối hệ thống của bạn với VPCL Logistics
Báo giá, tạo đơn, theo dõi hành trình và nhận webhook trạng thái trực tiếp từ hệ thống của bạn — REST/JSON, ký HMAC-SHA256, có sandbox để tích hợp trước khi chạy thật.
# Kiểm tra khoá và chữ ký
GET /api/v1/partner/ping
X-VPCL-Key: <key_id>
X-VPCL-Timestamp: <unix_time>
X-VPCL-Signature: <hmac_sha256_hex>
200 { "environment": "sandbox", … }
Trọn vòng đời một đơn hàng qua API
Danh mục địa chỉ 2 cấp
Tỉnh/thành → phường/xã theo mô hình địa chỉ sau sáp nhập 2025. Lấy mã chuẩn trước khi báo giá, tạo đơn.
GET /locations/provinces · /locations/wardsBáo giá
Tính phí vận chuyển trước khi tạo đơn. Giá tham khảo đến hạn hiệu lực, chốt tại thời điểm tạo đơn.
POST /quotesTạo & huỷ đơn
Idempotent theo order_code: gửi lại cùng mã nhận về đúng đơn đã tạo, an toàn để thử lại khi mất kết nối.
POST /orders · POST /orders/{order_code}/cancelHành trình & bằng chứng giao hàng
Lịch sử trạng thái và sự kiện hiện trường: quét mã, giao nhận, bằng chứng giao hàng (POD).
GET /orders/{order_code}/trackingWebhook trạng thái
VPCL chủ động gửi sự kiện order.status_changed mỗi khi đơn đổi trạng thái, có gửi lại khi phía nhận lỗi.
order.status_changedMỗi request đều được ký và kiểm tra
Ký request HMAC-SHA256
Mỗi request kèm X-VPCL-Key, X-VPCL-Timestamp và X-VPCL-Signature tính trên phương thức, đường dẫn và mã băm body.
Cửa sổ thời gian 300 giây
Timestamp lệch quá 300 giây so với giờ máy chủ bị từ chối — chặn phát lại request cũ.
Webhook có chữ ký
Mọi webhook được ký bằng webhook_secret riêng. Phía đối tác xác minh chữ ký và khử trùng theo event_id.
Khoá riêng từng môi trường
Sandbox và production dùng bộ khoá tách biệt. Khoá production chỉ cấp sau khi nghiệm thu sandbox.
import crypto from 'node:crypto';
function sign({ secret, method, path, body = '' }) {
const ts = Math.floor(Date.now() / 1000).toString();
const bodyHash = crypto.createHash('sha256').update(body).digest('hex');
const toSign = [ts, method.toUpperCase(), path, bodyHash].join('\n');
const signature = crypto.createHmac('sha256', secret).update(toSign).digest('hex');
return { 'X-VPCL-Timestamp': ts, 'X-VPCL-Signature': signature };
}Ký trên đúng chuỗi byte gửi đi: serialize JSON một lần, dùng chuỗi đó vừa để băm vừa làm body. Ví dụ Python và chi tiết string_to_sign có trong tài liệu API.
Từ đăng ký đến vận hành
- 1
Đăng ký
Gửi thông tin đơn vị, đầu mối kỹ thuật và webhook_url sandbox. VPCL cấp khoá sandbox — được tích hợp song song khi hợp đồng đang ký.
- 2
Tích hợp sandbox
Gọi GET /ping để kiểm tra chữ ký, POST /webhooks/test để kiểm tra phía nhận webhook, rồi chạy luồng báo giá → tạo đơn → tra cứu → huỷ.
- 3
Nghiệm thu
VPCL đối chiếu dữ liệu đơn thử và trạng thái webhook hai phía.
- 4
Production
VPCL cấp khoá production, chạy thử vài đơn thật có giám sát rồi mở hoàn toàn.
- 5
Vận hành
Đối soát cước định kỳ theo hợp đồng; mọi thay đổi API ghi ở Lịch sử thay đổi của tài liệu.
Base URL
| Môi trường | Base URL | Ghi chú |
|---|---|---|
| Sandbox | https://api-dev.vpclogistics.vn/api/v1/partner | Dữ liệu thử, không phát sinh vận chuyển thật |
| Production | https://api.vpclogistics.vn/api/v1/partner | Cấp sau khi nghiệm thu sandbox |
Mỗi môi trường có bộ khoá riêng (key_id, api_secret, webhook_secret).
Đặc tả OpenAPI 3.1
Nhập vào Postman, Insomnia hoặc trình sinh mã client để bắt đầu nhanh.