連携API・MCP
POSや在庫のシステム、税理士さんや醸造所が使うAIから、醸造帳簿の記録を読んだり、移出の案を送ったりできます。申告の確定は、どの入口からもできません。確定は、人が画面で確かめて行います。
鍵と呼び出しの決まり
鍵は、組織の管理者（owner）が設定の画面で作ります。鍵ごとにスコープ（使える範囲）を選びます。
呼び出しには Authorization: Bearer <鍵> を付けます。鍵が無い・違う・止められているときは 401、スコープが足りないときは 403、組織の外のIDを指定したときは 404 を返します。
回数の上限は鍵ごとに60回/分です。超えると 429 と Retry-After を返します。作成の呼び出しには Idempotency-Key のヘッダーが必要で、同じキーなら同じ応答を返します。
鍵の確かめには GET /api/partner/v1/ping を使います。定義は OpenAPI（/api/partner/v1/openapi.json）でも公開しています。
連携API
| メソッド | パス | スコープ | 内容 |
|---|---|---|---|
| GET | /api/partner/v1/ping | — | 鍵の確かめ（組織のIDとスコープ） |
| GET | /api/partner/v1/stock | stock:read | タンク・容器ごとの在庫（L） |
| GET | /api/partner/v1/periods/{ym}/summary | period:read | 月の集計（数量だけ。税額は tax:read と組織の許可がある場合だけ） |
| POST | /api/partner/v1/removals | removal:write | 移出の案を送る（POSや在庫のシステムから）。確認待ちの箱に入り、利用者が確かめるまで正式な記録になりません |
curl "https://jozo-chobo.com/api/partner/v1/periods/2026-10/summary" \ -H "Authorization: Bearer <鍵>"
curl -X POST "https://jozo-chobo.com/api/partner/v1/removals" \
-H "Authorization: Bearer <鍵>" \
-H "Idempotency-Key: 5b0e7c2a-1d4e-4c1b-9f11-3a2b8c7d6e5f" \
-H "Content-Type: application/json" \
-d '{"date":"2026-10-15","product":"梅田IPA","package":"樽20L","units":3,"kind":"removal_taxable","counterparty":"〇〇酒店","doc_no":"D-1015-02"}'Webhook
知らせる出来事：period.closed（月を締めた）、return.confirmed（申告の下書きを確定した）、discrepancy.detected（棚卸で帳簿との差が見つかった）。
本文には税額を入れません。IDと月と件数だけです。署名はヘッダー X-SBGG-Signature（t=<UNIX秒>,v1=<HMAC-SHA256>）で、300秒以上ずれていたら捨ててください。同じ出来事は同じIDで、順番は保証しません。
MCP
MCP の入口は POST /api/mcp です。読み取りは1回で、記録は「案→確認→実行」の2回で行います。1回目は案と confirmation_token を返し、同じトークンで呼ぶと記録します。
| ツール | 段階 | スコープ | 内容 |
|---|---|---|---|
| get_stock | 読み取り | stock:read | タンク・容器ごとの量（L） |
| get_period_status | 読み取り | period:read | 月の状態・期限・締めのチェックの結果 |
| get_return_draft | 読み取り | return:read | 申告の下書きの数字・要確認の規則の一覧（「下書きです」の注記つき） |
| explain_return_cell | 読み取り | return:read | 下書きの1つの欄の計算式と、もとの記録の一覧 |
| list_exceptions | 読み取り | period:read | 例外（確かめが要る記録）の一覧 |
| record_removal | 案→確認→実行 | removal:write | 移出の記録。締めた月には記録できません |
| record_production | 案→確認→実行 | production:write | 製成の記録 |
| record_stock_count | 案→確認→実行 | production:write | 棚卸の記録 |
できないこと
- 申告の下書きの確定は、MCP でも連携APIでもできません。利用者が画面で確認の手順を通したときだけ確定します。
- 月の締め、締めた月の訂正、税理士の招待も、MCP では提供しません。
- e-Taxへの送信はしません。