Shipment

Các thao tác với đơn hàng thông qua 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/ondemand-shipments

Response data:

{
  "code": 200,
  "status": "success",
  "data": [
    {
      "id": "GSVQ833P81",
      "code": null,
      "order_id": null,
      "shipper_phone": null,
      "shipper_name": null,
      "carrier": "1",
      "carrier_text": "Ahamove",
      "carrier_logo": "http://localhost/static/ahamove.png",
      "service": "HAN-BIKE",
      "requests": [],
      "vehicle": "BIKE",
      "discount": 0,
      "stop_fee": 0,
      "delivery_fee": 0,
      "total_fee_carrier": 0,
      "service_fee": 0,
      "total_fee": 0,
      "cod_amount": 0,
      "total_amount": 0,
      "tracking_url": null,
      "status": 900,
      "status_text": "Đơn mới",
      "error": null,
      "error_text": null,
      "note": "",
      "polylines": null,
      "can_cancel": true,
      "can_update": false,
      "pickup_at": null,
      "delivery_at": null,
      "shipper_accept_at": null,
      "completed_at": null,
      "returned_at": null,
      "metadata": [],
      "cancel_at": null,
      "created_at": "2025-04-26 16:03:24",
      "updated_at": "2025-04-26 16:03:24",
      "points": {
        "data": [
          {
            "id": "GS196QRP8J",
            "tracking_number": null,
            "tracking_url": null,
            "kind": 1,
            "kind_text": "Điểm lấy hàng",
            "is_return": false,
            "completed_at": null,
            "failed_at": null,
            "returned_at": null,
            "fail_note": null,
            "address": "360 Đ. Giải Phóng, Phương Liệt, Thanh Xuân, Hà Nội, Vietnam",
            "lat": "20.9856562",
            "lng": "105.8404401",
            "note": "",
            "status": 900,
            "status_text": "Đơn mới",
            "created_at": "2025-04-26 16:03:24",
            "parcel": null,
            "latest_status": {
              "data": {
                "status": 900,
                "status_text": "Đơn mới",
                "message": null,
                "created_at": "2025-04-26 16:03:24"
              }
            },
            "statuses": {
              "data": [
                {
                  "status": 900,
                  "status_text": "Đơn mới",
                  "message": null,
                  "created_at": "2025-04-26 16:03:24"
                }
              ]
            }
          },
          {
            "id": "GSNX8EXZLM",
            "tracking_number": null,
            "tracking_url": null,
            "kind": 2,
            "kind_text": "Điểm giao hàng",
            "is_return": false,
            "completed_at": null,
            "failed_at": null,
            "returned_at": null,
            "fail_note": null,
            "address": "373 P. Vũ Tông Phan, Khương Đình, Thanh Xuân, Hà Nội, Việt Nam",
            "lat": "20.9899983",
            "lng": "105.8137906",
            "note": "",
            "status": 900,
            "status_text": "Đơn mới",
            "created_at": "2025-04-26 16:03:24",
            "parcel": {
              "name": "Quần áo, Giày dép",
              "quantity": 0,
              "amount": 0,
              "cod_amount": 0,
              "length": 0,
              "width": 0,
              "height": 0,
              "weight": 500
            },
            "latest_status": {
              "data": {
                "status": 900,
                "status_text": "Đơn mới",
                "message": null,
                "created_at": "2025-04-26 16:03:24"
              }
            },
            "statuses": {
              "data": [
                {
                  "status": 900,
                  "status_text": "Đơn mới",
                  "message": null,
                  "created_at": "2025-04-26 16:03:24"
                }
              ]
            }
          }
        ]
      },
      "latest_status": {
        "data": {
          "status": 900,
          "status_text": "Đơn mới",
          "message": "Tạo đơn hàng",
          "created_at": "2025-04-26 16:03:24"
        }
      },
      "statuses": {
        "data": [
          {
            "status": 900,
            "status_text": "Đơn mới",
            "message": "Tạo đơn hàng",
            "created_at": "2025-04-26 16:03:24"
          }
        ]
      }
    }
  ]
}

Trong đó:

