Tổng đài hỗ trợ - 
1900 6750
( 7:00 - 22:00 )

api-reference
tai-lieu-api
tai-lieu-nha-phat-trien

Carrier Service

Carrier Service cho phép tính phí vận chuyển cho đơn hàng dựa vào thông tin giỏ hàng, địa chỉ giao hàng lúc người mua đặt hàng thay vì phí cố định dựa vào khu vực vận chuyển được cấu hình như hiện tại. Carrier Service có thể được tạo thông qua apps của bên thứ 3 hoặc private apps. Sau khi một Carrier Service được cài, nó sẽ cung cấp một danh sách các phí ship (shipping rates) có thể ở trang checkout. Các shipping rates này có thể được điều chỉnh dựa vào thông tin giỏ hàng, chủ shop dựa vào đó để tối ưu phí vận chuyển. Điều này có thể mang lại lợi ích về phí vận chuyển cho cả người mua và người bán.

Cấp phát quyền truy cập Carrier Service

Carrier Service thuộc nhóm order nên cần quyền (permission) read_orders, write_orders.

Xem thông tin về cấp phát quyền tại đây .

Xây dựng dịch vụ cung cấp các shipping rates cho Carrier Service

Để cài đặt được 1 Carrier Service bạn phải cung cấp 1 địa chỉ POST (public POST endpoint) thông qua callback_url để Sapo Web có thể lấy các phí ship (shipping rates) khi người dùng thanh toán. Địa chỉ này sẽ nhận các request từ Sapo Web.

Ví dụ một request lấy các shipping rates từ Sapo Web:

POST <callback url của bạn>
{
  "rate": {
    "origin": {
      "country": "Việt Nam",
      "country_code": "VN",
      "province": "Hà Nội",
      "province_code": "04",
      "district": "",
      "district_code": "",
      "ward": "",
      "ward_code": null,
      "name": "Cửa hàng tiện lợi",
      "address1": "434 Nguyễn Chí Thanh",
      "address2": "",
      "phone": null,
      "email": null
    },
    "destination": {
      "country": "Việt Nam",
      "country_code": "VN",
      "province": "Hà Nội",
      "province_code": "04",
      "district": "Ba Đình",
      "district_code": "494",
      "ward": null,
      "ward_code": null,
      "name": null,
      "address1": "43 Nguyễn Chí Thanh",
      "address2": null,
      "phone": null,
      "email": null
    },
    "items": [
      {
        "name": "Nước tăng lực",
        "sku": null,
        "quantity": 2,
        "grams": 300,
        "price": 1000000,
        "vendor": null,
        "requires_shipping": true,
        "product_id": 1122429712,
        "variant_id": 3424219217
      }
    ],
    "currency": "VND"
  }
}

Xem kết quả

HTTP/1.1 200 Ok
{
  "rates": [
    {
      "service_name": "Giao hàng trong 2h",
      "service_code": "GH2H",
      "total_price": 1000000,
      "description": "",
      "currency": "VND"
    },
    {
      "service_name": "Giao hàng tiêu chuẩn",
      "service_code": "GHTC",
      "total_price": 500000,
      "description": "",
      "currency": "VND"
    }
  ]
}

Thông tin trả về:

Khi Sapo Web request shipping rates theo callback_url của bạn, trường rates trả về phải là một mảng các object với thông tin như sau. Các trường đánh dấu required phải được trả về thì mới được tính là hợp lệ

service_name

(required)

Tên của shipping rate, người mua có thể nhìn thấy ở trang checkout.

Ví dụ: Giao hàng trong 2h

service_code

(required)

Mã code để phân biệt giữa các shipping rates. Ví dụ: GH2H
description

Mô tả cho shipping rate hiện tại

total_price

(required)

Tổng phí vận chuyển của đơn hàng

(kiểu integer được nhân 100 cho việc xử lý phần thập phân. Tương tự cho trường price trong request)

currency

(required)

Đơn vị tiền tệ của phí trả về (Phải cùng đơn vị tiền tệ với request)

    Caching phía server

    Sapo Web sử dụng 1 tầng cache. Các thông tin sau sẽ được sử dụng cho việc cache:

    • product_id, variant_id
    • khối lượng item (grams), số lượng item (quantity)
    • carrier service_id
    • địa chỉ đầu, địa chỉ đích

    Nếu một trong các thông tin trên thay đổi, request shipping rates mới sẽ được gọi sang đối tác. Thông tin cache sẽ được expire sau 15 phút đối với request success hoặc 30s đối với failure request

    Bạn có thể làm gì với Carrier Service?

    API Carrier Service cho phép bạn thực hiện như sau:

    Các thuộc tính của Carrier Service

    id

    Số duy nhất định danh cho Carrier Service.

    name

    Tên Carrier Service (Tên này sẽ xuất hiện trong cấu hình trang admin của chủ shop)

    callback_url

    Đường dẫn Sapo Web cần để lấy các phí ship từ đối tác

    active

    Trạng thái bật tắt Carrier Service

    type

    legacy hoặc api (mặc định là api)

    service_discovery

    Trạng thái xác định chủ shop có thể nhìn thấy các shipping rates trong cấu hình trang admin. Các shipping rates này có được bằng việc gửi 1 request xác định (dummy request) tới callback_url trong trang cấu hình admin của chủ shop

    Endpoints

    POST /admin/carrier_services.json

    Tạo một Carrier Service

    POST /admin/carrier_services.json
    {
      "carrier_service": {
        "name": "Demo Shipping App",
        "callback_url": "http://shippingrateprovider_url.com",
        "service_discovery": true
      }
    }
    Xem kết quả
    HTTP/1.1 201 Created
    {
      "carrier_service": {
        "id": 214144414,
        "name": "Demo Shipping App",
        "active": true,
        "type": "api",
        "service_discovery": true,
        "callback_url": "http://shippingrateprovider_url.com"
      }
    }
    
    PUT/admin/carrier_services/#{id}.json

    Cập nhật các thuộc tính của 1 Carrier Service

    PUT /admin/carrier_services/214144414.json
    {
      "carrier_service": {
        "service_discovery": false
      }
    }
    Xem kết quả
    HTTP/1.1 200 Ok
    {
      "carrier_service": {
        "id": 214144414,
        "name": "Demo Shipping App",
        "active": true,
        "type": "api",
        "service_discovery": false,
        "callback_url": "http://shippingrateprovider_url.com"
      }
    }
    
    GET/admin/carrier_services.json

    Lấy danh sách tất cả Carrier Service

    GET /admin/carrier_services.json
    Xem kết quả
    HTTP/1.1 200 Ok
    {
      "carrier_services": [
        {
          "id": 214144414,
          "name": "Demo Shipping App",
          "active": true,
          "type": "api",
          "service_discovery": false,
          "callback_url": "http://shippingrateprovider_url.com"
        }
      ]
    }
    
    GET/admin/carrier_services/#{id}.json

    Lấy thông tin một Carrier Service

    GET /admin/carrier_services/214144414.json
    Xem kết quả
    HTTP/1.1 200 Ok
    {
      "carrier_service": {
        "id": 214144414,
        "name": "Demo Shipping App",
        "active": true,
        "type": "api",
        "service_discovery": false,
        "callback_url": "http://shippingrateprovider_url.com"
      }
    }
    
    DELETE/admin/carrier_services/#{id}.json

    Xoá một Carrier Service

    DELETE /admin/carrier_services/214144414.json
    Xem kết quả
    HTTP/1.1 204 No Content
    

    Bài viết trên có hữu ích cho bạn không?

    Hữu ích Không hữu ích
    Số lượt đánh giá hữu ích: