Truy xuất và cập nhật gói thuê bao

Sau khi truy xuất một gói thuê bao, bạn có thể sử dụng thông tin từ phản hồi thành công để thay đổi trạng thái của gói thuê bao hoặc cập nhật gói thuê bao. Trang này tập trung vào các cách bạn có thể truy xuất và cập nhật gói thuê bao.

Truy xuất gói thuê bao

Để truy xuất gói thuê bao đã đặt hàng hoặc chuyển thành công, hãy sử dụng yêu cầu HTTP GET sau.

GET https://reseller.googleapis.com/apps/reseller/v1/customers/CUSTOMER_ID/subscriptions/SUBSCRIPTION_ID

Thay thế nội dung sau:

Thao tác này không có thông số nào trong phần nội dung yêu cầu.

Phản hồi thành công sẽ trả về mã trạng thái HTTP 200 và chế độ cài đặt của gói thuê bao. Trong phản hồi mẫu sau, thuộc tính isInTrial là false nhưng không có thuộc tính trialEndTime, nghĩa là khách hàng này chưa từng dùng thử gói này trong 30 ngày.

{
  "kind": "reseller#subscription",
  "customerId": "C0123456",
  "subscriptionId": "123",
  "skuId": "1010020028",
  "billingMethod": "ONLINE",
  "creationTime": "1331647980142",
  "plan": {
    "planName": "ANNUAL",
    "isCommitmentPlan": true,
    "commitmentInterval": {
      "startTime": "1331647980142",
      "endTime": "1363183980142"
    }
  },
  "seats": {
    "kind": "subscriptions#seats",
    "numberOfSeats": 10,
    "licensedNumberOfSeats": 10
  },
  "trialSettings": {
    "isInTrial": false
  },
  "renewalSettings": {
    "kind": "subscriptions#renewalSettings",
    "renewalType": "RENEW_CURRENT_USERS_MONTHLY_PAY"
  },
  "purchaseOrderId": "example.com_annual_1",
  "status": "ACTIVE",
  "resourceUiUrl": "URL to customer's Subscriptions page in the Admin console",
  "skuName": "Google Workspace Business Standard"
}

Truy xuất tất cả gói thuê bao của một khách hàng

Để truy xuất tất cả gói thuê bao của một khách hàng đại lý cụ thể đã được đặt hàng hoặc chuyển thành công, hãy sử dụng yêu cầu HTTP GET sau đây và đưa mã thông báo uỷ quyền vào:

GET https://reseller.googleapis.com/apps/reseller/v1/subscriptions?customerId=CUSTOMER_ID value&pageToken=START_DATE&maxResults=MAX_NUMBER

Thay thế nội dung sau:

  • CUSTOMER_ID: Tên miền chính của khách hàng hoặc giá trị nhận dạng duy nhất của khách hàng.
  • START_DATE: Ngày bắt đầu ở định dạng YYYY-MM-DD.
  • MAX_NUMBER: Số kết quả tối đa được trả về trên trang phản hồi.

Thao tác này không có thông số nào trong phần nội dung yêu cầu.

Phản hồi thành công sẽ trả về mã trạng thái HTTP 200 và danh sách các gói thuê bao cũng như chế độ cài đặt của khách hàng. Danh sách gói thuê bao có thể bao gồm các sản phẩm không được quản lý trong phiên bản API Đại lý này.

Nếu bạn không quản lý khách hàng này, lỗi 403 "Forbidden" sẽ được trả về.

Truy xuất tất cả gói thuê bao có thể chuyển cho một khách hàng

Để truy xuất tất cả gói thuê bao của khách hàng có thể được chuyển sang cho đại lý quản lý, hãy sử dụng yêu cầu HTTP GET sau đây và thêm mã thông báo uỷ quyền. Bạn bắt buộc phải cung cấp customerId. Đây là giá trị nhận dạng duy nhất của khách hàng được trả về khi truy xuất tài khoản của khách hàng đã bán lại. customerAuthToken là mã chuyển giao do khách hàng cung cấp, dành riêng cho mã đại lý của bạn. Sau khi khách hàng tạo, mã này sẽ có hiệu lực trong 30 ngày. Để biết thêm thông tin về cách khách hàng tạo mã thông báo, hãy xem bài viết Chuyển tài khoản Google Workspace của bạn cho đại lý.

