Shipment API

API shipment được dùng để tạo vận đơn mới, lấy thông tin các vận đơn đã tạo của bạn, tìm kiếm vận đơn... Sử dụng API này để liệt kê 1 danh sách các vận đơn và thông tin chi tiết của chúng.

Danh sách vận đơn

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

Response data:

{
  "code": 200,
  "status": "success",
  "data": [
    {
      "id": "GSR64NAQ82",
      "order_id": null,
      "carrier_name": "Giao hàng nhanh",
      "carrier_code": "HSY87F",
      "service_name": "Nhanh",
      "expected": "Dự kiến giao hàng trong 24 Giờ",
      "insurrance_fee": 0,
      "return_fee": 0,
      "re_delivery_fee": 0,
      "update_info_fee": 0,
      "overweight_fee": 0,
      "discount": 0,
      "service_fee": 0,
      "amount_return_shop": 0,
      "cod_fee": 0,
      "delivery_fee": 1488000,
      "total_fee": 1488000,
      "status_code": 900,
      "status_text": "Đơn mới",
      "status_desc": "Goship đã tiếp nhận đơn",
      "payer": 0,
      "payer_txt": "Khách trả",
      "tracking_url": null,
      "note_update": null,
      "created_at": "27/03/2017 16:59",
      "updated_at": "27/03/2017 16:59",
      "address_from": {
        "name": "Nguyễn Văn A",
        "phone": "0987121212",
        "email": "[email protected]",
        "street": "101 Hoàn Kiếm",
        "ward": "Thị Trấn Thường Tín",
        "ward_code": "582",
        "district": "Huyện Thường Tín",
        "district_code": 102700,
        "city": "Hà Nội",
        "city_code": 100000
      },
      "address_to": {
        "name": "Trần Văn B",
        "phone": "0987131313",
        "email": "[email protected]",
        "street": "102 Bà Triệu",
        "district": "Huyện Chương Mỹ",
        "district_code": 102100,
        "city": "Hà Nội",
        "city_code": 100000
      },
      "parcel": {
        "name": null,
        "quantity": 1,
        "width": 100,
        "height": 100,
        "length": 100,
        "weight": 166666.66666667,
        "cweight": 166666.66666667,
        "metadata": null
      },
      "history": [
        {
          "status": 900,
          "status_text": "Đơn mới",
          "status_desc": "Goship đã tiếp nhận đơn",
          "updated_at": "27/03/2017 16:59",
          "updated_time": 1490614528
        }
      ]
    }
  ]
}

Trong đó:

  • shipment: Thông tin chi tiết của vận đơn
  • shipment.id: Mã vận đơn Goship
  • shipment.order_id: Mã vận đơn của đối tác
  • shipment.carrier_name: Tên hãng vận chuyển nhận đơn
  • shipment.carrier_code: Mã vận đơn của hãng vận chuyển
  • shipment.service_name: Dịch vụ chuyển phát
  • shipment.cod_fee: Phí thu hộ tiền COD
  • shipment.insurrance_fee: Phí bảo hiểm
  • shipment.return_fee: Phí chuyển hoàn
  • shipment.re_delivery_fee: Phí giao lại
  • shipment.update_info_fee: Phí khác (chi tiết tại node_update)
  • shipment.overweight_fee: Phí vượt cân
  • shipment.discount: Giảm gá
  • shipment.service_fee: Phí dịch vụ (nền tảng)
  • shipment.delivery_fee: Phí vận chuyển
  • shipment.total_fee: Tổng phí vận chuyển
  • shipment.amount_return_shop: Tiền shop (người gửi hàng) nhận được khi đối soát (nêu âm Goship sẽ truy thu)
  • shipment.status_code: Mã trạng thái vận đơn
  • shipment.status_text: Trạng thái vận đơn
  • shipment.payer: Người trả phí
  • shipment.tracking_url: Link tra hành trình đơn từ HVC
  • shipment.note_update: Lịch sử cập nhật đơn hàng
  • shipment.status_desc: Mô tả trạng thái vận đơn
  • shipment.created_at: Thời gian tạo vận đơn
  • shipment.updated_at: Thời gian cập nhật vận đơn
  • shipment.address_from: Địa chỉ gửi
  • shipment.address_from.name: Tên người gửi
  • shipment.address_from.phone: Số điện thoại người gửi
  • shipment.address_from.email: Email người gửi
  • shipment.address_from.street: Địa chỉ người gửi
  • shipment.address_from.ward: Phường/xã gửi
  • shipment.address_from.ward_code: Mã phường/xã gửi
  • shipment.address_from.district: Quận/huyện gửi
  • shipment.address_from.district_code: Mã quận/huyện gửi
  • shipment.address_from.city: Tỉnh/thành phố gửi
  • shipment.address_from.city_code: Mã tỉnh/thành phố gửi
  • shipment.address_to: Địa chỉ nhận
  • shipment.address_to.name: Tên người nhận
  • shipment.address_to.phone: Số điện thoại người nhận
  • shipment.address_to.email: Email người nhận
  • shipment.address_to.street: Địa chỉ người nhận
  • shipment.address_to.district: Quận/huyện nhận
  • shipment.address_to.district_code: Mã quận/huyện nhận
  • shipment.address_to.city: Tỉnh/thành phố nhận
  • shipment.address_to.city_code: Mã tỉnh/thành phố nhận
  • shipment.parcel: Thông tin gói hàng
  • shipment.parcel.name: Tên gói hàng
  • shipment.parcel.quantity: Số lượng
  • shipment.parcel.width: Số đo chiều rộng
  • shipment.parcel.height: Số đo chiều cao
  • shipment.parcel.length: Số đo chiều dài
  • shipment.parcel.weight: Trọng lượng
  • shipment.parcel.weight: Trọng lượng quy đổi hàng cồng kềnh
  • shipment.parcel.metadata: Ghi chú vận đơn
  • history: Lịch sử cập nhật trạng thái của vận đơn
  • history.status: Mã trạng thái vận đơn
  • history.status_text: Trạng thái vận đơn
  • history.status_desc: Mô tả trạng thái vận đơn
  • history.updated_at: Ngày cập nhật (kiểu string)
  • history.updated_time: Thời gian cập nhật (kiểu integer)
  • invoice.id: Mã phiếu chuyển tiền COD
  • invoice.count: Số lượng vận đơn trong phiếu
  • invoice.total: Tổng tiền COD Goship trả cho shop
  • invoice.fee: Tổng phí của tất cả vận đơn trong phiếu

