でんき点検ノート連携API・MCP

でんき点検ノートの連携APIを使うと、事業場の台帳・点検の状態・報告書PDFを、電気保安法人の業務システムや会計の仕組みから受け取れます。点検記録の作成・確定・訂正は、現地のアプリでだけ行い、APIからはできません。使うには、つなぎたい組織の管理者に鍵を発行してもらってください。

できること

事業場の一覧（種類・受電電圧・設備容量・点検の周期・次の点検）、月ごとの点検の状態（点検日・記録の区分・版・設置者の確認の有無・異常の件数・記録の指紋）、報告書PDFを受け取れます。

設置者の氏名・連絡先は、鍵に pii:read があり、組織が設定でオンにしている場合だけ含まれます。既定では、事業場のIDと記録の状態だけを返します。

点検記録の作成・確定・訂正・取消と、設置者の確認の代行は、どの入口からもできません（現地でしか記録を作らないため）。

鍵とスコープ

組織の管理者が「設定 → 連携」で鍵を発行します。鍵は発行したときに1回だけ表示されます。本番の鍵は dk_live_、試験用の鍵は dk_test_ で始まります。

鍵は Authorization ヘッダーに Bearer で付けます。1本の鍵で1分に60回まで呼べます。超えると 429 と Retry-After を返します。

作成・更新の呼び出しには Idempotency-Key ヘッダーを付けてください。同じ値なら24時間、同じ応答を返します。

GET /api/partner/v1/ping で鍵を確かめられます（組織のIDと、その鍵で使えるスコープを返します）。

スコープ

スコープ	できること
`sites:read`	事業場の一覧・換算係数の合計
`inspections:read`	月ごとの点検の状態
`reports:read`	報告書PDFの取得（pii:read も必要）
`pii:read`	設置者の氏名・住所を含める（組織の設定がオンのときだけ）
`schedule:read`	点検の予定
`schedule:write`	予定の日の変更・停電日の候補の送信（MCP。案→確認→実行）
`reports:send`	報告書・改善のお願いの送付（MCP。案→確認→実行）
`exceptions:read`	未解決の例外
`mcp:invoke`	MCP の受け口を使う

エンドポイント

連携API（/api/partner/v1）

メソッド	パス	中身
GET	`/api/partner/v1/sites`	事業場の一覧（site_id・site_code・種類・受電電圧・設備容量・点検の周期・次の点検）。sites:read
GET	`/api/partner/v1/inspections?month=2026-11`	その月の点検（inspection_id・site_id・種類・点検日・記録の区分・版・確認の有無・異常の件数・record_hash）。inspections:read
GET	`/api/partner/v1/inspections/{id}/report.pdf`	最新の版の報告書PDF。reports:read と pii:read
GET	`/api/partner/v1/ping`	鍵の確認

一覧は ?limit=（最大100、既定50）と ?cursor= で続きを取ります。日時は ISO 8601（+09:00 付き）です。

curl "https://denki-tenken-note.com/api/partner/v1/inspections?month=2026-11" \
  -H "Authorization: Bearer dk_live_xxxxxxxxxxxx_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"

{"data":[{"inspection_id":"0b6f5c1e-…","site_id":"c41d…","kind":"monthly",
  "inspected_on":"2026-11-10","source":"field","revision":1,"acknowledged":true,
  "defects":1,"record_hash":"3f9a0c51e7b2…"}],"next_cursor":null}

curl -o report.pdf "https://denki-tenken-note.com/api/partner/v1/inspections/0b6f5c1e-…/report.pdf" \
  -H "Authorization: Bearer dk_live_…"

お知らせ（Webhook）

送る出来事：inspection.finalized（記録の確定）、inspection.revised（訂正）、report.acknowledged（設置者の確認）、defect.opened（異常の記録）、defect.resolved（異常の改善）。中身はIDと状態だけです。

X-SBGG-Signature ヘッダーの t と v1 で署名を確かめてください。v1 は、署名用の秘密で「t.本文」を HMAC-SHA256 にした16進数です。300秒以上ずれていたら捨ててください。

届く順番は保証しません。受け手は created_at で判断してください。同じ出来事には同じ id が付きます。失敗したときは間隔を空けて最大6回送り直します。

{"id":"evt_…","type":"report.acknowledged","created_at":"2026-11-11T10:05:00+09:00","org_id":"…",
 "data":{"inspection_id":"0b6f5c1e-…","site_id":"c41d…","revision":1,"method":"link"}}

