ポノポノ JSON API仕様書

概要

• API名: FP-Ponopono 託送データ取得 JSON API
• バージョン: v1
• 機能: ポノポノのUIから取得できる託送のファイルリストをAPIとして提供する。
• ポノポノのAPI利用オプションのご契約が必要です。

認証

• 認証方式: APIキー + APIシークレット + UnixタイムスタンプによるHMAC署名方式
• 認証用ヘッダー
  • X-API-Key: 小売設定画面で発行できるAPIキー
  • X-Timestamp: Unix タイムスタンプ(秒)
  • X-Signature: 本資料署名の生成方法に示すHMAC署名

APIキーの発行

ポノポノのUIから、サイドパネルの小売名を選択して表示される小売の設定画面下部「APIキーの発行」から、 小売ごとに5つまでのAPIキーを発行できます。
任意の名前と有効期限、および必要であれば接続元IP(v4)を50件までCIDR形式で設定します。(/32とすれば単一のアドレスを対象にできます)
IPアドレスは複数行の貼り付けを行うと一括で設定可能です。Excelなどで作成した対象IPアドレスの一覧を貼り付ける事ができます。
IPアドレス制限のみ、発行後に変更することが出来ます 有効期限は無期限とすることも可能です。セキュリティポリシーに応じて選択ください。

APIシークレットは発行時にのみ表示されますので忘れずに控え、紛失した場合は対象のキーは削除し新たに作り直してください。
設定内容の作成後の修正もできませんので、設定を誤った場合も新たに作り直してください。

npmパッケージ

nodeもしくはbunjsを利用する場合、以下のnpmパッケージを公開しています。簡易に操作できるので強く推奨いたします。

ponopono-api

エンドポイント

ベースURL: https://fp-ponopono.com ベースURLに以下のPathを続けたものがエンドポイントとなります。

名前	Method	Path
ファイル一覧取得API	GET	/pn-api/v1/tso-files
ファイルダウンロードAPI	GET	/pn-api/v1/tso-files/:fileId

アクセスに利用するAPIキーは各小売に結びついており、一つのAPIキーは自動的に対象の小売へのアクセスに限定されます。

ファイル一覧取得API

託送ファイルの一覧をJSONで返します。
ポノポノのUIでは、帳票類とxml使用量/発電量が別の画面で提供されていますが、内部的にはすべて同列のファイルであり、APIとしては分離していません。 レスポンス例

{
  "meta": {
    "ppsCode": "4xxx",//小売コード
    "total":5 //データ数 
  },
  "data": [
    {
      "area": "03",//エリアコード 01:北海道~10:沖縄
      "filename": "Wxxxxxxxxxxxxxxx.zip",
      "downloadPath": "/ponopono-api/v1/tso-files/xxxxxxxxxxxxxxxxxx",//ダウンロード用URLパス
      "type": "低圧確定値",//ファイル種別
      "publishedAt": "2025-xx-xxT15:31:36.000Z",//データ公開時刻 UTC
      "lastDownloadedBy": "サンプルユーザ",//最終ダウンロードユーザ名
      "lastDownloadedAt": "2025-04-18T15:31:36.000Z" //最終ダウンロード時刻 UTC
    },
    ....
  ]
}

検索パラメータ

以下のパラメータをクエリに使えます。

パラメータ	例	デフォルト	備考
area	03		対象託送エリア01~10、指定がなければすべて
filename	請求書		対象ファイル名。部分一致
from	2025-01-01	実行時の7日前	ファイル取得日時の範囲の開始日時(日本時間)
to	2025-01-31	実行翌日	ファイル取得日時の範囲の終了日時(日本時間)。指定された日の23:59:59.999までを対象とする from-toの期間は最大40日まで。超えるとエラーを返す
downloaded	false		ダウンロード済みであるか。true=ダウンロード済み,false=未ダウンロード。 指定がなければすべて

使用例

#2025年1月に取得された、東京エリアの未ダウンロードファイルの一覧を取得。
https://fp-ponopono.com/ponopono-api/v1/tso-files?from=2025-01-01&to=2025-01-31&area=03&downloaded=false

ファイルダウンロードAPI

一覧取得のデータにあるdownloadPathをベースURLと連結したURLからファイルをダウンロードします。 レスポンスはJSONではなくバイナリが直接取得されます。
UIからのダウンロードと同様にダウンロード履歴にAPIからのダウンロードとして記録されます。
中国、および東京の一部のxlsxファイルの自動パスワード解除オプションはこのダウンロードにも有効となります。

署名の生成方法

以下、X-Signatureヘッダに設定する署名の生成方法をjavascript、pythonでの実装で示す。
リプレイ防止のため、タイムスタンプ、およびクエリを含んだリクエストのパスを元に署名にするので、リクエストの都度署名の作成が必要です。
タイムスタンプはサーバと60秒の差を許容します。

1. Unixタイムスタンプ(秒)、リクエストメソッド、リクエストパスをドットで連結し、署名対象文字列とする。
   パスはホスト部分を含まないので注意。
   javascript

   const requestPath = "/pn-api/v1/tso-files?area=03"
   const currentUnixTimeStamp = Math.floor(Date.now() / 1000)
   const stringToSign = `${currentUnixTimeStamp}.GET.${requestPath}

   python

   import time
   request_path = "/pn-api/v1/tso-files?area=03"
   current_unix_timestamp = int(time.time())
   string_to_sign = f"{current_unix_timestamp}.GET.{request_path}"

2. 署名対象文字をAPIシークレットによりHMAC-SHA256で署名とする。
   javascript

   const secret = "{APIキー発行時に得られるAPIシークレット}"
   const hmac = createHmac("sha256", secret)
   hmac.update(stringToSign, "utf8")
   const signature = hmac.digest('hex')

   python

   import hmac
   import hashlib
   secret = "{APIキー発行時に得られるAPIシークレット}"
   hmac_object = hmac.new(secret.encode('utf-8'), string_to_sign.encode('utf-8'), hashlib.sha256)
   signature = hmac_object.hexdigest()

エラーレスポンス

エラーは以下の形式で返却されます。error messageは実際のエラー理由に差し替わります。

{
  "error": "{error message}"
}

エラー理由	メッセージ
不正なタイムスタンプ	Invalid timestamp.
存在しないAPIキー	API key not found.
有効期限切れのAPIキー	API key expired.
不正な署名	Invalid signature.
IPアドレスの不許可	Unauthorized IP address.
存在しないファイル	File not found.

検証時の際、成功しない原因が不明であればサポートまでお問い合わせいただければ調査いたします。