Shipment

API lấy thông tin danh sách người nhận trên Goship 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 https://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,
      "is_recall": 0,
      "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 đơn vị vận chuyển nhận đơn
  • shipment.carrier_code: Mã vận đơn của đơn vị 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í vận chuyển. Giá trị của trường này có thể là:
    • 0: Khách trả
    • 1: Shop trả
  • 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
  • is_recall: thông tin đơn thu hồi (Chỉ hỗ trợ đơn thu hồi với đơn vị vận chuyển BestExpress)
    • 0: Không phải đơn thu hồi (Mặc định)
    • 1: Đơn thu hồi
  • 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 https://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 https://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 https://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 https://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 https://sandbox.goship.io/api/v2/shipments

Request body:

{
  "shipment": {
    "rate": "MTRfMTFfMTAwMg==",
    "payer": 1,
    "order_id": "02846e55e191c5706a5021191563c2a6",
    "is_recall": 0,
    "address_from": {
      "name": "Nguyễn Văn A",
      "phone": "0913131313",
      "street": "195 Đ. Thạch Bàn",
      "ward": "108",
      "district": "100900",
      "city": "100000"
    },
    "address_to": {
      "name": "Trần Văn B",
      "phone": "0912121212",
      "street": "51 Lê Đại Hành",
      "ward": "37",
      "district": "100300",
      "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."
    }
  }
}

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í
  • payer là người trả phí vận chuyển. Giá trị của trường này có thể là:
    • 0: Khách trả
    • 1: Shop trả
  • is_recall: thông tin đơn thu hồi (Chỉ hỗ trợ đơn thu hồi với đơn vị vận chuyển BestExpress)
    • 0: Không phải đơn thu hồi (Mặc định)
    • 1: Đơn thu hồi
  • 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.

Response data:

{
  "id": "GSL9VBJ2Y6",
  "shipment_status": 901,
  "shipment_status_txt": "Chờ lấy hàng",
  "cod": 100000,
  "fee": 25000,
  "is_recall": 0,
  "tracking_number": "GA6NWFXL",
  "carrier": "Giao Hàng Nhanh (v3)",
  "carrier_short_name": "ghnv3",
  "sorting_code": "HN01-01-02",
  "return_sorting_code": "RHN-0H1",
  "amount_return_shop": 75000,
  "created_at": "13/12/2021 14:59:56"
}

Trong đó:

  • id Mã vận đơn Goship
  • shipment_status Mã trạng thái vận đơn hàng. Danh sách trạng thái:
    • Lưu ý: Nếu xảy ra lỗi trong quá trình tạo vận đơn, shipment_status = 900, hệ thống sẽ trả thêm thông tin lỗi tại trường carrier_error
  • shipment_status_txt Tên trạng thái vận đơn.
  • cod Tiền COD của vận đơn
  • fee Tiền phí của vận đơn
  • tracking_number Mã vận đơn của đơn vị vận chuyển
  • carrier Tên đơn vị vận chuyển
  • carrier_short_name Mã đơn vị vận chuyển. Danh sách đơn vị vận chuyển
  • sorting_code Mã sorting code
  • return_sorting_code Mã sorting code chuyển hoàn
  • amount_return_shop Số tiền shop nhận được sau khi hoàn thành vận đơn
  • created_at Thoi gian tạo vận đơn
  • carrier_error Thông tin lỗi khi tạo vận đơn
  • is_recall: thông tin đơn thu hồi (Chỉ hỗ trợ đơn thu hồi với đơn vị vận chuyển BestExpress)
    • 0: Không phải đơn thu hồi (Mặc định)
    • 1: Đơn thu hồi

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.

Xóa vận đơn

DELETE https://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"
}
Rate
Cách lấy biểu phí vận chuyển toàn quốc qua Goship API
Invoice
API lấy thông tin phiếu đối soát trên Goship API