ドキュメント

認証、REST API エンドポイント、MCP ツール、環境変数の設定方法。

認証

API キー

REST API と MCP の両方で共通の API キーを使用します。

条件	API キー
env var に `B2_CUSTOMER_CODE` あり	必須 — クエリ `?key=xxx` またはヘッダー `X-MCP-API-Key`
env var に `B2_CUSTOMER_CODE` なし	不要 — 呼び出し側がヘッダーで B2 情報を持ち込む形

B2 ログイン情報の優先順位

優先度	場所	ヘッダー / 変数名
1（最優先）	リクエストヘッダー	`X-B2-Customer-Code` / `X-B2-Customer-Password`
2	Vercel 環境変数	`B2_CUSTOMER_CODE` / `B2_CUSTOMER_PASSWORD`
—	どちらもなし	エラー

環境変数に B2 ログイン情報を入れずにデプロイすれば、API キーなしの公開 API になります。呼び出し側がヘッダーで認証情報を毎回渡す「持ち込み型」運用が可能。

環境変数

必須（3つ）

変数	説明
`B2_CUSTOMER_CODE`	お客様コード（10桁）
`B2_CUSTOMER_PASSWORD`	パスワード
`MCP_API_KEY`	MCP アクセスキー（任意の文字列）

任意（デフォルト依頼主）

設定しておくと、毎回の送り状作成で依頼主情報の入力を省略できます。

B2_DEFAULT_SHIPPER_NAME=株式会社XXX
B2_DEFAULT_SHIPPER_TEL=03-0000-0000
B2_DEFAULT_SHIPPER_ZIP=100-0000
B2_DEFAULT_SHIPPER_ADDR1=東京都
B2_DEFAULT_SHIPPER_ADDR2=千代田区
B2_DEFAULT_SHIPPER_ADDR3=丸の内1-1
B2_DEFAULT_INVOICE_CODE=0482540070
B2_DEFAULT_INVOICE_FREIGHT_NO=01
B2_DEFAULT_PRINT_TYPE=m5

REST API

12 エンドポイントで B2クラウドの全主要操作をカバー。

Swagger UI: /api/docs で全エンドポイントのインタラクティブなドキュメントを閲覧できます。
OpenAPI spec (JSON): /api/docs.json

Method	Path	用途	実測
GET	`/api/health`	ヘルスチェック	即時
POST	`/api/b2/login`	接続テスト	4.8s
POST	`/api/b2/check`	バリデーションのみ	4.9s
POST	`/api/b2/save`	check → 保存	5.1s
POST	`/api/b2/print`	check→保存→印刷→PDF→追跡番号	12.5s
GET	`/api/b2/download`	署名付き PDF ダウンロード（60秒有効）	—
POST	`/api/b2/reprint`	発行済み伝票の再印刷	—
GET	`/api/b2/history`	履歴検索	4.8s
GET	`/api/b2/saved`	保存済み伝票一覧	4.7s
DELETE	`/api/b2/saved`	保存済み伝票削除	4.1s
GET	`/api/b2/tracking`	追跡情報取得	4.2s
GET/PUT	`/api/b2/settings`	プリンタ設定	5.0s

MCP サーバー

claude.ai での設定

Settings → MCP Connectors → Add で以下の URL を登録:

https://your-app.vercel.app/api/mcp?key=b2mcp-xxxxx

Claude Desktop での設定

{
  "mcpServers": {
    "b2cloud": {
      "command": "npx",
      "args": ["-y", "mcp-remote", "https://your-app.vercel.app/mcp?key=b2mcp-xxxxx"]
    }
  }
}

ツール一覧（14ツール）

ツール名	説明
`create_and_print_shipment`	伝票作成→印刷→PDF→追跡番号を一括実行。`auto_shortest: true` で最短配達日時を自動差込可能
`validate_shipment`	バリデーションのみ
`save_shipment`	伝票保存のみ
`print_saved_shipments`	保存済み伝票を印刷
`search_history`	発行済み伝票を検索
`get_tracking_info`	12桁追跡番号で照会
`reprint_shipment`	発行済み伝票を再印刷
`delete_saved_shipments`	保存済み伝票を削除
`get_account_info`	アカウント情報取得
`list_saved_shipments`	保存済み伝票一覧
`get_printer_settings`	プリンタ設定取得
`set_printer_type`	プリンタ種別切替
`search_delivery_date`	配達予定日検索（B2認証不要）。4商品別の配達日・時間帯制約・クール可否を返す
`find_shortest_delivery_slot`	最短配達スロット取得（調査用）。発行せずに「何日で届くか」を確認

最短配達スロット自動差込

「最短で届けて」と言われたとき、auto_shortest: { enabled: true } を付けるだけ。ヤマト運輸の配達予定日検索から最短日時を自動取得して送り状に差し込みます。

条件	結果
`shipment_date` 省略	エラー（`SHIPMENT_DATE_REQUIRED`）
service_type が 3/4/7/A	エラー（`UNSUPPORTED_SERVICE_TYPE`）
クール不可地域で `is_cool` ≠ "0"	エラー（`COOL_UNAVAILABLE`）
service_type × is_cool の不正組み合わせ	エラー（`INVALID_SERVICE_COOL`）

クール不可地域: 利島/式根島/御蔵島/青ヶ島/小笠原。レスポンスに auto_shortest_applied が含まれ、判断根拠（rationale）も返ります。

実機で踏み抜いた落とし穴

Node.js 実装で実際に踏んで解決済みの罠。すべて自動回避されます。

#	罠	対処
1	CSRF ヘッダ必須	Origin / Referer / X-Requested-With を自動付与
2	認証は5段階	bmypage GET → POST → 302追跡 → ME0002 → OAuth → template
3	ME0002 は form-urlencoded	jQuery の dataType は「レスポンス型」指定
4	302 リダイレクト手動追跡	`redirect: 'manual'` + Cookie 保存
5	PDF は 2段階取得	`checkonly=1` → `fileonly=1`
6	12桁追跡番号は PDF 取得後	polling Success だけでは UMN 内部番号のまま
7	search_key4 は 16文字以内	17文字や記号で `ES002070`
8	DELETE は msgpack+zlib 必須	JSON body では 409 or 実削除されない
9	polling の Error は正常	`summary=queued` は処理中
10	タイム便の時間帯	`0010` / `0017` のみ