👋 HOOPヘルプセンターへようこそ

• 安全在庫割れ — フリー在庫が安全在庫数を下回っているSKUの件数
• 未確認の入出庫 — 実施日を過ぎても「実施見込」のままの記録
• 発注点警告 — 発注点までの日数が会社設定の警告日数を下回った品番
• 滞留在庫 — 会社設定の日数以上、出庫されていないSKU
• 🔮 枯渇予測 — 直近の消費ペースから、まもなく在庫切れになると予測されたSKU

各カードをタップすると、該当する一覧画面に直接ジャンプします。

今動かす在庫（アクションボード）

ホーム下部には、枯渇間近・安全在庫割れのSKUを優先表示するリストがあります。

• 安全在庫を反映 — AI推奨安全在庫をワンタップでSKUに適用
• 発注メモをコピー — 品番・フリー在庫・推奨値などをテキストとしてコピーし、発注メールやチャットに貼り付け可能

登録の流れ

1. 「在庫情報」メニューから分類（カテゴリ）を選ぶ
2. 「登録…」ボタンから品番を新規登録（品番コード・品名・設定原価など）
3. 品番登録時に、同名のSKUが自動で1件作成されます。サイズ違い等が必要な場合はSKUタブから追加登録

公開設定と絶版

• 公開／非公開 — 営業ポータルや共有在庫リンクに載せるかどうか
• 絶版 — 新規取扱を止めるフラグ（公開設定とは独立）。在庫の消化は可能です。他システム連携時の属性同期にも使います
• 取扱中／中止 — 運用上のアクティブ状態

直近30日間の確定出庫実績から1日あたりの消費ペースを算出し、「あと何日で枯渇するか」を予測します。予測が会社設定の警告日数以内の場合は「枯渇間近」バッジで警告します。

SKUサマリー画面には、消費ペース×リードタイム（会社設定で変更可）から算出したAI推奨安全在庫が現在値と大きく異なる場合に表示され、ワンタップで安全在庫数へ反映できます。既存の手動設定を壊すことはなく、あくまで「提案」として重ねて表示されます。

元ロットの連携方法

1. 入庫登録・編集フォームの「元ロット（任意）」欄に、原材料・部材ロットのコードを入力
2. QRコードをカメラでスキャンするか、候補一覧（入力補完）から選択、または直接入力
3. 空欄のまま保存すれば、外部からの仕入れ品としてそのまま登録できます

存在しないコードを指定した場合は「元ロット「〇〇」に一致する入庫ロットが見つかりません」というエラーが表示され、保存されません。

系譜ツリー画面（/lot_trace）

ロットのQRコードをスキャンするか、入出庫記録一覧の🔗アイコンから開くと、親（原材料）→子（半製品）→孫（完成品）という系譜がツリー形式で一望できます。各ロットのQRコード・出庫履歴・仮押さえ状況もあわせて確認できます。管理画面・現場端末・営業ポータルのいずれからもアクセス可能です。

SKU設定画面の 引当管理（ロットトレース） をONにすると、そのSKUは出庫のたびに「どの入庫ロットから払い出したか」を厳密に記録します。

営業ポータルで「出庫（確定）」を押すと、サーバー側が実施日時の古い順（FIFO）に入庫ロットを選び、要求数量を満たすまで複数ロットへ自動分割して出庫します。営業マンは数量と顧客名を入力するだけでよく、倉庫の先入れ先出しルールを意識する必要はありません。

メリット

• パスワード不要 — 営業は普段使っている LINE からワンタップでポータルに入れます。
• 自社ブランドのまま届く — 御社の公式アカウント上にメニューや案内を置けます。
• その場で在庫操作 — フリー在庫の確認・仮押さえ・出庫確定まで、LINE内で完結できます。
• URLの配布が簡単 — リッチメニューやトークに「LINE用 URL」を貼るだけで始められます。

設定手順

1. LINE公式アカウントを用意する
   まだない場合は LINE公式アカウント を作成します（無料プランでも始められます）。
2. LINE Developers でチャネルを用意する
   LINE Developers Console にログインし、公式アカウントに紐づく Messaging API チャネルを作成（または既存アカウントを連携）します。 表示される チャネルID・チャネルシークレット・チャネルアクセストークン（長期） を控えておくと、あとで HOOP に貼り付けやすくなります。
3. LIFF アプリを追加する
   チャネルの「LIFF」からアプリを追加します。
   • サイズ: Full（推奨）
   • エンドポイントURL: https://hoop.956.jp/sales_portal/liff
   作成後に表示される LIFF ID（例: 1234567890-AbCdEfGh）を控えます。
4. HOOPに登録する
   管理者でログイン → 設定 → HOOP設定 → 編集 → 「LINE連携」に LIFF ID（必須）を入力して保存します。 チャネルID・シークレット・アクセストークンは任意ですが、控えてある場合は合わせて登録してください。
5. 営業ポータルの LINE用 URL をコピーする
   設定 → ポータルURL → 営業ポータルでポータルを発行（または既存の詳細を開き）、画面上の LINE用 URL をコピーします。
6. リッチメニューやトークに貼る
   公式アカウント管理画面で、リッチメニューのボタンやトークメッセージにその URL を設定します。 営業担当がタップすると、LINE内でポータルが開き、仮押さえ〜出庫まで使えます。

うまく開かないとき

• HOOP設定に LIFF ID が入っているか
• LIFF のエンドポイントURLが https://hoop.956.jp/sales_portal/liff になっているか
• LINE用 URL が古い（ポータルを再発行・無効化したあと）ものになっていないか
• スマホの通常ブラウザではなく、LINEアプリ内から開いているか

取引先や協力会社に「今ある分だけ」を見せたいときに使います。パスワード不要のトークンURLで、公開設定のSKUのフリー在庫を一覧・検索できます。

1. 「設定 → ポータルURL → 共有在庫」を開く
2. 表示名（例: ○○商事さま向け）と、任意で有効期限を指定して発行
3. 表示されたURLをコピーして相手に共有

AI Agent チートシート

下の契約（チートシート）をコピーしてエージェントに渡し、「やりたいこと」を自然文で依頼します。キー文字列は含めないでください。

1. チートシートをコピーアコーディオンを開き「コピー」で全文を取得します（または /llms-api.txt）。
2. エージェントに読み込ませるCursor / OpenClaw 系などのルール・プロンプト・会話に貼ります。
3. やりたいことを伝える例: 「公開SKUカタログを同期する Python を書いて」「SKUコードの free_qty を確認する curl を」。
4. キーは見せない環境変数 HOOP_API_KEY 等で渡し、チャット・ログ・コミットに平文キーを出さない。

# HOOP Inventory Hub API — LLM / Agent cheat sheet
Base: https://hoop.956.jp
Auth: Authorization: Bearer <HOOP_API_KEY> (prefix often hoop_)
Scopes: catalog:read, stock:read — read-only. No write/Webhook yet.
OpenAPI: https://hoop.956.jp/openapi.yaml
Help: https://hoop.956.jp/help.html#api-hub

Hard rules:
- Call ONLY https://hoop.956.jp/api/v1/*
- Never invent POST/PATCH/DELETE
- Never print/commit/share the API key
- Use free_qty (not only qty) for sellable stock
- location_code is always "default" today

Endpoints:
GET /api/v1/catalog/skus?public_only=true&exclude_discontinued=true&updated_since=ISO&limit=1..500
GET /api/v1/skus/{code_or_id}
GET /api/v1/stock?sku_codes[]=A&sku_codes[]=B&limit=1..500
GET /api/v1/skus/{code_or_id}/stock

curl:
export HOOP_API_KEY=…
curl -sS -H "Authorization: Bearer $HOOP_API_KEY" \
  "https://hoop.956.jp/api/v1/catalog/skus?exclude_discontinued=true&limit=50"

Playbooks:
- Sync catalog: list with public_only + exclude_discontinued; upsert by code; next run use updated_since
- Promise stock: GET …/skus/{code}/stock → free_qty
- Health: GET …/catalog/skus?limit=1 → expect 200

Errors: 401 unauthorized · 403 forbidden+required_scope · 404 not_found

やりたいこと一覧

できること（提供中）と、今後の予定を一覧にしています。項目を選ぶと呼び出し方までジャンプします。

接続の基本

ベースURL: https://hoop.956.jp

認証: Authorization: Bearer hoop_…（会社の APIキー。平文は発行時に一度だけ表示）

スコープ: catalog:read / stock:read（キーは組織に紐づき、他社データは返りません）

1. 管理者で「設定 → APIキー」を開く
2. 名前を付けて発行し、安全な場所に保存する
3. リクエストに Bearer ヘッダを付ける（クエリ api_key= も可だが非推奨）

SKUカタログを他システムへ同期する 提供中

こんなときに — EC／店舗／Agency／Trinity 側のマスタを HOOP の公開SKUに揃えたい。

呼び出し

GET /api/v1/catalog/skus?public_only=true&exclude_discontinued=true&limit=100
Authorization: Bearer $HOOP_API_KEY

1件のSKU詳細を取る 提供中

こんなときに — 相手システムの画面で、特定コードの品名・単位・公開状態だけ確認したい。

