本記事は公開仕様の静的照合による案内です。ログインや認証付きAPI実行による動作試験は今回行っていません。
対象は「エネがえる共通 公開用 API」です。2026年10月10日に公開定義（OpenAPI 3.0.0、仕様書内バージョン1.0.0）を確認しています。旧V4や契約別のBiz・EV・AI Sense等へ、この認証方式や再試行条件を一律に適用しないでください。利用する接続先と契約対象の仕様を確認してください。
1. uid と API キーの使い方
ログインは POST /sys/login です。x-api-key ヘッダーを付け、JSON本文に username と password を指定します。product は対象サービスに合わせて確認してください。公開定義にある値は _ASP、_EV、_BIZ、_PPA、_SYS です。この列挙は各商品の全APIを共通仕様書で提供することを意味しません。
ログイン応答の uid はアクセストークンです。後続のリクエストでは、Authorization ヘッダーに uid の値を直接設定します。Bearer は付けません。対象操作に必要な x-api-key も送信します。
uid、APIキー、パスワードはサーバー側で管理し、WebページのJavaScriptや公開リポジトリへ埋め込まないでください。ログにも認証情報を出力しないでください。
2. 同時ログインと uid の管理
forcelogin=true は、同じユーザー名で先にログインしていた他の利用者のアクセストークンを無効にします。複数の処理が同じアカウントを利用する場合は、強制ログインの常用を避け、uid の共有・更新と再ログインの排他制御を設計してください。
この公開定義だけでは、uid の固定有効期間や、強制指定を伴わない再ログイン時の無効化条件を一律には確定できません。必要な失効条件は対象サービスの提供仕様・契約窓口で確認してください。定期的な強制ログインを共通の推奨処理にはしません。
3. エラー時は何を確認しますか？
HTTPステータス、対象パス、応答本文、Content-Type を合わせて確認します。認証エラーを401だけに限定しません。
・共通エラー定義：無効な認証トークンは403です。
・補助金一覧・詳細・検索の個別定義：認証エラーは401です。
・equipconsumptionest の個別定義：403はオプションが無効、またはグループ情報を取得できない場合です。再ログインだけで解決すると判断しないでください。
400は入力条件を修正します。補助金詳細の404は該当データなしです。認証情報の設定ミス、契約・オプションの不足、入力不備をそのまま自動再試行し続けないでください。エラー本文が text/plain の場合もあるため、すべての応答を無条件にJSONとして解析しないでください。
4. 再試行の設計
認証情報の失効が確認できた場合に限り、再ログインを一つの処理に集約し、新しい uid で対象リクエストを再試行する設計を検討してください。再試行の回数・間隔・タイムアウトは、対象APIの利用条件と処理の性質に合わせて設定します。公開仕様から共通の「3回・2秒間隔」は確認できません。
500・504などは、同じ処理を再送してよいか、利用回数・費用・重複処理へ影響しないかを確認したうえで、上限を決めて扱います。改善しない場合は、発生時刻、対象パス、認証情報を除いた入力条件、HTTPステータスと応答を添えてお問い合わせください。
5. 認証ヘッダーの最小例
以下は補助金一覧を1件取得する形のサンプルです。補助金データ照会の契約・権限がある場合に利用できます。自動再ログイン・再試行は含めていません。
サーバー側で取得済みのuidとAPIキーを環境変数へ設定した場合の例です。以下は1行のコマンドです。
curl --fail-with-body --get 'https://api.enegaeru.com/sys/subsidy' -H "x-api-key: ${ENEGAERU_API_KEY}" -H "Authorization: ${ENEGAERU_UID}" --data-urlencode 'limit=1'よくある確認事項
質問 | 回答 |
uid はいつ失効する？ | 共通公開定義ではforcelogin=trueが同一ユーザーの旧トークンを無効化します。固定有効期間やその他の失効条件は対象サービスで確認します。 |
失効したuidを使うとどうなる？ | 認証が通りません。共通定義403と補助金個別定義401を区別し、対象パスと応答本文を確認します。 |
uid失効への備えは？ | サーバー側で安全に管理し、更新と再ログインを一つの処理に集約。強制ログインの常用を避けます。 |
401や403が発生したら？ | 認証・契約オプション・入力条件を切り分けます。失効が確認できた場合のみ再ログインを検討します。 |
リトライの回数・間隔は？ | 共通の3回・2秒という定義は未確認。対象APIの条件・重複処理・費用への影響を確認し上限を設定します。 |