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"
  }
}

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ệ

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:

• POST /admin/carrier_services.json Tạo mới một Carrier Service
• PUT /admin/carrier_services/#{id}.json Cập nhật một Carrier Service đã tồn tại
• GET /admin/carrier_services.json Lấy ra danh sách Carrier Service
• GET /admin/carrier_services/#{id}.json Lấy ra một Carrier Service
• DELETE /admin/carrier_services/#{id}.json Xóa một Carrier Service

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

id

name

callback_url

active

type

service_discovery

Endpoints

POST /admin/carrier_services.json

POST /admin/carrier_services.json

{
  "carrier_service": {
    "name": "Demo Shipping App",
    "callback_url": "http://shippingrateprovider_url.com",
    "service_discovery": true
  }
}

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

PUT /admin/carrier_services/214144414.json

{
  "carrier_service": {
    "service_discovery": false
  }
}

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

GET /admin/carrier_services.json

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

GET /admin/carrier_services/214144414.json

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

DELETE /admin/carrier_services/214144414.json

HTTP/1.1 204 No Content