Tổng quan

Học cách sử dụng Zogo API trong 10 phút để gửi một đơn hàng đi

Trong hướng dẫn này, chúng ta sẽ cùng tìm hiểu cách sử dụng Zogo API để tích hợp vận chuyển nhanh nhất.

Kết thúc hướng dẫn này, bạn sẽ gửi được đơn hàng tới hệ thống Zogo. Đơn hàng được gửi đi thành công sẽ được các đơn vị giao hàng tiếp nhận và điều phối cho shipper tới lấy hàng.

Các bước thao tác

  1. Tạo tài khoản Zogo
  2. Tạo tài khoản developer (ClientID và Secret)
  3. Xác thực tài khoản để lấy token truy cập hệ thống Zogo API
  4. Lấy thông tin biểu phí
  5. Tạo vận đơn đầu tiên

Bạn cần tạo tài khoản Zogo trước khi bắt đầu

Hướng dẫn tạo tài khoản xem tại Thiết lập cơ bản và Authentication.

1. Lấy thông tin biểu phí

Biểu phí là danh sách các dịch vụ của tất cả các đơn vị vận chuyển (ĐVVC) đang cung cấp cho 1 tuyến giao hàng. Thông tin biểu phí bao gồm:

  • ID biểu phí
  • Thông tin đơn vị vận chuyển
  • Dịch vụ vận chuyển
  • Các loại phí: Phí giao hàng, phí thu hộ, bảo hiểm...
  • Thời gian dự kiến giao

Dựa vào các thông tin này, bạn có thể cung cấp cho người dùng một giao diện để so sánh phí và lựa chọn ĐVVC một cách trực quan.

Để thực hiện chức năng lấy thông tin biểu phí, chúng ta tạo một request với thông tin như sau:

POST http://sandbox.zogo.vn/api/v2/rates

Hãy chắc chắn bạn đã cài đặt thành công token authentication trên header của request như đoạn code bên dưới:

Accept: application/json
Content-Type: application/json
Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbG...

Request body bao gồm các thông tin sau:

{
    "shipment": {
        "address_from": {
            "city": "100000", // Lấy từ API: /cities
            "district": "100900", // Lấy từ API: /districs
            "ward": "113" // Lấy từ API: /wards
        },
        "address_to": {
            "city": "100000",
            "district": "100200",
            "ward": "79"
        },
        "parcel": {
            "cod": "500000", // Tiền thu hộ
            "amout": "500000", // Giá trị khai giá
            "weight": "220",
            "width": "1",
            "height": "1",
            "length": "1"
        }
    }
}

Nếu request gửi đi thành công, bạn sẽ nhận được một response data như sau:

{
    "code": 200,
    "status": "success",
    "data": [{
        "id": "Nl84XzkzOA==",
        "carrier_name": "Viettel Post",
        "carrier_logo": "https:\/\/api.zogo.vn\/storage\/images\/carriers\/vtpost_c.png",
        "service": "Tiết kiệm",
        "expected": "Dự kiến giao trong 5 ngày",
        "cod_fee": "22000",
        "total_fee": "17000",
        "total_amount": "39000"
    },
    {
        "id": "MTFfN181OTg=",
        "carrier_name": "Giao Hàng Tiết Kiệm",
        "carrier_logo": "https:\/\/api.zogo.vn\/storage\/images\/carriers\/ghtk_c.png",
        "service": "Nhanh",
        "expected": "Dự kiến giao trong 2 ngày",
        "cod_fee": "0",
        "total_fee": "18000",
        "total_amount": "39000"
    }]
}

Mục tiêu của hướng dẫn này là giúp bạn nhanh chóng hiểu được luồng làm việc khi tích hợp Zogo API. Do vậy chúng ta tạm thời bỏ qua việc tìm hiểu ý nghĩa các trường dữ liệu.

Với response data ở trên, chúng ta chỉ cần quan tâm tới thông tin về id của từng biểu phí. Khi người dùng chọn một biểu phí để bắt đầu gửi đơn, trường id sẽ lưu lựa chọn biểu phí của người dùng. Đó cũng chính là tham số yêu cầu bắt buộc để có thể gửi vận đơn thành công.

Tạo và gửi một vận đơn

Thực hiện một request với thông tin body data như sau:

POST http://sandbox.zogo.vn/api/v2/shipments

{
    "shipment": {
        "rate": "MTFfN181OTg=",
        "payer": 0, // Người trả phí, 1: Người gửi, 0: Người nhận
        "address_from": {
            "name": "Nguyễn Văn A",
            "phone": "0912345678",
            "street": "102 Thái Thịnh",
            "city": "100000",
            "district": "100900",
            "ward": "113"
        },
        "address_to": {
            "name": "Lai Dao",
            "phone": "0909876543",
            "street": "51 Lê Đại Hành",
            "city": "100000",
            "district": "100200",
            "ward": "79"
        },
        "parcel": {
            "cod": "500000",
            "amount": "500000",
            "weight": "220",
            "width": "1",
            "height": "1",
            "length": "1",
            "metadata": "Hàng dễ vỡ, vui lòng nhẹ tay."
        }
    }
}

Bạn có thể thấy, key rate ở request body trên nhận giá trị của id biểu phí ở bước trước. Rate ID là tham số required để tạo đơn hàng.

Tham khảo API Lấy biểu phí

Response data nhận lại sẽ có dạng:

{
  "code": 200,
  "status": "success",
  "id": "GSOX6OQQLQ",
  "cod": "500000",
  "fee": "22000",
  "tracking_number": "G8SKL8SS",
  "carrier": "Giao Hàng Nhanh",
  "carrier_short_name": "GHN",
  "created_at": "21\/08\/2024 13:34:49"
}

Như vậy là bạn đã gửi được đơn hàng đầu tiên thành công, xin chúc mừng!

Lưu ý

Zogo API sử dụng hệ thống Webhook để cập nhật thông tin đơn hàng cho các đối tác tích hợp API. Các đơn hàng sau khi được gửi đi sẽ bắt đầu nhận thông tin cập nhật qua hệ thống Zogo Webhook.

Môi trường sandbox không thể thực hiện webhook, bạn chỉ có thể tự giả lập webhook với body data như trong hướng dẫn về Webhook.

Xem hướng dẫn về Zogo Webhooks.

Thiết lập cơ bản
Hướng dẫn thiết lập cơ bản để bắt đầu tích hợp hệ thống API vận chuyển Zogo API