Rate

Cách lấy biểu phí vận chuyển hoả tốc qua Goship API

Rate API dùng để lấy biểu phí vận chuyển đơn hoả tốc của tất cả các đơn vị vận chuyển có cung ứng dịch vụ trên tuyến lấy/giao hàng.

Bắt đầu lấy bảng phí vận chuyển:

POST https://sandbox.goship.io/api/v2/ondemand-shipments/rates

Request body:

{
  "paths": [
    {
      "lat": 20.9842552,
      "lng": 105.8609381,
      "kind": 1
    },
    {
      "lat": 20.9895958,
      "lng": 105.8445432,
      "kind": 2,
      "parcel": {
        "name": "Tủ gỗ",
        "quantity": 20,
        "weight": 200,
        "height": 20
      }
    }
  ]
}

Field	Type	Description	Required
paths	Array of object	Danh sách các điểm lấy/giao hàng. Mỗi điểm có thể chứa thông tin về địa chỉ, loại hàng hoá và thông tin khác.	Có
paths[].lat	float	Vĩ độ của địa chỉ.	Có
paths[].lng	float	Kinh độ của địa chỉ.	Có
paths[].kind	number	Loại địa chỉ. Có thể là `1` (địa chỉ lấy hàng) hoặc `2` (địa chỉ giao hàng).	Có
paths[].parcel	object	Thông tin chi tiết về kiện hàng.
paths[].parcel.name	string	Tên kiện hàng.
paths[].parcel.quantity	number	Số lượng kiện hàng.
paths[].parcel.weight	number	Cân nặng kiện hàng. `(gram)`
paths[].parcel.width	number	Chiều rộng kiện hàng. `(cm)`
paths[].parcel.height	number	Chiều cao kiện hàng. `(cm)`
paths[].parcel.length	number	Chiều dài kiện hàng. `(cm)`
services	Array of object	Các dịch vụ cần bổ sung đi kèm trong các trường hợp (hàng cồng kềnh, quay lại điểm giao...)
services[]._id	string	Mã dịch vụ.
services[].requests	Array of object	Các yêu cầu đi kèm
services[].requests[]._id	string	Mã yêu cầu.
services[].requests[].num	number	Số lượng của yêu cầu đi kèm.
services[].requests[].tier_code	string	Mã của dịch vụ đi kèm (đối với dịch vụ hàng cồng kềnh).

Làm thế nào để lấy services? Hãy xem danh sách các dịch vụ kèm các yêu cầu bổ sung tại Response data, và xem ví dụ.

Response data:

