請求関連API

[更新: 2024年11月13日]

1．概要

さくらのクラウドで提供している「さくらのクラウドAPI」では、リソース操作以外に、請求金額や作成したリソースごとの利用明細など請求関連の情報も取得することが可能です。このAPIを利用することより、

  • さくらのクラウド使用料を元に、エンドユーザ向けに手数料を加算した請求を自動作成する

  • 過去の請求履歴よりサーバ・ディスク利用数・利用時間などリソース使用量を詳細に分析する

  • 単純な料金しきい値のみ設定可能な 料金アラート機能 を使用せず、トラフィック量との割合を元にした独自の料金アラート機能を作成する

など、料金部分においても自動化・省力化できる範囲を拡大することが可能となります。

※さくらのクラウドAPIの利用方法など、一般的な情報については APIドキュメント を参照ください。
　請求関連の機能についてもエンドポイントやサンプルといった情報も こちらのページ で紹介しています。

API URL

請求関連APIを利用する際のベースURLは以下より任意のものを使用します。

https://secure.sakura.ad.jp/cloud/zone/tk1a/api/system/1.0/
https://secure.sakura.ad.jp/cloud/zone/is1a/api/system/1.0/
https://secure.sakura.ad.jp/cloud/zone/is1b/api/system/1.0/
https://secure.sakura.ad.jp/cloud/zone/tk1v/api/system/1.0/

※リソースの制御に使用するAPIとはベースURLのバージョン部分が異なりますのでご注意ください。
※請求情報はゾーンによらずアカウント単位での合算となるため、どのURLに対してリクエストを行っても同じ結果を返します。

注意事項

  • 請求データは、当月分は翌日、毎月の確定分は月が明けた翌月1日作成されます

  • 請求データが更新されていない場合は時間をおいて再度取得してください

  • 請求関連APIを実行するためには、APIキーに「請求情報」の権限が付与され、「リソース閲覧」以上のアクセスレベルが必要になります。詳細は、 アクセスレベルのページ をご覧ください。

2．使用例

新たに請求情報の取得を専用に行うAPIキーを発行し、API経由で請求明細を取得するまでの使用例を解説します。

手順内で使用するパラメータは以下の通りです。

パラメータ

説明

会員ID

さくらインターネットの会員IDです。
例：nnn00000

請求書ID

毎月の請求書に採番される請求書をユニークに特定可能なIDとなります。請求書IDはアカウントごとに発番されます。
例：000000000

アクセストークン

APIキーのアクセストークンです。
例：ACCESS_TOKEN と表示しています。

アクセストークンシークレット

APIキーのアクセストークンシークレットです。
例：ACCESS_TOKEN_SECRET と表示しています

APIキーの作成

コントロールパネル上部にある[設定]をクリックします。

設定をクリックする

設定サブメニュー内の[APIキー]をクリックします。API管理画面が表示され、作成済みのAPIキーがある場合は一覧表示されます。

APIキーをクリックする

今回は請求情報取得用のAPIキーを新たに作成するので、右上の[追加]をクリックします。

追加をクリックする

請求情報取得専用APIキーとして必要最低限の権限とするため、アクセスレベルは「リソース閲覧」、他サービスへのアクセス権の「請求情報」にチェックを入れたのみの状態を選択し、[作成]ボタンをクリックします(名前や説明欄には今回作成したAPIキーであることが分かりやすい名称を入力しておきます)。

アクセスレベルに関する設定

一覧画面に今回作成したAPIキーが表示されるので、このAPIキーをダブルクリックします。

APIキーをダブルクリックする

詳細画面が表示され、実際のAPIアクセス時に必要となる「ACCESS_TOKEN」と「ACCESS TOKEN SECRET」が表示されます。

APIアクセス時に必要となる情報を表示

※アカウントが複数ある場合は、アカウントごとにAPIキーを作成する必要があります。

アカウントのリソースIDの取得

請求情報をAPIで確認するには、自身のアカウントIDが必要です。アカウントIDは以下の操作で事前に確認しておきます。以下のコマンド例ではcurlコマンドでAPIサーバに問い合わせを行い、応答結果をjqコマンドで見やすく整形します。

