Bắt đầu sử dụng (10 phút)

1. Thiết lập cơ bản

Trước khi bắt đầu sử dụng chúng ta sẽ cần:

  • Tạo một tài khoản developer để nhận thông tin về ClientID và Secret. Xem hướng dẫn tại mục Authentication.

  • Lấy token để xác thực truy cập hệ thống Goship API.

  • Download SDK phù hợp với ngôn ngữ mà bạn quen sử dụng.

Setup một endpoint:

Production: https://api.goship.io/api/v2

Sandbox: http://sandbox.goship.io/api/v2

Chú ý:

  • Tất cả các url production của Goship đều sử dụng giao thức https nhằm đảm bảo tính bảo mật của thông tin gửi tới cho Goship.

  • Mặc định tất cả các tài khoản developer trên môi trường production đều ở trạng thái deactive, để active tài khoản các bạn cần liên hệ với Goship Team.

  • Các tài khoản trên sandbox thì mặc định là active, bạn có thể thoải mái sử dụng cho mục đích test trước khi tích hợp vào hệ thống.

2. Xác thực truy cập

Hầu hết các api của Goship được bảo vệ bởi hệ thống xác thực token. Chúng ta sẽ cần lấy token bằng cách thực hiện 1 POST request tới url như sau:

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

Header:

Accept: application/json
Content-Type: application/json

Request body:

{
        "username": "best_shop@gmail.com",
        "password": "bestshop",
        "client_id": 1,
        "client_secret": "gNBVFAvvU7lp9ARkqh7M0VOz..."
}

Response data:

{
        "code": 200,
        "status": "success",
        "token_type": "Bearer",
        "expires_in": 31536000,
        "access_token": "eyJ0eXAiOiJKV1QiLCJhbG.....",
        "refresh_token": "wFtUBGfUREYHeeH65ZhR....."
}

Mặc định, thời gian tồn tại của token là rất dài nên bạn có thể lưu vào đâu đó (local storage, file...) để tiện cho việc thực hiện các request tiếp theo.

3. Lấy thông tin phí

Để tạo được vận đơn, thông tin bắt buộc bạn cần có là bảng phí. Để lấy phí vận chuyển, chúng ta tạo một request như sau

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

Header:

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

Request body

{
    "shipment": {
        "address_from": {
            "district": "100900",
            "city": "100000"
        },
        "address_to": {
            "district": "100200",
            "city": "100000"
        },
        "parcel": {
            "cod": 500000,
            "weight": "220",
            "width": "15",
            "height": "15",
            "length": "15"
        }
    }
}

Response data

{
    "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
    }]
}

Sau khi lấy được thông tin về phí vận chuyển, bạn sẽ dùng dữ liệu trường id để request tạo vận đơn. id tương ứng là trường rate trong API tạo vận đơn bên dưới.

4. Tạo một vận đơn

Xem xét một cấu trúc body tạo vận đơn như sau:

{
    "shipment": {
        "rate": "OF8xXzc5NA==",
        "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": "0934577886",
            "street": "51 Lê Đại Hành",
            "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."
        }
    }
}

Toàn bộ thông tin query được bao bởi key shipment. Cấu trúc của query gồm 4 phần chính:

  • rate là thông tin về bảng giá. Thông tin về rate có thể lấy được từ api Lấy cước phí

  • address_from là thông tin người gửi. Thông tin về mã districtcity lấy được từ api Dữ liệu quận/huyệnDữ liệu tỉnh/thành phố

  • address_to là thông tin người nhận. Tương tự như address_from

  • parcel là thông tin về hàng hóa gửi. Giá trị của trường weight là gram. Giá trị của trường width, height, length là cm.

Như vậy, để tạo một vận đơn mới chúng ta cần thực hiện 1 POST request như sau:

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

Header

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

Response data:

{
    "code": 200,
    "status": "success"
}

Tạo vận đơn trên Goship là quá trình xử lý bất đồng bộ. Bạn sẽ luôn luôn nhận được một response như trên khi đẩy vận đơn qua Goship.

Sau 5 giây, Goship sẽ phát đi một notify qua webhook với event Vận đơn mới. Bạn cần listen event này thông qua hệ thống webhook để update thông tin vận đơn.

Đọc thêm Webhook và thông tin dữ liệu trả về.