Tên trường	Mô tả
`id`	Mã vận đơn Goship
`code`	Mã vận đơn của hãng vận chuyển
`order_id`	Mã đơn hàng của đối tác
`shipper_phone`	Số điện thoại người gửi
`shipper_name`	Tên người gửi
`carrier`	Mã hãng vận chuyển
`carrier_text`	Tên hãng vận chuyển
`carrier_logo`	Logo hãng vận chuyển
`service`	Mã dịch vụ
`requests`	Danh sách các yêu cầu của hãng vận chuyển
`vehicle`	Phương tiện vận chuyển
`discount`	Mức giảm giá
`stop_fee`	Phí dừng đỗ
`delivery_fee`	Phí giao hàng
`total_fee_carrier`	Tổng phí của hãng vận chuyển
`service_fee`	Phí dịch vụ (nền tảng)
`total_fee`	Tổng phí của đơn hàng
`cod_amount`	Tổng tiền thu hộ
`total_amount`	Tổng tiền của đơn hàng
`tracking_url`	Đường dẫn theo dõi đơn hàng
`status`	Trạng thái đơn hàng
`status_text`	Trạng thái đơn hàng (text)
`error`	Mã lỗi
`error_text`	Mô tả lỗi
`note`	Ghi chú
`polylines`	Đường đi của đơn hàng
`can_cancel`	Có thể hủy đơn hàng
`can_update`	Có thể cập nhật đơn hàng
`pickup_at`	Thời gian lấy hàng
`delivery_at`	Thời gian giao hàng
`shipper_accept_at`	Thời gian người gửi chấp nhận đơn hàng
`completed_at`	Thời gian hoàn thành đơn hàng
`returned_at`	Thời gian trả hàng
`metadata`	Thông tin bổ sung
`cancel_at`	Thời gian hủy đơn hàng
`created_at`	Thời gian tạo đơn hàng
`updated_at`	Thời gian cập nhật đơn hàng
`points`	Danh sách các điểm giao hàng
`points[].id`	Mã điểm giao hàng
`points[].tracking_number`	Mã theo dõi đơn hàng
`points[].tracking_url`	Đường dẫn theo dõi đơn hàng
`points[].kind`	Loại điểm giao hàng (1: Điểm lấy hàng, 2: Điểm giao hàng)
`points[].kind_text`	Loại điểm giao hàng (text)
`points[].is_return`	Có phải là điểm trả hàng không
`points[].completed_at`	Thời gian hoàn thành đơn hàng
`points[].failed_at`	Thời gian thất bại đơn hàng
`points[].returned_at`	Thời gian trả hàng
`points[].fail_note`	Ghi chú lỗi
`points[].address`	Địa chỉ giao hàng
`points[].lat`	Vĩ độ
`points[].lng`	Kinh độ
`points[].note`	Ghi chú
`points[].status`	Trạng thái đơn hàng
`points[].status_text`	Trạng thái đơn hàng (text)
`points[].created_at`	Thời gian tạo đơn hàng
`points[].parcel`	Thông tin hàng hóa
`points[].parcel.name`	Tên hàng hóa
`points[].parcel.quantity`	Số lượng hàng hóa
`points[].parcel.amount`	Giá trị hàng hóa
`points[].parcel.cod_amount`	Giá tiền thu hộ
`points[].parcel.length`	Chiều dài hàng hóa
`points[].parcel.width`	Chiều rộng hàng hóa
`points[].parcel.height`	Chiều cao hàng hóa
`points[].parcel.weight`	Trọng lượng hàng hóa
`points[].latest_status`	Trạng thái mới nhất của đơn hàng
`points[].statuses`	Danh sách trạng thái

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/ondemand-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/ondemand-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/ondemand-shipments?code=g3lm98me

Hoặc GET https://sandbox.goship.io/api/v2/ondemand-shipments/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/ondemand-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/ondemand-shipments

Request body:

{
  "order_id": "INTERNAL-ORDER-ID",
  "paths": [
    {
      "address": "Ngõ 371 Phố Vũ Tông Phan, Phường Khương Đình, Quận Thanh Xuân, Hà Nội, Việt Nam",
      "name": "My Company",
      "phone": "0987654321",
      "lat": 20.9898715,
      "lng": 105.8139308,
      "kind": 1
    },
    {
      "address": "300 Đ. Giải Phóng, Phương Liệt, Hai Bà Trưng, Hà Nội, Việt Nam",
      "name": "Nguoi nhan",
      "phone": "0123456789",
      "lat": 20.9902259,
      "lng": 105.8405199,
      "kind": 2,
      "parcel": {
        "name": "Quần áo, Giày dép",
        "quantity": 0,
        "weight": 999,
        "height": 0,
        "width": 0,
        "length": 0,
        "cod_amount": 0,
        "amount": 0
      }
    }
  ],
  "carrier": 1,
  "vehicle": "BIKE",
  "service": "HAN-BIKE",
  "note": "Ghi chú cho tài xế",
  "metadata": ["Thông tin bổ sung ..."],
  "requests": [
    {
      "_id": "HAN-BIKE-ROUND-TRIP"
    }
  ]
}

Trong đó:

Tên trường	Mô tả	Type
`order_id`	Mã đơn hàng của đối tác	string
`paths`	Danh sách các điểm giao hàng	Array of object
`paths[].address`	Địa chỉ giao hàng	string
`paths[].name`	Tên người gửi hoặc người nhận	string
`paths[].phone`	Số điện thoại người gửi hoặc người nhận	string
`paths[].lat`	Vĩ độ	float
`paths[].lng`	Kinh độ	float
`paths[].kind`	Loại điểm giao hàng (`1`: Điểm lấy hàng, `2`: Điểm giao hàng)	Enum `1`, `2`
`paths[].parcel`	Thông tin hàng hóa	object
`paths[].parcel.name`	Tên hàng hóa	string
`paths[].parcel.quantity`	Số lượng hàng hóa	integer
`paths[].parcel.weight`	Trọng lượng hàng hóa (gram)	integer
`paths[].parcel.height`	Chiều cao hàng hóa (cm)	integer
`paths[].parcel.width`	Chiều rộng hàng hóa (cm)	integer
`paths[].parcel.length`	Chiều dài hàng hóa (cm)	integer
`paths[].parcel.cod_amount`	Tiền thu hộ của gói hàng	integer
`paths[].parcel.amount`	Giá trị hàng hóa	integer
`carrier`	Mã hãng vận chuyển Xem danh sách hãng vận chuyển	integer
`vehicle`	Phương tiện vận chuyển	Enum `BIKE`
`service`	Mã id dịch vụ Xem danh sách dịch vụ khi lấy biểu phí	string
`note`	Ghi chú	string
`metadata`	Thông tin bổ sung	Array of object
`requests`	Danh sách các yêu cầu bổ sung để tính phí đúng nhất	Array
`requests[]._id`	ID của yêu cầu	string
`requests[].tier_code`	Mã tier của yêu cầu (Đối với yêu cầu hàng cồng kềnh)Xem mẫu	string
`requests[].num`	Số lượng yêu cầu Xem mẫu	integer

Response data:

{
  "code": 200,
  "status": "success",
  "data": {
    "id": "GS3Y6X2OLK",
    "code": "GS3Y6X2OLK",
    "order_id": "G-MYTRACKING-CODE",
    "status": 901,
    "status_text": "Đã gửi sang hãng vận chuyển",
    "tracking_url": null,
    "metadata": ["Thông tin bổ sung ..."],
    "can-update": true
    ...
  }
}

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

PUT https://sandbox.goship.io/api/v2/ondemand-shipments/56GDG8F Trong đó, 56GDG8F là mã vận đơn Goship.

Các đơn có trạng thái trường can-update sẽ có thể sửa lại thông tin của đơn hàng để gửi lại sang hãng vận chuyển.

Request body: Tương tự khi tạo đơn.

Xóa vận đơn

DELETE https://sandbox.goship.io/api/v2/ondemand-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 hoả tốc qua Goship API

Webhooks

Hệ thống Goship webhook giúp các website tích hợp với Goship có thể nhận thông tin update tự động và nhanh chóng