{
  "code": 200,
  "status": "success",
  "data": [
    {
      "_id": "HAN-BIKE",
      "description_vi_vn": "Lấy hàng ngay, giao hỏa tốc",
      "icon_url": "https://vncdn.ahamove.com/ahamoveimg/aha-service/icon-bike.png",
      "max_cod": 10000000,
      "max_cod_per_stop_point": 10000000,
      "max_stop_points": 10,
      "requests": [
        {
            "_id": "HAN-BIKE-ROUND-TRIP",
            "description_vi_vn": "Tài xế sẽ quay lại điểm lấy hàng với số phí bằng 80% phí khoảng cách. Lưu ý: Phí khoảng cách là số phí dựa theo số km vận chuyển, ko bao gồm phí điểm dừng và các loại phí khác.",
            "icon_url": "https://s3-ap-southeast-1.amazonaws.com/ahamoveimg/core_services/ic_round_trip.png",
            "name": "Quay lại điểm lấy hàng",
            "original_price": 0,
            "price": 24000,
            "type": "BOOLEAN"
        },
        {
          "_id": "HAN-BIKE-BULKY",
          "description_vi_vn": "Giao hàng cồng kềnh",
          "icon_url": "https://ahamoveimg.s3-ap-southeast-1.amazonaws.com/Special+Request/Special+Request+Icon/Bulky_packages.jpg",
          "name": "Giao hàng cồng kềnh",
          "original_price": 0,
          "price": 0,
          "tier_list": [
            {
              "code": "TIER_1",
              "description_vi_vn": "50x40x50:30kg",
              "img_url": "https://ahamoveimg.s3-ap-southeast-1.amazonaws.com/Special+Request/Bulky+Packages/Standard.png",
              "name_vi_vn": "Tiêu chuẩn",
              "price": 0,
              "price_description_vi_vn": "Miễn phí",
              "selectable": false
            },
            ...
            {
              "code": "TIER_4",
              "description_vi_vn": "90x70x90:80kg",
              "img_url": "https://ahamoveimg.s3-ap-southeast-1.amazonaws.com/Special+Request/Bulky+Packages/Tier+3.png",
              "name_vi_vn": "Mức 3",
              "price": 40000,
              "price_description_vi_vn": "",
              "selectable": true
            }
          ],
          "type": "TIER"
        }
        ...
      ],
      ...
      "delivery_fee": 30000,
      "carrier": 1,
      "carrier_name": "Ahamove",
      "carrier_logo": "https://sandbox.goship.io/static/ahamove.svg",
      "polylines": "qna_Cs}beSH??jA?V?pB?v@qA?G@?xC?nA@vAi@?I?eA@mBJg@`EMr@AJWxAIl@m@rDEVMz@CNKv@QdBMxAEd@a@dFE`@WbBK~AAFIdA?FAP?@?^AXAX?lBEVATG`AGhAK|AIjAATGlA_@EaAIuBQATGz@SrBAHCHCDGFGBOFm@\\{@b@jArCo@Za@PEB",
      "requested": [
        {
          "_id": "HAN-BIKE-BULKY",
          "price": 40000,
          "tier_code": "TIER_4"
        }
      ],
      "service_fee": 2500,
      "total_fee": 32500
    },
    ...
    {
      "_id": "GrabExpress",
      "currency": "VND",
      "distance": 1802,
      "delivery_fee": 2000,
      "service_fee_percent": 5,
      "carrier": 2,
      "carrier_name": "Grab",
      "carrier_logo": "https://sandbox.goship.io/static/grab.png",
      "estimated_time": {
          "pickup": "2025-04-16 22:02:11",
          "dropoff": "2025-04-16 22:32:11",
          "completed": "2025-04-16 22:32:11"
      },
      "polylines": null,
      "polyline_points": null,
      "service_fee": 1100,
      "total_fee": 3100
    }
  ]
}

Trong đó:

Field	Type	Description
_id	string	Mã dịch vụ
distance	number	Khoảng cách giữa 2 địa chỉ (m)
delivery_fee	number	Phí giao hàng (đ)
service_fee_percent	number	Phí nền tảng theo phần trăm
service_fee	number	Phí nền tảng (đ)
total_fee_carrier	number	Tổng phí giao hàng của hãng vận chuyển (đ)
total_fee	number	Tổng phí (đ)
carrier	number	Mã đơn vị vận chuyển
carrier_name	string	Tên đơn vị vận chuyển
carrier_logo	string	Logo đơn vị vận chuyển
estimated_time	object	Thời gian ước tính
estimated_time.pickup	string	Thời gian ước tính lấy hàng
estimated_time.dropoff	string	Thời gian ước tính giao hàng
estimated_time.completed	string	Thời gian ước tính hoàn thành
requests	array	Danh sách các yêu cầu đặc biệt (Đối với hãng vận chuyển AhaMove sẽ cần thêm các yêu cầu này)
requests[]._id	string	Mã yêu cầu
requests[].price	number	Phí yêu cầu (đ)
requests[].name	string	Tên yêu cầu
requests[].type	string	Loại yêu cầu (Quan trọng)
requested	array	Danh sách các yêu cầu mà bạn đã được chọn
requested[]._id	string	Mã yêu cầu đã được chọn
requested[].tier_code	string	Mã yêu cầu bổ sung đã được chọn
requested[].price	number	Phí yêu cầu (đ)

... và nhiều trường khác nữa, nhưng chúng ta quan tâm chủ yếu đến các trường trên.

Đối với hãng vận chuyển AhaMove, bạn sẽ cần bổ sung thêm các yêu cầu đi kèm như Giao hàng cồng kềnh hoặc Quay lại điểm lấy hàng để có thể lấy được bảng phí vận chuyển chính xác nhất.

Phân loại các yêu cầu đặc biệt:

Các yêu cầu đặc biệt đi kèm sẽ có các loại như sau:

Type	Group	Description
TIER	BULKY	Giao hàng cồng kềnh (Chi tiết)
PER_UNIT	TIP	Các yêu cầu đi kèm với số lượng (Chi tiết)
COD_INSURANCE	INSURANCE	Bảo hiểm hàng hoá (Chi tiết)
BOOLEAN	D2D, FRAGILE, SMS, TRIP	Các yêu cầu khác (Chi tiết)