GET https://reseller.googleapis.com/apps/reseller/v1/subscriptions?customerId=CUSTOMER_ID&customerAuthToken=AUTH_TOKEN&pageToken=START_DATE&maxResults=MAX_NUMBER

Thay thế nội dung sau:

  • CUSTOMER_ID: Tên miền chính của khách hàng hoặc giá trị nhận dạng duy nhất của khách hàng.
  • AUTH_TOKEN: Mã chuyển giao do khách hàng cung cấp, dành riêng cho mã đại lý của bạn. Sau khi khách hàng tạo, mã này sẽ có hiệu lực trong 30 ngày. Để biết thêm thông tin về cách khách hàng tạo mã thông báo, hãy xem bài viết Chuyển tài khoản Google Workspace của bạn cho đại lý. Nếu giá trị này không hợp lệ hoặc đã hết hạn, phản hồi API sẽ trả về lỗi 403 "Forbidden".
  • START_DATE: Ngày bắt đầu ở định dạng YYYY-MM-DD.
  • MAX_NUMBER: Số kết quả tối đa được trả về trên trang phản hồi.

Thao tác này không có thông số nào trong phần nội dung yêu cầu.

Phản hồi thành công sẽ trả về mã trạng thái HTTP 200 và danh sách các gói thuê bao có thể chuyển của khách hàng, cùng với ngày hết hạn của mã thông báo chuyển và số lượng chỗ ngồi tối thiểu cần thiết trong đơn đặt hàng chuyển. Khách hàng có thể sở hữu các gói thuê bao bổ sung không thể chuyển nhượng.

{
  "kind": "reseller#subscriptions",
  "subscriptions": [
    {
      "kind": "subscriptions#subscription",
      "customerId": "custId-6543",
      "subscriptionId": "432",
      "skuId": "1010020028",
      "billingMethod": "ONLINE",
      "creationTime": "1331647980142",
      "plan": {
        "planName": "ANNUAL",
        "isCommitmentPlan": true,
        "commitmentInterval": {
          "startTime": "1331647980142",
          "endTime": "1363183980142"
        }
      },
      "seats": {
        "kind": "subscriptions#seats",
        "numberOfSeats": 10,
        "maximumNumberOfSeats": 500,
        "licensedNumberOfSeats": 10
      },
      "trialSettings": {
        "isInTrial": false
      },
      "renewalSettings": {
        "kind": "subscriptions#renewalSettings",
        "renewalType": "SWITCH_TO_PAY_AS_YOU_GO"
      },
      "transferInfo": {
        "transferabilityExpirationTime": "1333183980142",
        "minimumTransferableSeats": "20"
      },
      "purchaseOrderId": "PO_890",
      "status": "ACTIVE",
      "resourceUiUrl": "URL to customer's Subscriptions page in the Admin console",
      "skuName": "Google Workspace Business Standard"
    },
    {
      "kind": "subscriptions#subscription",
      "customerId": "custId-6543",
      "subscriptionId": "140",
      "skuId": "1010020028",
      "creationTime": "1329389322728",
      "plan": {
        "planName": "FLEXIBLE",
        "isCommitmentPlan": false
      },
      "seats": {
        "kind": "subscriptions#seats",
        "maximumNumberOfSeats": 50
        "licensedNumberOfSeats": 10
      },
      "trialSettings": {
        "isInTrial": false,
        "trialEndTime": "1331877480016"
      },
      "renewalSettings": {
        "kind": "subscriptions#renewalSettings",
        "renewalType": "SWITCH_TO_PAY_AS_YOU_GO"
      },
      "transferInfo": {
        "transferabilityExpirationTime": "1333183780159",
        "minimumTransferableSeats": "10"
      },
      "purchaseOrderId": "",
      "status": "ACTIVE",
      "resourceUiUrl": "URL to customer's Subscriptions page in the Admin console",
      "skuName": "Google Workspace Business Standard"
    },
  ],
  "nextPageToken": "token"
}