GET /api/v1/skus/{code}
Authorization: Bearer $HOOP_API_KEY

複数SKUの在庫をまとめて取る 提供中

こんなときに — カートや発注画面の候補一覧に、いまの在庫を並べたい。

GET /api/v1/stock?sku_codes[]=SKU-A&sku_codes[]=SKU-B
Authorization: Bearer $HOOP_API_KEY

売れる数量（フリー在庫）を確認する 提供中

こんなときに — 受注前に「いま客に約束できる数」だけ知りたい。

GET /api/v1/skus/{code}/stock
Authorization: Bearer $HOOP_API_KEY

連携の疎通確認をする 提供中

こんなときに — バッチやエージェントの起動時に、キーと権限が生きているか確認したい。

GET /api/v1/catalog/skus?limit=1
Authorization: Bearer $HOOP_API_KEY

書込・Webhook 予定

在庫の更新や、変更イベントの押し出し（Webhook）は順次提供予定です。エージェントに書込APIを発明させないでください。

具体的な使用例

言語別のサンプルです。アコーディオンを開き、必要ならコピーしてからキーだけ差し替えてください。

export HOOP_API_KEY='hoop_…'   # 平文キーはここにだけ置く
export HOOP_BASE='https://hoop.956.jp'

# カタログ（絶版除外）
curl -sS -H "Authorization: Bearer $HOOP_API_KEY" \
  "$HOOP_BASE/api/v1/catalog/skus?exclude_discontinued=true&limit=50"

# フリー在庫（1 SKU）
curl -sS -H "Authorization: Bearer $HOOP_API_KEY" \
  "$HOOP_BASE/api/v1/skus/SAMPLE-001/stock"

# 複数在庫
curl -sS -H "Authorization: Bearer $HOOP_API_KEY" \
  "$HOOP_BASE/api/v1/stock?sku_codes[]=SAMPLE-001&sku_codes[]=SAMPLE-002"

import os
import requests

BASE = "https://hoop.956.jp"
KEY = os.environ["HOOP_API_KEY"]
headers = {"Authorization": f"Bearer {KEY}"}

r = requests.get(
    f"{BASE}/api/v1/catalog/skus",
    headers=headers,
    params={"public_only": "true", "exclude_discontinued": "true", "limit": 100},
    timeout=30,
)
r.raise_for_status()
for sku in r.json()["skus"]:
    print(sku["code"], sku["name"], sku["is_public"])

stock = requests.get(
    f"{BASE}/api/v1/skus/SAMPLE-001/stock",
    headers=headers,
    timeout=30,
).json()["stock"]
print("free_qty=", stock["free_qty"])

require "json"
require "net/http"
require "uri"

base = "https://hoop.956.jp"
key  = ENV.fetch("HOOP_API_KEY")

uri = URI("#{base}/api/v1/skus/SAMPLE-001/stock")
req = Net::HTTP::Get.new(uri)
req["Authorization"] = "Bearer #{key}"

res = Net::HTTP.start(uri.host, uri.port, use_ssl: true) { |http| http.request(req) }
raise "HTTP #{res.code}" unless res.is_a?(Net::HTTPSuccess)

stock = JSON.parse(res.body).fetch("stock")
puts "free_qty=#{stock['free_qty']}"

const BASE = "https://hoop.956.jp";
const KEY = process.env.HOOP_API_KEY;

const res = await fetch(`${BASE}/api/v1/stock?sku_codes[]=SAMPLE-001`, {
  headers: { Authorization: `Bearer ${KEY}` },
});
if (!res.ok) throw new Error(`HTTP ${res.status}`);
const { stocks } = await res.json();
console.log(stocks.map((s) => [s.code, s.free_qty]));

「設定 → HOOP設定」から、コードの変更・デプロイなしにいつでも調整できます。

• 滞留判定日数（既定90日）— 最終出庫日からこの日数以上経過したSKUを「滞留在庫」として警告
• リードタイム（既定7日）— AI推奨安全在庫（消費ペース×リードタイム）の計算に使用
• 仮押さえ有効期間（既定14日）— 営業ポータルで新規仮押さえを登録した際のデフォルト期限日数
• LINE連携 — 営業ポータルを LINE から開くための LIFF ID など（詳しくは LINEで営業ポータルを使う）

しきい値が未設定のままでも、それぞれ安全なデフォルト値にフォールバックするため、省略しても問題なく運用できます。

「設定 → ポータルURL → 入出庫端末」から発行した専用URLで、現場のタブレット・スマホから入出庫・棚卸を記録できます。QR/バーコードスキャンでSKU・ロットを即座に呼び出し、そのままロット系譜トレース画面へも遷移できます。