Shipment

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.

1. Lấy tất cả thông tin

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

Header:

Accept: application/json
Content-Type: application/json
Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbG.....

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ờ",
            "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",
            "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": "nva@gmail.com",
                "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": "tvb@gmail.com",
                "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.delivery_fee: Phí vận chuyển
  • shipment.total_fee: Tổng phí vận chuyển
  • shipment.status_code: Mã trạng thái vận đơn
  • shipment.status_text: Trạng thái vận đơn
  • 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)

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

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

Sử dụng phân trang tương tự như API Lấy tất cả vận đơn ở trên.

3. 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

Header:

Accept: application/json
Content-Type: application/json
Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbG.....

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,
        "weight":"220",
        "width":"15",
        "height":"15",
        "length":"15",
        "metadata":"Hàng dễ vỡ, vui lòng nhẹ tay."
    }
}
}

Response data:

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

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.

4. 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ợ

5. Xóa vận đơn

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

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

Header:

Accept: application/json
Content-Type: application/json
Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbG.....

Response data:

Success

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

Error

{
    "code": 404,
    "status": "Error",
    "data": "Resource Not Found",
    "message": "Not Found"
}