課金詳細情報CSV

はじめに

SORACOMの各サービスの利用料金は、月初から月末(UTC)までの間を１区間として計算され、課金が行われます。 コンソール上ではこの課金額の合算値を確認できますが、コンソールもしくはAPIを利用すると、 この利用料金の詳細な内訳をCSV形式で取得できます。 このドキュメントでは、課金の詳細情報CSVについて説明します。

コンソールでの課金詳細情報CSVの取得

直近月の課金詳細は、課金情報タブの「今月のご利用料金」から取得できます。

このCSVは直近月の情報で、時間により随時更新されていきます。

また過去月のCSVについては、「過去のご利用料金」の各月の行をクリック後、画面最下部にあるボタンで取得可能です。

APIでの課金詳細情報CSVの取得

直近月の課金情報については、APIリファレンスのexportLatestBillingAPIで取得ができます。 また過去月の課金情報については、exportBillingAPIを使用してください。

現在の仕様では、月初が来た時点で、exportLatestBillingから取得できるCSVが当該月のものとなります。 また月初の締め処理（前月の課金再計算処理）が行われ課金金額が確定するまでの間は、exportBilling APIでは前月分を取得できません。 なお、月初の締め処理は通常月初から1-3営業日以内に完了します。

CSVのエンコード

CSVファイルは、UTF-8(BOMあり）のエンコードとなります。

CSVファイルの構造

CSVファイルは、次のような構造となっています。

以下が各項目の説明となります。

1行目 ヘッダー行

ヘッダー行には、項目名が並びます。 項目名は、大きく分けて「金額項目」と「タグ/グループ項目」に分かれ、金額項目のあとにタグ/グループ項目が出力されます。 「金額項目」「タグ/グループ項目」はいずれも可変のため、プログラムで取り込む場合は「CSVパース時の注意」を参考にしてください。

「金額項目」に表示される項目名は以下のとおりです。

• imsi
  • SIMのIMSI。SIM以外の課金項目(VPGや無料枠等)の場合、項目行が空となります。
• vpgId
  • SORACOM Canal/Directで使用するVirtual Private Gateway(VPG)のID。
  • VPG以外の課金項目(SIMや無料枠等)の場合は項目行が空となります。
  • SORACOM Canal/Directを使用していない場合は、この項目はCSVに出力されません。
• date
  • 課金項目については、対象日がyyyyMMdd形式で設定されます。
  • 無料利用枠については、対象月がyyyyMM形式で設定されます。

• billItemName

  • 課金/割引の項目名。現在以下の項目があります。

  課金レコード	内容
  basicCharge-ready	基本料金（SIM利用料金:ready時）
  basicCharge-active	基本料金（SIM利用料金:Active時）
  basicCharge-inactive	基本料金（SIM利用料金:Inactive時）
  basicCharge-suspended	基本料金（SIM利用料金:Suspended時）
  subscriberSuspensionCharge	Suspendedへの変更料金
  uploadDataCharge-xxxx-xxxx	上り（デバイスからSORACOM）へのデータ通信量。速度クラス(s1.fast等)と時間帯(daytime,nighttime)がハイフン区切りで付与されます。 例）uploadDataCharge-s1.fast-daytime
  downloadDataCharge-xxxx-xxxx	下り（SORACOMからデバイス）へのデータ通信量。速度クラス(s1.fast等)と時間帯(daytime,nighttime)がハイフン区切りで付与されます。 例）downloadDataCharge-s1.fast-nighttime
  customDNSCharge	CustomDNSのSIMごとの料金
  virtualPrivateGatewaySetupCharge	Virtual Private Gatewayのセットアップ料金(2016年4月までの分)
  virtualPrivateGatewayCanalSetupCharge	SORACOM Canal用のVirtual Private Gatewayセットアップ料金
  virtualPrivateGatewayDirectSetupCharge	SORACOM Direct用のVirtual Private Gatewayセットアップ料金
  virtualPrivateGatewayDoorSetupCharge	SORACOM Door用のVirtual Private Gatewayセットアップ料金
  virtualPrivateGatewayCharge	Virtual Private GatewayのSIMごとの利用料金
  soracomCanalVirtualPrivateGatewayCharge	SORACOM Canal用Virtual Private Gatewayの利用料金
  soracomCanalVPCPeeringCharge	SORACOM CanalのVPCPeeringごとの料金
  soracomDirectVirtualPrivateGatewayCharge	SORACOM Direct用Virtual Private Gatewayの料金
  soracomDirectVirtualInterfaceCharge	SORACOM DirectのVirtual Interfaseごとの料金
  soracomDoorVirtualPrivateGatewayCharge	SORACOM Door用Virtual Private Gatewayの料金
  soracomDoorVPNConnectionCharge	SORACOM DoorのVPN接続ごとの料金
  soracomBeamRequestCharge	Soracom Beam リクエスト利用料金
  soracomEndorseCharge	Soracom Endorse 利用料金
  soracomFunnelRequestCharge	Soracom Funnel リクエスト利用料金
  soracomJunctionCharge	Soracom Junctionの料金
  soracomJunctionInspectionCharge	Soracom Junctionインスペクションの料金
  docomoSMSCharge	SMS料金(DOCOMO回線)
  docomoInternatinalSMSCharge	国際SMS料金(DOCOMO回線)
  kddiSMSCharge	SMS料金(KDDI回線)

  割引レコード	内容
  dataTrafficFreeTier	データ通信無料利用枠
  soracomBeamRequestFreeTier	Soracom Beam リクエスト無料利用枠
  soracomEndorseFreeTier	Soracom Endorse 無料利用枠
  soracomFunnelRequestFreeTier	Soracom Funnel リクエスト無料利用枠
  dataTrafficCoupon	データ通信へのクーポン充当枠
  soracomBeamRequestCoupon	Soracom Beam リクエスト利用料へのクーポン充当枠
  soracomEndorseCoupon	Soracom Endorse利用料へのクーポン充当枠
  soracomFunnelRequestCoupon	Soracom Funnel利用料へのクーポン充当枠
  chargeCoupon	SORACOM利用料全体へのクーポン充当枠
  soracomAirBasicChargeVolumeDiscount	基本料金のボリュームディスカウント

• unitPrice

  • 料金の単価
  • 例えばデータ通信料の場合、1byteあたりの費用が出力されます。

• quantity

  • 課金/割引対象の数量
  • 例えばデータ通信量の場合、通信したbyte数が出力されます。

• amount

  • 項目の金額。unitPriceにquantityをかけた値が出力されます。

「タグ/グループ項目」には、各SIMに設定したタグ名と、グループ名が項目名として出力されます。 例えば次のようにタグ名/グループ名を付与すると、項目名とレコード行は次のようになります。 - SIM - 名前 : MySIM - タグ名: tag1 - タグ値: foo - グループ - グループID : d674d68e-da8a-44f6-8868-51d1f069bc06 - グループ名 : グループ 1

name,tag1,group:groupId,group:name
MySIM,foo,d674d68e-da8a-44f6-8868-51d1f069bc06,グループ 1

あるSIMにタグが付与されていたり、グループに所属したりしている場合は、そのSIMのレコード行にタグ値/グループIDおよび名前が 出力されるため、この値を使用することで、任意のタグ値やグループ名で集計をできます。

2行目以降 レコード行

２行目以降は、レコード行となります。 レコード行は「課金レコード」と「割引レコード」に分かれており、課金レコードの次に割引レコードが出力されます。

課金レコードは、IMSI/VPGIDごと、日ごと、課金項目ごとにレコードが作成され、quantity(数量）や金額(amount)は日(UTC)ごとに合算されます。 またIMSIやVPGにタグがついている場合は、タグ/グループ項目部分にその値が出力されます。

割引レコードは、無料利用枠やクーポン利用で利用金額から割引される項目が出力されます。日付(date)項目に対象の月が入ります。また金額(amount)の値として、割引額がマイナスで入ります。

なお、このCSVには消費税および合計金額に該当する項目はないため、請求金額と合わせる場合は、すべての金額(amount)を合算後、消費税率をかけ 小数点以下を切り上げしてください。

CSVパース時の注意点

CSVは、BOMつきのUTF-8でエンコードされていますので、UTF-8で読み込みを行ってください。

タグ/グループの値にカンマ(,)が入っている場合は、値がダブルコーテーションで括られます。 またダブルコーテーション(“)が入っている場合は、ダブルコーテーションでエスケープされます。 これらの文字を利用する場合は、エスケープを考慮できるCSVパーサを利用してください。

項目は可変のため、また今後ICCIDなど新規項目が追加になる可能性があるため、ヘッダー行とレコード行を合わせて読みこむようにしてください。 例えばCSVの1項目目がimsi、2項目がdateという形で固定で読み込むプログラムの実装した場合、SORACOM Canal/Directを使用してvpgIdが CSVに出力されたり、将来的にICCIDなどが追加されると正しくデータを取得できなくなるため、 CSVを一度オブジェクトやHash、連想配列など、レコード行をキー/値であつかえる形に変換した後、データを取り扱ってください。

Excelへのインポート

Office2013などの古いExcelの場合、文字コードの問題で、日本語などがCSVを開いただけでは正しく値が表示されないケースがあります。 この場合は、以下の手順でExcelにインポートすることが出来ます。

ダウンロードフォルダなどに入っている、ダウンロードしたCSVファイルをUTF-8に対応したテキストエディタで開く。

テキストエディタのデータを全選択して、コピーする

Excelを起動して、新規ワークシートを開く。

ワークシートの先頭セル(A1)を選択して、貼り付けを行う。

テキストウィザードを使用する。

区切り記号付きを選択して次へ

区切り文字にコンマを選択し、連続した区切り文字は１文字として扱うを未選択にして次へ

データ形式を標準にして完了

以上の手順で、Excelにデータがインポートされます。なお、IMSIが数字として表示されない場合は、IMSI列を選択して 形式を数値に変更してください。