Nếu bạn dự định chuyển các gói thuê bao này bằng cách sử dụng thao tác hàng loạt, hãy chuyển tất cả các gói thuê bao. Việc chuyển từng gói thuê bao sẽ dẫn đến lỗi. Ngoài ra, thao tác hàng loạt chỉ chuyển các gói thuê bao có trạng thái ACTIVE. Để biết thêm thông tin, hãy xem bài viết Chuyển gói thuê bao.

Truy xuất tất cả gói thuê bao của đại lý

Để truy xuất tất cả các gói thuê bao đã được đặt hàng hoặc chuyển thành công của đại lý, hãy sử dụng yêu cầu HTTP GET sau đây và thêm mã thông báo uỷ quyền. 

GET https://reseller.googleapis.com/apps/reseller/v1/subscriptions?customerNamePrefix=PREFIX &pageToken=TOKEN&maxResults=MAX_NUMBER

Thay thế nội dung sau:

  • PREFIX: Phần đầu tên của khách hàng có gói thuê bao mà bạn đang tìm.
  • TOKEN: Mã thông báo xác định một trang cụ thể của kết quả mà máy chủ sẽ trả về.
  • MAX_NUMBER: Số kết quả tối đa được trả về trên trang phản hồi.

Thao tác này có thể sử dụng phạm vi truy cập chỉ đọc OAuth. customerNamePrefix, pageToken và maxResults là các chuỗi truy vấn không bắt buộc.

Ví dụ sau đây truy xuất tất cả gói thuê bao của đại lý thuộc về những khách hàng có tên bắt đầu bằng "exam":

GET https://reseller.googleapis.com/apps/reseller/v1/subscriptions?customerNamePrefix=exam

{
  "kind": "reseller#subscriptions",
  "subscriptions": [
    {
      "kind": "subscriptions#subscription",
      "customerId": "C0123456",
      "subscriptionId": "123",
      "skuId": "1010020028",
      "creationTime": "1331647980142",
      "billingMethod": "ONLINE",
      "plan": {
        "planName": "ANNUAL",
        "isCommitmentPlan": true,
        "commitmentInterval": {
          "startTime": "1331647980142",
          "endTime": "1363183980142"
        }
      },
      "seats": {
        "kind": "subscriptions#seats",
        "numberOfSeats": 10,
        "licensedNumberOfSeats": 10
      },
      "trialSettings": {
        "isInTrial": false
      },
      "renewalSettings": {
        "kind": "subscriptions#renewalSettings",
        "renewalType": "SWITCH_TO_PAY_AS_YOU_GO"
      },
      "purchaseOrderId": "PO_135",
      "status": "ACTIVE",
      "resourceUiUrl": "URL to customer's Subscriptions page in the Admin console",
      "skuName": "Google Workspace Business Standard"
    },
    {
      "kind": "subscriptions#subscription",
      "customerId": "custId-5678",
      "subscriptionId": "1404686",
      "skuId": "1010020028",
      "billingMethod": "ONLINE",
      "creationTime": "1329389322728",
      "plan": {
        "planName": "FLEXIBLE",
        "isCommitmentPlan": false
      },
      "seats": {
        "kind": "subscriptions#seats",
        "maximumNumberOfSeats": 50,
        "licensedNumberOfSeats": 10
      },
      "trialSettings": {
        "isInTrial": false,
        "trialEndTime": "1331877480016"
      },
      "renewalSettings": {
        "kind": "subscriptions#renewalSettings",
        "renewalType": "AUTO_RENEW"
      },
      "purchaseOrderId": "",
      "status": "ACTIVE",
      "resourceUiUrl": "URL to customer's Subscriptions page in the Admin console",
      "skuName": "Google Workspace Business Standard"
    },
  ],
  "nextPageToken": "token"
}

Cập nhật gói thuê bao

