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ố from và to

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, district và city lấy được từ api Dữ liệu quận/huyện và Dữ 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"
}