$ curl --user 'ACCESS_TOKEN':'ACCESS_TOKEN_SECRET' https://secure.sakura.ad.jp/cloud/zone/tk1a/api/cloud/1.1/auth-status | jq .

APIサーバからのレスポンスは以下のようになります。

{
     "is_ok": true,
     "Member": {
             "Errors": null,
             "Code": "xxx000001",
             "Class": "sakura"
     },
     "User": null,
     "AuthMethod": "apikey",
     "AuthClass": "account",
     "Permission": "create",
     "ExternalPermission": "bill",
     "RESTFilter": null,
     "IsAPIKey": true,
     "OperationPenalty": "none",
     "Account": {
             "Code": "billTest",
             "Name": "APIテスト用",
             "Class": "account",
             "ID": "000000526782"
     }
}

こちらのレスポンス末尾にある

"ID": "000000526782"

の数字部分がアカウントIDとなります。

※jqコマンドでは以下のようにキーの絞り込みを行うことが可能です。この機能によりアカウントIDのみ出力し、容易に確認することができます。

$ curl --user 'ACCESS_TOKEN':'ACCESS_TOKEN_SECRET' https://secure.sakura.ad.jp/cloud/zone/tk1a/api/cloud/1.1/auth-status | jq -c " .Account "

APIサーバからのレスポンスは以下のようになります。

{"Code":"billTest","Name":"APIテスト用","Class":"account","ID":"000000526782"}

過去の請求履歴を確認する

過去の請求履歴を表示します。APIのエンドポイントには /bill/by-contract/:accountid を使用します。

$ curl --user "ACCESS_TOKEN":"ACCESS_TOKEN_SECRET" https://secure.sakura.ad.jp/cloud/zone/tk1a/api/system/1.0/bill/by-contract/112700526782 | jq .

APIサーバからのレスポンスは以下のようになります。

{
     "is_ok": true,
     "ResponsedAt": "2016-06-01T13:33:13+09:00",
     "Count": 12,
     "Bills": [{
                     "PaymentClassID": 200,
                     "PayLimit": "2016-06-30T00:00:00+09:00",
                     "Paid": false,
                     "MemberID": "xxx000001",
                     "Date": "2016-06-10T00:00:00+09:00",
                     "BillID": 13481639,
                     "Amount": 4330
             }, {
                     "PaymentClassID": 200,
                     "PayLimit": "2016-05-31T00:00:00+09:00",
                     "Paid": true,
                     "MemberID": "xxx000001",
                     "Date": "2016-05-10T00:00:00+09:00",
                     "BillID": 13327977,
                     "Amount": 4330
             },
             .....
     }
}

レスポンスに含まれる主なキーの内容は以下の通りです。

キー名

説明

Date

ISO 8601形式の請求年月
例：2016-05-10T00:00:00+09:00

Amount

請求金額(税込の日本円)
例：4330

BillID

請求書ID。さらに詳細を見る場合に使用します。
例：13327977

請求書IDから請求明細を取得する

請求書IDから請求明細を取得する場合は、APIのエンドポイントに /billdetail/:membercd/:billno を使用します。

問い合わせ時に使用するパラメータは以下の通りです。

URLパラメータ

説明

membercd

取得したい請求書の会員ID

billno

処理対象となる請求書NO

パラメータを、会員IDと、先ほど調べた請求書NOに置換して実行します。

$ curl --user "ACCESS_TOKEN":"ACCESS_TOKEN_SECRET" https://secure.sakura.ad.jp/cloud/zone/tk1a/api/system/1.0/billdetail/xxx000001/000000000 | jq .

APIサーバからのレスポンスは以下のようになります。

{
     "is_ok": true,
     "ResponsedAt": "2016-06-01T13:39:54+09:00",
     "Count": 3,
     "BillDetails": [{
             "Usage": 2592000,
             "ServiceClassID": 50000,
             "Index": 1,
             "ContractID": "112700526782",
             "Amount": 0
     }, {
             "Usage": 2592000,
             "ServiceClassID": 50118,
             "Index": 2,
             "ContractID": "112700654736",
             "Amount": 108
     }, {
             "Usage": 2474113,
             "ServiceClassID": 50295,
             "Index": 3,
             "ContractID": "112700675125",
             "Amount": 540
     }]
}

レスポンスに含まれる主なキーの内容は以下の通りです。

請求明細項目

説明

Usage

詳細ごとの利用時間(秒)または利用量

ServiceClassID

明細に対応する契約ID

Index

同じ明細情報内における並び順

ContractID

詳細に対応する契約ID

Amount

詳細ごとの請求金額

請求明細をCSVで取得する

請求明細をCSV形式で取得する手順です。なお、CSV形式の請求明細はコントロールパネル右上の「請求情報」をクリックして表示される請求情報表示画面から取得することも可能です。

$ printf "`curl --user 'ACCESS_TOKEN':'ACCESS_TOKEN_SECRET' https://secure.sakura.ad.jp/cloud/zone/tk1a/api/system/1.0/billdetail/xxx000001/000000000/csv | jq .Body`"

APIサーバからのレスポンスは以下のようになります。

"連番","枝番","請求書番号","利用年月","支払いステータス","会員ID","アカウントコード","リソースID","商品ID","商品名","ゾーンID","ゾーン名","商品金額（税込）","リソース名","利用種類","フォーマット済み利用量"
"1","0","000000000","2015/09","入金済み","xxx000001","payTest","112700526782","50000","さくらのクラウド",,,"0",,,
"2","0","000000000","2015/09","入金済み","xxx000001","payTest","112700654736","50118","ISOイメージアップロード/5GB","is1b","石狩第2ゾーン","110","名称未設定 ISOイメージ 14ef10fedac","利用時間","30d, 0h"
"3","0","000000000","2015/09","入金済み","xxx000001","payTest","112700675125","50295","GSLB",,,"550","テスト","利用時間","28d, 16h"

各フィールドの内容は以下の通りです。

フィールド名

内容

連番

同一の請求書番号内での連番

枝番

1つの請求明細それぞれに紐づく小契約の連番

請求書番号

請求書は会員ID内のアカウントコードごとに発行されます。すべてのゾーンが含まれます。

利用年月

請求対象の利用年月

支払いステータス

未入金、支払済み、ペンディングの3種類があります。未請求の月はペンディング状態となります。

会員ID

会員ID

アカウントコード

アカウントコード

リソースID

使用されるリソースに割り振られるユニークな値です。請求書番号と組みあわせるとユニークなキーとなります。

商品ID

商品に割り当てられるIDとなります。同じ商品でも商品IDはゾーンごとに異なります。商品名は料金表から取得ください。

商品名

商品名が記載されます。ゾーンが異なる場合など、同一の商品名でも商品IDが異なる場合があります。ご注意ください。

ゾーンID

ゾーンに割り振られたIDになります。グローバルなリソースの場合は空欄となります。

ゾーン名

ゾーンに割り振られたゾーン名称が記載されます。グローバルなリソースの場合は空欄となります。

商品金額（税込）

税込の商品料金

リソース名

サーバの場合はサーバ名など、リソースにお客様が設定した名前が記載されます。

利用種類

「フォーマット済み利用量」に記載される利用量の種類が記載されます。

フォーマット済み利用量

請求対象の利用量が記載されます。

3．価格表一覧の取得

参照に必要な権限

APIに設定されているアクセスレベルが閲覧以上の権限である必要があります。

注意事項

API経由で取得できる価格表の一覧はAPIが紐付いているアカウント毎に異なります。
コントロールパネルから取得できる価格表の公開されているサービスの他に、コントロールパネルの価格表に掲載していないお客様個別に提供しているサービスの価格についてもAPIから取得することが可能です。
料金の更新は1日1回のため、リアルタイムでの更新は行われません。
APIをご利用の際は、短い間隔で多数のリクエストはお控えください。

詳細は さくらのクラウドAPIドキュメント をご確認ください。

参考：Curl（Linux）での呼び出し例

# APIキーによる認証を行わない場合
curl -H "X-Requested-With:XMLHttpRequest" \
    https://secure.sakura.ad.jp/cloud/zone/is1a/api/cloud/1.1/public/price.json

# APIキーによる認証を行う場合
curl --user "Access Token":"Access Token Secret" \
    https://secure.sakura.ad.jp/cloud/zone/is1a/api/cloud/1.1/public/price.json