Cách cập nhật gói Google Workspace sẽ khác nhau tuỳ theo gói. Trước khi cập nhật kế hoạch, hãy cân nhắc những điều sau:

  • Khi bạn tạo một gói thuê bao và khách hàng đủ điều kiện, gói thuê bao đó có thể là gói dùng thử 30 ngày. Cả gói thanh toán linh hoạt và gói thanh toán theo cam kết hằng năm đều có thể dùng thử miễn phí trong 30 ngày. Trong thời gian dùng thử, bạn có thể thay đổi gói thanh toán của gói thuê bao thành gói cam kết linh hoạt hoặc hằng năm bất cứ khi nào cần. Tuy nhiên, sau khi thời gian dùng thử kết thúc và gói bắt đầu hoạt động, việc cập nhật gói sẽ tuân theo các quy tắc giống như các gói đang hoạt động của các gói thuê bao khác. Để chuyển ngay gói thuê bao dùng thử sang gói đang hoạt động, hãy bắt đầu sử dụng dịch vụ có tính phí từ gói thuê bao dùng thử miễn phí 30 ngày. Để biết thêm thông tin về bản dùng thử 30 ngày và các quy tắc về điều kiện của khách hàng, hãy xem trung tâm trợ giúp dành cho quản trị viên.

  • Bạn có thể cập nhật gói linh hoạt thành gói cam kết hằng năm.

  • Bạn không thể cập nhật gói cam kết hằng năm.

  • Không phải gói nào cũng dùng được với mọi sản phẩm. Để biết thêm thông tin về những sản phẩm mà các gói này sử dụng, hãy xem phần Sản phẩm và SKU.

Để cập nhật gói dùng thử 30 ngày hoặc gói thuê bao linh hoạt thành gói thuê bao hằng năm, hãy sử dụng yêu cầu HTTP POST sau:

POST https://reseller.googleapis.com/apps/reseller/v1/customers/CUSTOMER_ID/subscriptions/SUBSCRIPTION_ID/changePlan

Thay thế nội dung sau:

Ví dụ sau đây cập nhật gói thuê bao bằng subscriptionId có giá trị là 123. customerId là C0123456.

POST https://reseller.googleapis.com/apps/reseller/v1/customers/C0123456/subscriptions/123/changePlan

Nội dung yêu cầu có các thông tin sau:

{
  "kind": "reseller#changePlanRequest",
  "planName": "ANNUAL_MONTHLY_PAY",
  "seats": {
    "kind": "subscriptions#seats",
    "numberOfSeats": 10
  },
  "purchaseOrderId": "123_March2012"
}

Phản hồi thành công sẽ trả về mã trạng thái HTTP 201 và trả về chế độ cài đặt gói thuê bao đã cập nhật:

{
  "kind": "reseller#subscription",
  "customerId": "C0123456",
  "subscriptionId": "123",
  "skuId": "1010020028",
  "creationTime": "1331647980142",
  "plan": {
    "planName": "ANNUAL",
    "isCommitmentPlan": true,
    "commitmentInterval": {
      "startTime": "1331647980142",
      "endTime": "1363183980142"
    }
  },
  "seats": {
    "kind": "subscriptions#seats",
    "numberOfSeats": 10,
    "licensedNumberOfSeats": 10
  },
  "trialSettings": {
    "isInTrial": false
  },
  "renewalSettings": {
    "kind": "subscriptions#renewalSettings",
    "renewalType": "SWITCH_TO_PAY_AS_YOU_GO"
  },
  "purchaseOrderId": "123_March2012",
  "status": "ACTIVE",
  "skuName": "Google Workspace Business Standard"
}

Cập nhật số ghế của gói thuê bao

Việc cập nhật gói thuê bao cam kết hằng năm sử dụng các thuộc tính gói thuê bao khác với việc cập nhật gói thuê bao của gói linh hoạt của Google Workspace.

Cập nhật số chỗ ngồi cho gói thuê bao theo gói hằng năm

Để cập nhật chế độ cài đặt giấy phép người dùng của gói thuê bao hằng năm, hãy sử dụng yêu cầu HTTP POST sau:

POST https://reseller.googleapis.com/apps/reseller/v1/customers/CUSTOMER_ID/subscriptions/SUBSCRIPTION_ID/changeSeats

Thay thế nội dung sau:

Ví dụ sau đây cập nhật gói thuê bao bằng subscriptionId 123. customerId là C0123456. Nội dung của yêu cầu khác nhau tuỳ thuộc vào loại gói:

POST https://reseller.googleapis.com/apps/reseller/v1/customers/C0123456/subscriptions/123/changeSeats

