VPCL Partner API · v1

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", … }

Khả năng

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/wards

Bá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 /quotes

Tạ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}/cancel

Hà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}/tracking

Webhook 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_changed
Bảo mật

Mỗ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.

sign.js · Node.jsHMAC-SHA256
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.

Quy trình tích hợp

Từ đăng ký đến vận hành

  1. 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. 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. 3

    Nghiệm thu

    VPCL đối chiếu dữ liệu đơn thử và trạng thái webhook hai phía.

  4. 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. 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.

Môi trường

Base URL

Môi trườngBase URLGhi chú
Sandboxhttps://api-dev.vpclogistics.vn/api/v1/partnerDữ liệu thử, không phát sinh vận chuyển thật
Productionhttps://api.vpclogistics.vn/api/v1/partnerCấ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.