API ベータ
プログラムから、CSVの取り込み・計算・各照会画面の結果の取得ができます。社内システムとの連携や、毎日の自動実行に使えます。
ベータ版・無料 API は現在ベータ版として、すべてのアカウントで無料でご利用いただけます。今後、Pro プラン（有料）の機能として提供する予定です。移行する場合は事前にお知らせします。
仕様は今後変更することがあります。ご意見・ご要望は お問い合わせ からどうぞ。
1. 利用を始める
- 現在はベータ期間のため、すべてのアカウントで無料で利用できます（将来は Pro プランの機能になる予定です）。
- ログインして アカウント画面 の「API」で キーを発行します。キーは発行時に1回だけ表示されるので、安全な場所に保管してください。
- キーが漏れた場合は、同じ画面で再発行（古いキーは無効）または無効化してください。
API で扱うデータは画面と共通です（API で取り込んだデータは画面でも見られ、その逆も同じです）。
2. 認証
すべてのリクエストに、次のどちらかのヘッダーで API キーを付けます。
Authorization: Bearer jk_xxxxxxxxxxxxxxxxxxxxxxxxxxxx
X-API-Key: jk_xxxxxxxxxxxxxxxxxxxxxxxxxxxx
ベースURL: https://supply-demand-adjustment.duckdns.org/api/v1 通信は HTTPS のみです。
3. 基本の流れ
# ① 需要・供給の CSV を取り込んで、そのまま計算（?calculate=1）
curl -X PUT "https://supply-demand-adjustment.duckdns.org/api/v1/data/mixed?calculate=1" -H "Authorization: Bearer $KEY" -F "file=@mixed.csv"
# ② 遅延・欠品の最上位需要を取得
curl "https://supply-demand-adjustment.duckdns.org/api/v1/results/tops?status=遅延" -H "Authorization: Bearer $KEY"
# ③ 供給番号から最上位需要を照会
curl "https://supply-demand-adjustment.duckdns.org/api/v1/lookup/supply?no=PO-M01,PO-M02" -H "Authorization: Bearer $KEY"
CSV の形式は画面と同じです（CSVの作り方）。応答は JSON（UTF-8）で、表形式の結果は format=csv を付けると CSV（Excel 用の BOM 付き UTF-8）で受け取れます。
4. API 一覧
| メソッド・URL | 内容 |
|---|---|
GET /me | アカウント情報（プラン・API の利用状態 api_access・登録件数・最終計算日時・制限値） |
データの取り込み
| メソッド・URL | 内容 |
|---|---|
PUT /data/mixed | 需要・供給が混在した CSV を取り込む（両方とも置き換え）。数量プラス＝供給、マイナス＝需要 |
PUT /data/supplyPUT /data/demand | 供給だけ／需要だけを取り込む（その種類だけ置き換え） |
CSV は multipart の file フィールド、または本文そのもの（Content-Type: text/csv）で送ります。
?calculate=1 を付けると取り込み後に続けて計算します。POST でも同じです。
CSV に問題があるとエラー 422 invalid_csv（details に「○行目: …」）を返し、データは変更しません。 | |
DELETE /data/{supply|demand|all} | 登録データを削除 |
GET /priorities | 優先度テーブルを取得 |
PUT /priorities | 優先度テーブルを置き換え。JSON [{"code":"A","rank":1,"note":"特急"}] または CSV（優先コード,順位,説明） |
計算
| メソッド・URL | 内容 |
|---|---|
POST /calculate | 登録データで計算する。応答: calculated_at, stats（最上位需要数・納期内・遅延・欠品）, warnings |
計算結果を返す API の応答には calculated_at（計算日時）と stale（計算後にデータが変更されていれば true）が付きます。
計算結果（画面「計算結果」）
| メソッド・URL | 内容 |
|---|---|
GET /results/tops | 最上位需要サマリ（充足見込日・遅れ日数・判定）。status=納期内｜遅延｜欠品｜部品欠品｜欠品・部品欠品 |
GET /results/allocations | 直接引当・欠品・余剰。status=引当｜欠品｜余剰 |
共通パラメータ: q（番号・品目の検索。空白区切りで複数語）, page, per（1ページの件数。最大 5,000、既定 1,000）, format=csv（条件に合う全件を CSV で）。
JSON 応答: {"total", "page", "per", "items": [...]} | |
GET /results/traces | 全経路（供給 → 最上位需要）。件数が多いため format=csv（既定）または format=ndjson（1行1件の JSON）で順次送ります |
照会（各照会画面）
| メソッド・URL | 内容 |
|---|---|
GET /lookup/supply?no=… | 供給番号照会。供給番号（カンマ区切りで最大500件）→ 需要番号・必要日・最上位需要番号・最上位必要日・経路。not_found, surplus（余剰数量）も返す |
GET /lookup/tree?demand_no=… | 構成展開。需要番号 → 引き当たる供給と部品の供給（depth が階層）。max_rows（既定 5,000、最大 50,000） |
GET /lookup/expedite?demand_no=…&date=… | 前倒し計算。date（希望日。省略時は需要の必要日）→ 前倒しが必要な供給と日数（rows）、数量不足（shortages） |
照会の表は format=csv でも取得できます。
5. エラー
{"error": {"code": "invalid_csv", "message": "CSV に問題があるため…", "details": ["3行目: 需要の数量はマイナスで…"]}}
| HTTP | code | 意味 |
|---|---|---|
| 400 | bad_request | パラメータが不正 |
| 401 | unauthorized | キーが無い・正しくない・無効 |
| 403 | plan_required | API 対応プランではない（ベータ期間終了後、Pro プラン以外の場合） |
| 404 | not_found / demand_not_found | URL または指定した番号が無い |
| 409 | not_calculated / no_data | 計算結果が無い（先に計算）／データが無い |
| 413 | too_large | ファイルが大きすぎる |
| 422 | invalid_csv / invalid_priorities | CSV・優先度の内容に問題（details に詳細） |
| 429 | rate_limited | リクエストが多すぎる（Retry-After 秒後に再実行） |
| 503 | busy | 計算が混み合っている（しばらくして再実行） |
6. 制限
- リクエスト数: キーごとに 1分あたり 120 回
- アップロード: 1回 50MB・50万行まで。保存できるのは需要・供給あわせて 300,000 行まで
- 計算は全利用者で同時に2件まで（混雑時は最大60秒待ち、その後 503）
- API の利用（日時・API・件数）は記録され、アカウント画面で今月の利用状況を確認できます
7. サンプルコード
Python
import requests
BASE = "https://supply-demand-adjustment.duckdns.org/api/v1"
H = {"Authorization": "Bearer jk_xxxxxxxx"}
# 取り込み＋計算
with open("mixed.csv", "rb") as f:
r = requests.put(f"{BASE}/data/mixed", params={"calculate": 1}, headers=H, files={"file": f})
r.raise_for_status()
print(r.json()["calculation"]["stats"])
# 遅延している最上位需要（全ページ）
page = 1
while True:
r = requests.get(f"{BASE}/results/tops", params={"status": "遅延", "page": page, "per": 1000}, headers=H).json()
for t in r["items"]:
print(t["demand_no"], t["need_date"], t["expected_date"], t["delay_days"])
if page * r["per"] >= r["total"]:
break
page += 1
# 前倒し計算
plan = requests.get(f"{BASE}/lookup/expedite", params={"demand_no": "SO-001"}, headers=H).json()
for row in plan["rows"]:
if row["expedite_days"] > 0:
print(row["supply_no"], row["expedite_days"], "日前倒し")
PowerShell
$H = @{ Authorization = "Bearer jk_xxxxxxxx" }
$base = "https://supply-demand-adjustment.duckdns.org/api/v1"
Invoke-RestMethod -Method Put -Uri "$base/data/mixed?calculate=1" -Headers $H -InFile "mixed.csv" -ContentType "text/csv"
Invoke-WebRequest -Uri "$base/results/tops?format=csv" -Headers $H -OutFile "tops.csv"