// Node.js：署名の確かめ方
import crypto from 'node:crypto';
function verify(secret, rawBody, header) {
  const p = Object.fromEntries(header.split(',').map((kv) => kv.split('=')));
  if (Math.abs(Date.now() / 1000 - Number(p.t)) >= 300) return false;
  const v1 = crypto.createHmac('sha256', secret).update(p.t + '.' + rawBody).digest('hex');
  return crypto.timingSafeEqual(Buffer.from(v1), Buffer.from(p.v1));
}

MCP（汎用AIからの呼び出し）

POST /api/mcp は MCP の Streamable HTTP（JSON-RPC 2.0）の受け口です。initialize・tools/list・tools/call に対応します。鍵に mcp:invoke と、各ツールのスコープが要ります。

送付や予定の変更のように外に影響するツールは2段階です。1回目は「案」（何をするか・誰に届くか）と confirmation_token（10分有効）を返すだけで、同じツールを confirmation_token 付きで呼んだときだけ実行します。実行は1つの confirmation_token につき1回だけです。

ツール（9つ）

ツール	種類	中身
`denki_list_today`	読み取り	今日の予定（事業場・種類・予定の時刻）
`denki_get_site`	読み取り	事業場の台帳の要約・次の点検・未解決の異常
`denki_inspection_status`	読み取り	月ごとの予定と実施・未確認の報告書
`denki_coefficients`	読み取り	換算係数の合計・内訳・上限までの残り（参考値）
`denki_open_exceptions`	読み取り	未解決の例外
`denki_send_report`	案→確認→実行	報告書を設置者に送る
`denki_propose_outage_dates`	案→確認→実行	年次点検の停電日の候補を設置者に送る
`denki_set_planned_date`	案→確認→実行	点検の予定の日を変える
`denki_send_defect_notice`	案→確認→実行	異常の改善のお願いを送る

curl -X POST https://denki-tenken-note.com/api/mcp \
  -H "Authorization: Bearer dk_live_…" -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/call",
       "params":{"name":"denki_send_report","arguments":{"inspection_id":"0b6f5c1e-…"}}}'
# 1回目は案と confirmation_token を返す。内容を確かめてから、
# "arguments":{"inspection_id":"0b6f5c1e-…","confirmation_token":"…"} で同じツールを呼ぶと送付する

設置者のエージェント

設置者（ビルの総務・工場の管理部門など）が使うエージェントは、確認リンクのトークンで /api/agent/v1/* を呼べます。ヘッダーに X-Counterparty-Token（確認リンクのトークン）と X-Agent-Name（エージェントの名前）を付けます。

報告書の要約（数値と判定）は1回で返します。確認・異常への回答・停電日の選択は2段階で、1回目は案を返し、設置者のメールに6桁のワンタイム番号（10分有効）を送ります。番号を付けて同じ呼び出しをしたときだけ実行します。番号を3回間違えると失効します。

回数の上限は、トークンごとに1分10回・1日100回です。

メソッド	パス	中身
POST	`/api/agent/v1/report/summary`	報告書の要約と、PDFの一時URL（5分有効）
POST	`/api/agent/v1/report/acknowledge`	報告書の確認（ワンタイム番号で2段階）
POST	`/api/agent/v1/defects/{id}/respond`	異常への回答（ワンタイム番号で2段階）
POST	`/api/agent/v1/outage/choose`	停電日の選択（停電のトークン。ワンタイム番号で2段階）

curl -X POST https://denki-tenken-note.com/api/agent/v1/report/acknowledge \
  -H "X-Counterparty-Token: <確認リンクのトークン>" -H "X-Agent-Name: example-assistant/1.0" \
  -H "Content-Type: application/json" -d '{}'
# → {"action":"acknowledge","confirmation_required":true}（設置者のメールに6桁の番号が届く）
# 番号を付けて同じ呼び出し：-d '{"otp":"123456"}'

エラー

401 鍵が無い・違う・止められた。403 スコープが足りない。404 見つからない（ほかの組織のIDも404）。409 同じ番号をすでに受け付けている。422 入力の誤り。429 回数の上限（Retry-After を見てください）。

OpenAPI 3.1 の定義（openapi.json）

でんき点検ノート 連携API・MCP