Gói thuê bao của gói cam kết hằng năm của Google Workspace sử dụng nội dung yêu cầu này để cập nhật số lượng giấy phép người dùng. Giá trị numberOfSeats là tổng. Ví dụ: nếu trước đây bạn có 10 giấy phép người dùng và bạn có đơn đặt hàng của khách hàng cho 5 giấy phép mới, thì tổng số trong phần nội dung của yêu cầu cho numberOfSeats là 15, như trong ví dụ sau:

{
    "kind": "subscriptions#seats",
    "numberOfSeats": 15
}

Cập nhật số chỗ ngồi cho gói thuê bao của gói linh hoạt

Gói thuê bao của gói linh hoạt trên Google Workspace sử dụng phần nội dung yêu cầu để cập nhật các giấy phép người dùng. Giá trị maximumNumberOfSeats là tổng số các giấy phép hiện có và giấy phép mới. Đây là số lượng giấy phép người dùng tối đa mà tài khoản có thể cấp.

{
  "kind": "subscriptions#seats",
  "maximumNumberOfSeats": 15
}

Phản hồi thành công sẽ trả về mã trạng thái HTTP 201 và chế độ cài đặt giấy phép thuê bao đã cập nhật:

{
  "kind": "reseller#subscription",
  "customerId": "C0123456",
  "subscriptionId": "123",
  "skuId": "1010020028",
  "creationTime": "1331647980142",
  "plan": {
    "planName": "FLEXIBLE",
    "isCommitmentPlan": false
  },
  "seats": {
    "kind": "subscriptions#seats",
    "maximumNumberOfSeats": 15,
    "licensedNumberOfSeats": 10
  },
  "trialSettings": {
    "isInTrial": false
  },
  "skuName": "Google Workspace Business Standard"
}

Cập nhật chế độ cài đặt gia hạn của gói thuê bao

Để cập nhật chế độ cài đặt gia hạn của gói thuê bao cam kết hằng năm, hãy sử dụng yêu cầu HTTP POST sau:

POST https://reseller.googleapis.com/apps/reseller/v1/customers/CUSTOMER_ID/subscriptions/SUBSCRIPTION_ID/changeRenewalSettings

Thay thế nội dung sau:

Sau đây là ví dụ về nội dung yêu cầu:

{
  "kind": "subscriptions#renewalSettings",
  "renewalType": "SWITCH_TO_PAY_AS_YOU_GO"
}

Giá trị của thuộc tính renewalType có thể là bất kỳ giá trị nào sau đây:

  • AUTO_RENEW_YEARLY_PAY: Khi kết thúc khoảng thời gian của gói cam kết hằng năm, tự động gia hạn gói thuê bao thành ANNUAL_YEARLY_PAY với cùng một numberOfSeats.
  • AUTO_RENEW_MONTHLY_PAY: Khi kết thúc khoảng thời gian của gói cam kết hằng năm, hãy tự động gia hạn gói thuê bao thành ANNUAL_MONTHLY_PAY với cùng một numberOfSeats.
  • RENEW_CURRENT_USERS_YEARLY_PAY: Khi kết thúc khoảng thời gian của gói cam kết hằng năm, hãy gia hạn gói thuê bao thành ANNUAL_YEARLY_PAY nhưng sử dụng tổng số giấy phép của người dùng đang hoạt động. Đây là chế độ cài đặt mặc định cho các gói cam kết hằng năm đang hoạt động (thanh toán hằng năm).
  • RENEW_CURRENT_USERS_MONTHLY_PAY: Khi kết thúc khoảng thời gian của gói cam kết hằng năm, hãy gia hạn gói thuê bao thành ANNUAL_MONTHLY_PAY nhưng sử dụng tổng số giấy phép của người dùng đang hoạt động. Đây là chế độ cài đặt mặc định cho các gói cam kết hằng năm đang hoạt động (thanh toán hằng tháng).
  • RENEW_ON_PROPOSED_OFFER: Khi kết thúc khoảng thời gian của gói cam kết hiện tại, hãy gia hạn theo đề xuất gia hạn mới nhất, trong đó numberOfSeats là số lượng giấy phép của người dùng đang hoạt động hiện tại hoặc cam kết ưu đãi được đề xuất (bất kỳ giá trị nào cao hơn).
  • SWITCH_TO_PAY_AS_YOU_GO: Khi kết thúc khoảng thời gian của gói cam kết hằng năm, hãy thay đổi gói cam kết hằng năm thành gói linh hoạt.
  • CANCEL: Khi kết thúc khoảng thời gian cam kết hằng năm, gói thuê bao sẽ bị tạm ngưng. Để tìm hiểu cách gỡ bỏ quyết định tạm ngưng, hãy xem trung tâm trợ giúp dành cho quản trị viên.