Lưu ý: Chỉ các vận đơn ở trạng thái Hoàn thành mới có dữ liệu invoice.

Phân trang:

Mặc định url này sẽ trả về 25 bản ghi, để lấy nhiều hơn hoặc ít hơn 25 bản ghi mặc định, chúng ta sử dụng tham số size trên query string, ví dụ:

GET http://sandbox.goship.io/api/v2/shipments?size=30

Để di chuyển giữa các trang, chúng ta sử dụng tham số page trên query string

GET http://sandbox.goship.io/api/v2/shipments?size=30&page=2

Tìm kiếm shipment

Chúng ta sẽ sử dụng tham số code để tìm kiếm thông tin chi tiết về vận đơn đó.

GET http://sandbox.goship.io/api/v2/shipments/search?code=g3lm98me

Trong đó code có thể nhận giá trị của các trường id, order_id hoặc carrier_code.

Hoặc tìm kiếm 1 danh sách các vận đơn theo thời gian tạo sử dụng tham số fromto

  • from: Integer - Thời gian bắt đầu
  • to: Integer - Thời gian kết thúc

GET http://sandbox.goship.io/api/v2/shipments?from=12345678&to=87654321

Phân trang và Response data tương tự như API shipment listing ở trên.

Tham khảo tài liệu mô tả về Phân trang

Tạo mới vận đơn

Chúng ta có thể thêm mới 1 vận đơn bằng cách thực hiện 1 request như sau

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

Request body:

{
  "shipment": {
    "rate": "MTRfMTFfMTAwMg==",
    "order_id": "02846e55e191c5706a5021191563c2a6",
    "address_from": {
      "name": "Nguyễn Văn A",
      "phone": "0913131313",
      "street": "102 Thái Thịnh",
      "ward": "108",
      "district": "100900",
      "city": "100000"
    },
    "address_to": {
      "name": "Trần Văn B",
      "phone": "0912121212",
      "street": "51 Lê Đại Hành",
      "district": "100200",
      "city": "100000"
    },
    "parcel": {
      "cod": 500000,
      "amount": 500000,
      "weight": "220",
      "width": "15",
      "height": "15",
      "length": "15",
      "metadata": "Hàng dễ vỡ, vui lòng nhẹ tay."
    }
  }
}

Response data:

{
  "code": 200,
  "status": "success",
  "data": [],
  "id": "GSL9VBJ2Y6",
  "cod": "0",
  "fee": "133300",
  "tracking_number": "GA6NWFXL",
  "carrier": "Giao Hàng Nhanh (v3)",
  "carrier_short_name": "ghnv3",
  "created_at": "13/12/2021 14:59:56"
}

Trong đó:

  • 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í
  • order_id là mã vận đơn của đối tác.
  • address_from là thông tin người gửi. Thông tin về mã ward, 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.

Chúng ta sẽ luôn nhận được response HTTP 200 OK vì thao tác tạo vận đơn là một thao tác bất đồng bộ (asynchronous). Goship sẽ trả thông tin kết quả việc tạo vận đơn thông qua Webhooks.

Sửa thông tin Vận đơn

Goship hiện tại không hỗ trợ sửa thông tin vận đơn. Trường hợp bạn cần sửa thông tin, hãy hủy vận đơn cũ và tạo một vận đơn mới.trợ

Xóa vận đơn

DELETE http://sandbox.goship.io/api/v2/shipments/56GDG8F

Trong đó, 56GDG8F là mã vận đơn Goship.

Response data:

Success

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

Error

{
  "code": 404,
  "status": "Error",
  "data": "Resource Not Found",
  "message": "Not Found"
}
Edit this page on GitHub Updated at Sat, Sep 17, 2022