外部連携（WebAPI）

AI Agent チートシート

コードを人が書くより、エージェントに「所在と使い方」を渡して呼び出すケース向けです。安全に使うための短い契約です。長いので折りたたんでいます。コピーしてプロンプトやルールに貼れます。

# DELTA WebAPI — Agent cheat sheet (safe use)

Base (production): https://delta.956.jp/api/v1
Auth: Authorization: Bearer $DELTA_WEBAPI_KEY
  Read the key ONLY from environment variable DELTA_WEBAPI_KEY (or the host's secret store that injects that name).
  Never ask the user to paste the key into chat. Never print, log, or commit the key value.
Content-Type: application/json
Times: ISO8601 with offset (e.g. 2026-08-24T09:00:00+09:00)
Ids: prefer workplace/work/worker/sku *codes* from DELTA masters; responses may include public_id (UUID).

## Hard rules (do not violate)
- Call ONLY DELTA host endpoints under /api/v1 (not the partner MES/BI host).
- Scope is the organization of the API key. Never attempt cross-tenant access.
- Do not invent paths, fields, or event names. If unsure, stop and ask a human.
- Writes: always send Idempotency-Key and a stable external_id when available.
- defect_quantity must be <= actual_quantity.
- pause creates NonProduction kind=other; resume closes it; humans may reclassify later.
- Do NOT use API for: browser login, kiosk/staff QR sessions, daily-report planned stops as job pause, changing OEE formulas.
- Prefer least privilege: read-only key for dashboards; write key only when registering records/instructions.
- If DELTA_WEBAPI_KEY is unset, stop and tell the human how to set it (do not invent a key).
- Never echo the key in curl -v, debug dumps, screenshots, or commit messages.

## Read (取得系)
GET /workplaces/{code_or_id}/oee/live?window=shift_today|day|last_1h
GET /oee?from=YYYY-MM-DD&to=YYYY-MM-DD&group_by=workplace|work_master|worker
GET /non_productions?from=ISO&to=ISO&status=open|closed|all
GET /workplaces/{code_or_id}/non_productions?from=ISO&to=ISO&status=open|closed|all

## Write (登録系)
POST /work_record_items/batch
  body.items[]: external_id, workplace_code, worker_code, work_master_code, sku_code?,
    planned_quantity, actual_quantity, defect_quantity, started_at, ended_at,
    standard_cycle_time_sec?, non_productions[]?, instruction_no?
  options: on_missing_master=error, wrap_up=true|false

POST /work_instructions
  body: instruction_no, sku_code, work_master_code, workplace_code, planned_quantity, due_date?, external_id?

POST /work_instructions/{id}/events
  body.event: start|pause|resume|qty_update|stop|wrap_up
  body: at?, worker_code?, workplace_code?, actual_quantity?, defect_quantity?, note?, non_productions[]?
  Typical flow: start → (qty_update|pause/resume)* → stop → wrap_up

## When blocked
- Missing master codes → create masters in DELTA admin first (or report error; do not invent).
- Duplicate start on same instruction → conflict; do not retry start blindly.
- Endpoint not listed above → treat as unavailable; do not guess.

Status: read and write endpoints published. Prefer OpenAPI when available.

API キーはどこに置くか（具体）

チートシートには使い方だけを入れ、キー文字列そのものは入れません。値は次の名前の環境変数に置きます（ハイフン不可。アンダースコア）。

DELTA_WEBAPI_KEY

• 自分の Mac でエージェント／curl を動かす
  ターミナルで一度だけ: export DELTA_WEBAPI_KEY='（管理画面で発行したキー）'
  毎回使うなら ~/.zshrc に同じ行を書くか、プロジェクト直下の git 管理外ファイル（例: .env.local）に書き、set -a; source .env.local; set +a してから Cursor／シェルを使う。.env* はコミットしない。
• Cursor の Cloud Agent
  クラウド実行用の環境変数／シークレットに、同じく名前 DELTA_WEBAPI_KEY で登録する（ローカルの ~/.zshrc は渡りません）。
• 他社の MES／BI／サーバ
  その製品のシークレット機能（環境変数、Vault、クラウドの Secrets Manager、Heroku Config Vars など）に同じ名前で入れる。

エージェントへの指示は「DELTA_WEBAPI_KEY を読んで Authorization: Bearer … に使う。値をチャット・ログ・コミットに出さない。未設定なら止めて人に設定を頼む」です。キーをチャットに貼り付けないでください。

やりたいこと一覧

やりたいことを選び、下の節で呼び出し方まで確認してください。取得系・登録系とも提供中です。

接続の基本

どの「やりたいこと」でも共通です。先にここを決めてから、個別の呼び出しに進みます。

接続先

呼び先はDELTA 側のホストです（連携先の MES／BI などのホストではありません）。本番:

https://delta.956.jp/api/v1

検証環境など別ホストで DELTA を動かしている場合は、その DELTA のホストに読み替えてください。

認証

管理者が発行した API キーを、すべてのリクエストに付けます。キーは組織に紐づき、他組織のデータには届きません。発行・失効は管理画面の APIキー から行います。

Authorization: Bearer dk_live_xxxxx

1. 管理画面の APIキー でキーを発行し、権限（read:oee / write:records など）を付ける
2. 外部システム側の設定にキーを保存する（ソースコードに直書きしない）
3. 漏洩・退職・システム廃止のときはキーを失効する

書込みの再送

実績や指示の登録では、同じ内容を二度送っても二重登録しないよう、Idempotency-Key（推奨）と、外部側の行 ID（external_id）を使います。

Idempotency-Key: mes-batch-20260824-001

時刻・コード

• 時刻は ISO8601（例: 2026-08-24T09:00:00+09:00）
• 現場・作業・作業員・SKU は、管理画面で登録したコードで指定できる
• 応答では public_id（UUID）も返す想定（以降の参照に使える）

いまの現場 OEE を見る 提供中

こんなときに … 行灯・大型モニタ・BI に「この現場のいま」を出したい。

呼び出し

GET /api/v1/workplaces/{現場のIDまたはコード}/oee/live
    ?window=shift_today

window の例: shift_today（今日のシフト） / day（当日） / last_1h（直近1時間）

手順

1. 対象現場のコード（または ID）を決める
2. 上記 URL を定期的に取得する（例: 10〜30 秒ごと）
3. 返ってきた OEE・可動・性能・品質と、計測中ジョブの一覧を画面に映す

返ってくるもの（イメージ）

• 現場の集計スコア（OEE / A / P / Q）と数量・時間の合計
• いま計測中の作業（作業名・SKU・作業員・ライブ OEE）
• 比較用の目標値（設定している場合）
• 計算できないときは、無理に 0 にせず「計算不可」と分かるフラグ

数字の意味は OEE 入門 と同じです。

期間の OEE を取る 提供中

こんなときに … 「先週の現場別」「今月の作業員別」をレポートや他 DB に取り込みたい。

呼び出し

GET /api/v1/oee
    ?from=2026-08-01
    &to=2026-08-23
    &group_by=workplace

group_by: workplace（現場） / work_master（作業） / worker（作業員）

絞り込み（任意）: workplace_id / work_master_id / worker_id / org_unit_id / capture_mode

手順

1. 期間（from / to）と、まとめ方（group_by）を決める
2. 必要なら現場・作業・作業員で絞り込む
3. 返ってきた行（キー＋スコア＋件数・数量）を表やグラフにする

管理画面の OEE／作業員レポートと同じ集計を、外部から読むイメージです。

停止を一括で取る 提供中

こんなときに … 他システム側にダッシュボードがあり、「いま／今日、DELTA で何が止まっているか」を一覧で取り込みたい。組織全体でも、特定現場だけでも取れます。

呼び出し

# 組織全体（キーの組織スコープ）
GET /api/v1/non_productions
    ?from=2026-08-24T00:00:00+09:00
    &to=2026-08-24T23:59:59+09:00
    &status=open|closed|all

# 所定の現場だけ
GET /api/v1/workplaces/{現場のコードまたはID}/non_productions
    ?from=…
    &to=…
    &status=open

status の例: open（継続中の停止） / closed（終了済み） / all（両方）

手順

1. ダッシュボードの更新周期に合わせて、上記を定期取得する
2. 全体監視なら組織向け、ライン別モニタなら現場向け URL を使う
3. 返ってきた各停止の理由・開始／終了・分数・紐づく現場／作業／作業員を表やアラートに載せる

返ってくるもの（イメージ）

• 非稼働の一覧（理由 kind、開始・終了、duration、メモ）
• 紐づき（現場・作業・作業員・作業記録）
• ページング（件数が多い日向け）

主に作業に紐づく非稼働（可動 A に効くロス）です。日報の予定外停止との違いは 作業員端末の説明 を参照。

実績をまとめて登録する 提供中

こんなときに … MES や別システムで確定した「いつ・誰が・何を・何個」を、DELTA の作業実績に載せたい。

呼び出し

POST /api/v1/work_record_items/batch
Authorization: Bearer dk_live_xxxxx
Idempotency-Key: mes-20260824-001
Content-Type: application/json

{
  "items": [
    {
      "external_id": "MES-ROW-1001",
      "workplace_code": "ASM",
      "worker_code": "S-01",
      "work_master_code": "W-01",
      "sku_code": "SKU-001",
      "planned_quantity": 20,
      "actual_quantity": 18,
      "defect_quantity": 1,
      "started_at": "2026-08-24T09:00:00+09:00",
      "ended_at": "2026-08-24T09:45:00+09:00",
      "standard_cycle_time_sec": 120,
      "non_productions": [
        { "kind": "changeover", "duration_sec": 600, "note": "段取" }
      ]
    }
  ],
  "options": { "on_missing_master": "error", "wrap_up": true }
}

手順

1. DELTA に現場・作業・作業員・SKU・標準 CT があることを確認する
2. 1 行ごとに external_id を付けて送る（再送対策）
3. 応答の行ごとの成功／失敗を見て、失敗行だけ直して再送する
4. 管理画面の作業実績で、取り込めたか確認する

よくある失敗

• コードがマスタに無い → 先に管理画面で登録
• 不良数が生産数より多い → 画面と同じく拒否
• 同じ external_id の再送 → 新規作成せず、既存を返す

指示を登録して実行する 提供中

こんなときに … 生産スケジューラで作った指示を DELTA に渡し、開始〜終了まで同じ指示に紐づけて追いたい。現場では QR でも読ませたい。

1. 指示を登録する

POST /api/v1/work_instructions

{
  "instruction_no": "WI-2026-0042",
  "sku_code": "SKU-001",
  "work_master_code": "W-01",
  "workplace_code": "ASM",
  "planned_quantity": 100,
  "due_date": "2026-08-25",
  "external_id": "MES-WO-7788"
}

応答には指示の ID と、現場端末向け DELTA WI JSON（作業指示 QR と同じ形）が付きます。仕様の背景は 管理者向け・作業指示書 QR を参照。

2. 実行イベントを送る

POST /api/v1/work_instructions/{id}/events
Idempotency-Key: wi-42-start-1

{
  "event": "start",
  "at": "2026-08-24T10:00:00+09:00",
  "worker_code": "S-01",
  "workplace_code": "ASM"
}

手順（典型）

1. 指示を登録する → 返ってきた ID を保存する
2. start → 必要なら qty_update / pause・resume
3. stop → wrap_up（最終の生産数・不良・非稼働）
4. 現場で QR からも始める場合は、二重 start にならないよう運用を決める（衝突時はエラー）

一時停止を記録する 提供中

こんなときに … 設備やラインが止まったことを可動（A）に反映したい。理由の細かい分類は後で直したい。

呼び出し

# 止まる
POST /api/v1/work_instructions/{id}/events
{ "event": "pause", "at": "2026-08-24T10:20:00+09:00", "note": "api:pause" }

# 再開する
POST /api/v1/work_instructions/{id}/events
{ "event": "resume", "at": "2026-08-24T10:35:00+09:00" }

DELTA 側の動き

1. pause … その作業に紐づく非稼働を自動作成。理由は当面「その他」
2. resume … その非稼働の終了時刻・分数を確定
3. あとから管理画面・現場端末・API で、段取・材料待ち・故障など正しい理由に置き換え

日報の予定外停止（会議・教育など、特定作業に紐づけない枠）とは別です。違いは 作業員端末の説明 を参照。