Tích hợp Goship API trong 10 phút

Trong hướng dẫn này, chúng ta sẽ cùng tìm hiểu cách sử dụng Goship 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 Goship. Đơn hàng được gửi đi thành công sẽ được Đơn vị vận chuyển tiếp nhận và điều phối cho shipper tới lấy hàng.

Tóm tắt của hướng dẫn

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

Bạn nên tạo tài khoản Goship trước khi bắt đầu đọc tiếp.

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

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.goship.io/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
        },
        "address_to": {
            "city": "100000",
            "district": "100200",
        },
        "parcel": {
            "cod": "500000",
            "weight": "220",
            "width": "10",
            "height": "15",
            "length": "15"
        }
    }
}

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

{
    "code": 200,
    "status": "success",
    "data": [{
        "id": "Nl84XzkzOA==",
        "carrier_name": "Viettel Post",
        "carrier_logo": "https:\/\/api.goship.io\/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.goship.io\/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 của việc tích hợp Goship API. Do vậy tạm thời chúng ta sẽ không đi vào 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

Như đã đề cập ở phần trên, bạn không cần hiểu ngay các trường dữ liệu trong request body dưới đây. Hãy cứ copy và paste vào một API Client App như Postman hoặc Insomnia và thực hiện một request:

POST http://sandbox.goship.io/api/v2/shipments

{
    "shipment": {
        "rate": "MTFfN181OTg=",
        "address_from": {
            "name": "Nguyễn Văn A",
            "phone": "0912345678",
            "street": "102 Thái Thịnh",
            "ward": "113",
            "district": "100900",
            "city": "100000"
        },
        "address_to": {
            "name": "Lai Dao",
            "phone": "0909876543",
            "street": "51 Lê Đại Hành",
            "ward": "79",
            "district": "100200",
            "city": "100000"
        },
        "parcel": {
            "cod": "500000",
            "weight": "220",
            "width": "15",
            "height": "15",
            "length": "15",
            "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. Điều này có nghĩa là để tạo được đơn hàng, bắt buộc phải có biểu phí trước.

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": "15700",
  "tracking_number": null,
  "carrier": "Giao Hàng Nhanh",
  "carrier_short_name": "GHN",
  "created_at": "21\/08\/2020 13:34:49"
}

Chúc mừng bạn đã gửi đơn hàng đầu tiên thành công!

Goship 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. Vì vậy, đơ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 Goship Webhook.

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