Phản hồi thành công sẽ trả về mã trạng thái HTTP 201 và chế độ cài đặt gia hạn gói thuê bao đã cập nhật:

{
  "kind": "reseller#subscription",
  "customerId": "C0123456",
  "subscriptionId": "123",
  "skuId": "1010020028",
  "creationTime": "1331647980142",
  "plan": {
    "planName": "ANNUAL",
    "isCommitmentPlan": true,
    "commitmentInterval": {
      "startTime": "1331647980142",
      "endTime": "1363183980142"
    }
  },
  "seats": {
    "kind": "subscriptions#seats",
    "numberOfSeats": 15,
    "licensedNumberOfSeats": 15
  },
  "trialSettings": {
    "isInTrial": false
  },
  "renewalSettings": {
    "kind": "subscriptions#renewalSettings",
    "renewalType": "SWITCH_TO_PAY_AS_YOU_GO"
  },
  "skuName": "Google Workspace Business Standard"
}

Bắt đầu sử dụng dịch vụ trả phí từ gói thuê bao dùng thử miễn phí

Để chuyển ngay gói thuê bao dùng thử miễn phí 30 ngày sang gói thuê bao dịch vụ có tính phí, nếu bạn đã thiết lập gói thanh toán cho gói thuê bao dùng thử, hãy sử dụng yêu cầu HTTP POST sau. 

POST https://reseller.googleapis.com/apps/reseller/v1/customers/CUSTOMER_ID/subscriptions/SUBSCRIPTION_ID/startPaidService

Thay thế nội dung sau:

Ví dụ sau đây có C0123456 làm customerId và giá trị subscriptionId là 123:

POST https://reseller.googleapis.com/apps/reseller/v1/customers/C0123456/subscriptions/123/startPaidService

Thao tác này không có thông số nào trong phần nội dung yêu cầu.

Phản hồi thành công sẽ trả về mã trạng thái HTTP 201 và chế độ cài đặt gói thuê bao đã cập nhật:

{
  "kind": "reseller#subscription",
  "customerId": "C0123456",
  "subscriptionId": "123",
  "skuId": "1010020028",
  "creationTime": "1331647980142",
  "plan": {
    "planName": "ANNUAL",
    "isCommitmentPlan": true,
    "commitmentInterval": {
      "startTime": "1331647980142",
      "endTime": "1363183980142"
    }
  },
  "seats": {
    "kind": "subscriptions#seats",
    "numberOfSeats": 15,
    "licensedNumberOfSeats": 15
  },
  "trialSettings": {
    "isInTrial": false
  },
  "renewalSettings": {
    "kind": "subscriptions#renewalSettings",
    "renewalType": "SWITCH_TO_PAY_AS_YOU_GO"
  },
  "skuName": "Google Workspace Business Standard"
}

Nâng cấp hoặc hạ cấp gói thuê bao

Bạn không thể hạ cấp gói hằng năm giữa thời hạn và không thể lên lịch hạ cấp bằng cách sử dụng chế độ cài đặt gia hạn. Bạn nên đặt chế độ cài đặt gia hạn để chuyển sang FLEXIBLE, sau đó hạ cấp sau thời gian gia hạn.

Để nâng cấp hoặc hạ cấp gói thuê bao, hãy tạo một gói thuê bao mới bằng skuId mà bạn muốn nâng cấp hoặc hạ cấp.

POST https://reseller.googleapis.com/apps/reseller/v1/customers/CUSTOMER_ID/subscriptions

Thay thế nội dung sau:

  • CUSTOMER_ID: Tên miền chính của khách hàng hoặc giá trị nhận dạng duy nhất của khách hàng.

Lệnh gọi này sẽ chấm dứt gói thuê bao trước đó và tạo một gói thuê bao mới.

Tìm thêm thông tin về việc nâng cấp và hạ cấp trên trang Sản phẩm và SKU.