Và các yêu cầu khác, bạn tham khảo thêm trên tài liệu của AhaMove

Params mẫu khi lấy biểu phí vận chuyển với các yêu cầu đặc biệt

`TIER`

Để dùng loại này, bạn cần xem danh sách tiêu chuẩn hàng hóa của các mức độ cồng kềnh tier_list trong yêu cầu đặc biệt

Bảng quy đổi kích thước và mức cồng kềnh (Tham khảo tại AhaMove)

Type	Kích thước	Cân nặng	Mức phí
TIER_2	60x50x60 (cm)	40kg	10.000 VND
TIER_3	70x60x70 (cm)	60kg	20.000 VND
TIER_4	90x70x90 (cm)	80kg	40.000 VND

{
  "paths": [
    {
      "lat": 20.9842552,
      "lng": 105.8609381,
      "kind": 1
    },
    {
      "lat": 20.9895958,
      "lng": 105.8445432,
      "kind": 2,
      "parcel": {
        "name": "Tủ gỗ",
        "quantity": 20,
        "weight": 200,
        "height": 20
      }
    }
  ],
  "services": [
    {
      "_id": "HAN-BIKE",
      "requests": [
        {
          "_id": "HAN-BIKE-BUKLY",
          "tier_code": "TIER_2" // =========> Mức cồng kềnh
        }
      ]
    }
  ]
}

`BOOLEAN`

Loại này chỉ cần có truờng thông tin _id ở mỗi yêu cầu khi tạo đơn

{
  "paths": [
    {
      "lat": 20.9842552,
      "lng": 105.8609381,
      "kind": 1
    },
    {
      "lat": 20.9895958,
      "lng": 105.8445432,
      "kind": 2,
      "parcel": {
        "name": "Tủ gỗ",
        "quantity": 20,
        "weight": 200,
        "height": 20
      }
    }
  ],
  "services": [
    {
      "_id": "HAN-BIKE",
      "requests": [
        {
          "_id": "HAN-BIKE-ROUND-TRIP" // =========> Quay lại điểm lấy hàng
        },
        {
          "_id": "HAN-BIKE-FRAGILE" // =========> Hàng dễ vỡ
        }
      ]
    }
  ]
}

`PER_UNIT`

Với loại yêu cầu này, cần phải thêm truờng thông tin num vào mỗi requests khi truyền để cụ thể số lượng các yêu cầu được thêm vào

{
  "paths": [
    {
      "lat": 20.9842552,
      "lng": 105.8609381,
      "kind": 1
    },
    {
      "lat": 20.9895958,
      "lng": 105.8445432,
      "kind": 2,
      "parcel": {
        "name": "Tủ gỗ",
        "quantity": 20,
        "weight": 200,
        "height": 20
      }
    }
  ],
  "services": [
    {
      "_id": "HAN-BIKE",
      "requests": [
        {
          "_id": "HAN-BIKE-TIP", // =========> Tiền tip
          "num": 2 // =========> Số lần tip
        }
      ]
    }
  ]
}

`COD_INSURANCE`

Loại này chỉ cần có truờng thông tin _id ở mỗi yêu cầu khi tạo đơn và cần cung cấp thông tin giá trị cod hoặc giá trị hàng hoá khi tạo đơn. Tại đây

Error

{
  "code": 422,
  "status": "error",
  "data": {
    "paths.0.lat": ["Vĩ độ không hợp lệ"],
    "paths.0.lng": ["Kinh độ không hợp lệ"],
    "paths.0.kind": ["Vui lòng chọn loại địa điểm (điểm nhận hoặc điểm giao)"],
    "paths": [
      "Vui lòng chọn ít nhất 2 địa chỉ",
      "Phải có ít nhất một điểm lấy hàng (kind = 1).",
      "Phải có ít nhất một điểm giao hàng (kind = 2)."
    ]
  },
  "message": "Unprocessable Entity"
}

Bạn cần điền đầy đủ thông tin để lấy được bảng phí vận chuyển.

Shipment status

Danh sách trạng thái và mã code tương ứng của response data từ hệ thống Goship API

Shipment

Các thao tác với đơn hàng thông qua Goship API