Karino / Still / KPM — Data Integration Specification
苅野・スティル・KPM データ連携仕様
作成日 2026-08-25
最終更新 2026-09-01（連携ギャップ整理の決着15件を反映）
作成者 宮村（AI整理）
ペア文書 苅野スティルKPM_データ連携仕様_20260825.md
位置づけ：正本「苅野スティル連携_要求事項・連携仕様・環境別実装事項_20260810.md」からデータ連携仕様のみを抜粋した整理文書。スティル環境の実装スコープ・未解決論点の詳細は正本を参照。矛盾がある場合は正本側が優先。
1連携の全体像
| 主体 | 役割 |
|---|
| 苅野Zoho | 営業・見積・受注・請求・売上、発注管理（マスタの親）。本番稼働中 |
| スティルZoho | 製造・生産。苅野とKPMの間の仲介地点。未構築（苅野環境のコピーで構築予定） |
| KPM | エキサイター社構築の生産管理システム。REST API（APIキー認証）で受信 |
- 卸売・役務（スケッチ）は苅野環境で完結し、KPM連携の対象外（卸売品の一部連携については現在調整中）
- 製造レイアウトの受注明細は全件スティル経由（2026-08-24 確定。「スティル絡みの場合のみ」という条件付けは採らない）
- 正式切替後は苅野→KPMの直接送信を全停止。納期回答受付APIも例外なくスティル一本化（2026-08-19 決定）
- スティル環境は苅野環境と同一の業務範囲（営業系・預かり品・図面タスク・入出金を含む全業務）を持つ想定。KPM連携部分に限定した縮小環境にはしない（2026-08-25 宮村回答）
1.1 トランザクション連携の一連の流れ（サマリ）
見積明細の作成から出荷・入庫までの流れと、各段階でどの連携が動くか（正式切替後の姿）。詳細は §3〜§6 を参照。
-
1
見積明細の作成 苅野
苅野環境で見積明細・明原価（見積明細）を作成する。この段階ではスティル・KPMへの連携は発生しない。
-
2
納期確認（納期回答API・必要な明細のみ） 苅野 スティル KPM
納期確認依頼を行う見積明細のみ苅野→スティルへ連携し、スティルからKPMへ依頼を送信（POST /delivery-date/requests）。KPMは回答3項目をスティルの見積明細へ書き戻し（Update Records）、スティルが苅野の見積明細へ反映する（§6）。
-
3
受注処理 苅野 → スティル
受注処理完了をトリガーに、受注明細（製造レイアウト）を主体とするツリー（明原価・発注明細／発注書／取引先・仕入先マスタ）を苅野→スティルへ連携する（苅野連携フラグ付与。卸売・役務は対象外。§3）。
-
4
KPMへの受注登録 スティル → KPM
苅野からの受信完了を受けて、スティルからKPMへ受注明細・外注情報等を送信する（§5）。以後、KPM側で製造が進行する。
-
5
出荷 KPM → スティル → 苅野
KPMからスティルへ出荷準備データが届き、スティルで出庫処理と受注明細の数量消込を実行。出庫履歴＋消込結果（2つの箱）を苅野へ戻す。出荷請求などの金流データは苅野側で生成する（§4）。あわせて苅野側では出荷全量完了時にスティル仕入先明原価の入庫管理を自動生成する（§4.3）。
-
6
入庫 KPM → スティル → 苅野
外注の明原価・発注明細に対応する入庫が発生すると、KPMからスティルへ入庫管理データが届き、スティルで入庫処理と明原価の消込を実行。入庫管理データ＋消込結果（2つの箱）を苅野へ戻す。出金記録などの金流データは苅野側で生成する（§4）。
2マスターデータ連携（順方向）
| 送信元 → 先 | 連携データ | トリガー |
|---|
| 苅野 → スティル | 商品マスター（製造レイアウト＋仕入レイアウト（原材料 RM-・副資材 SM-）。卸売品・役務レイアウトは対象外） | マスタ作成時・編集時（KPM変更可能項目の変更） |
| 苅野 → スティル | 材質マスタ（Material_Types。材質コード MT-＋材質名） | マスタ作成時・名称変更時 |
| 苅野 → スティル | 図面管理（KPM連携対象＝商品の KPM_Drawing_Management が指すレコード。図面番号・最新リビジョン・図面URL） | 商品マスタ連携時（依存連携）・リビジョン更新時 |
| スティル → KPM | 商品マスター（苅野連携分＋スティル独自分をまとめて） | スティルでの作成時 または 苅野からの受信時 |
- マスタは苅野＝親・スティル＝子。親で登録→子へ自動連携、子で登録したものは親へ逆流させない。親でのマスタ編集（名称変更等）も子へ伝搬する 2026-09-01 確定
- 連携方式は即時（イベント駆動）。作成・編集時に都度送信する 2026-09-01 確定
- 依存マスタの先行連携：品目マスタは得意先（
customer_id・変更不可）・仕入先（supplier_id）・材質（material_code・変更不可）・図面管理を参照するため、品目連携の処理内で参照先マスタを先に連携して順序保証する 2026-09-01 確定
- 取引先・仕入先マスタは上記の依存連携に加え、受注処理をトリガーにトランザクションに紐づけて連携（受注時の紐づけ再確認）
- 材質は販売管理側では材質コード・材質名のみ保持（詳細はKPM側で付加）
- スティルで必要になったマスタ（商品・材質・原材料・副資材）は苅野で登録・採番してスティルへ連携する（苅野一元登録。最終確認は採番方式とあわせて苅野様へ）。依頼は当面運用フロー（チャット等）で行う 2026-09-01 確定。得意先・仕入先は対象外＝スティル側でも登録可
- 図面ファイル実体は苅野環境が保管し、スティル・KPMはURL参照（実体の環境間コピーは行わない） 2026-09-01 確定
3トランザクション連携（順方向）
受注処理により 見積書・見積明細・明原価（見積明細）→ 受注書・受注明細・明原価/発注明細 へ変換され、明原価は仕入先ごとに発注書へ取りまとめられる。
連携の主体は受注明細。受注処理完了をトリガーに、受注明細を起点とするツリー（明原価・発注明細／発注書／取引先・仕入先マスタ）を連携する。見積明細は納期回答API（納期確認依頼）を利用する場合のみ連携する例外で、見積段階のその他のデータは連携しない（2026-08-25 確定）。
| 送信元 → 先 | 連携データ | 対象外 | トリガー |
|---|
| 苅野 → スティル | 受注明細（製造レイアウト）＝連携の主体／明原価・発注明細／発注書（ステータス含む）／取引先・仕入先マスタ（いずれも苅野連携フラグ付与） | 「卸売」「役務」明細／仕入先＝株式会社スティルの明原価（苅野Zohoに残し §4.3 で消込） 2026-09-01 確定 | 受注処理完了時 |
| 苅野 → スティル | 受注明細の変更差分（KPM変更可能項目に限定：出荷予定日・図面3項目・担当者名・製造指示・外注入出庫予定日・出張検査情報） | KPM変更不可項目（数量・品目等。変更は「キャンセル→再受注処理」の例外フローで対応） | 対象項目の編集時 |
| 苅野 → スティル | 受注明細キャンセル | — | ステータス=キャンセル時 |
| 苅野 → スティル | 原材料・副資材の明原価（入庫予定）：原材料＝重量・単価（円/kg）・入庫予定日／副資材＝数量・入庫予定日 | 発注前のドラフト | 発注済ステータス到達時・以後の変更時 |
| 苅野 → スティル | 見積明細（納期回答API利用時のみの例外連携） | 納期確認依頼を行わない見積明細 | 納期確認依頼時 |
| スティル → KPM | 受注明細／明原価・発注明細／発注書／取引先／仕入先／原材料・副資材入庫予定 | — | 苅野からの受信完了時 |
- スティル絡みの判定は工程3項目方式：商品の
Material（素材）／Heat_Treatment（熱処理）／Processing（加工）を、未選択→0／スティル→1／外注→2 に変換してKPMへ送信
- スティル→KPM送信の起動方式 2026-09-01 確定：苅野からの受信処理がツリー（受注明細＋明原価＋発注書）全件の保存を完了した直後に、受信処理から送信処理を直接起動する（外注数量一致チェックがあるためツリーが揃う前の送信は必ず失敗する）。既存のKPM送信ワークフローはスティル環境では無効化する
- 連携項目はホワイトリスト方式 2026-09-01 確定：連携する項目を明示列挙し、KPM系制御項目（
KPM_Initial_Send_Completed 等）・送信結果項目は送らない（持ち込むとスティル→KPMの初回送信スキップ等の誤作動が起きるため）
- スティル環境では S-007A 相当の除外ロジックは不要：スティル仕入先明原価はそもそも連携されないため、KPMへ送る外注情報に混入し得ない 2026-09-01 確定
4トランザクション連携（逆方向）
| フロー | 送信元 → 先 | データ | トリガー |
|---|
| 出荷 | KPM → スティル | 出荷準備データ | 出荷準備完了時 |
| 出荷 | スティル → 苅野 | 出庫履歴データ＋受注明細消込結果（2つの箱） | 出庫処理完了時 |
| 入庫 | KPM → スティル | 入庫管理データ | 外注明原価・発注明細に対応する入庫発生時 |
| 入庫 | スティル → 苅野 | 入庫管理データ＋明原価・発注明細消込結果（2つの箱） | 入庫処理完了時 |
4.1 KPM→Zoho 戻しの現行仕様（受け口実装済み）
KPMが Zoho CRM API v8 を OAuth 2.0 で直接呼ぶプッシュ方式（正本: 苅野様_KPM→ZohoAPI連携仕様整理.xlsx。項目定義は 2026-08-24 に実環境一致を確認済み）。
| 用途 | API | 宛先モジュール | キー・注意点 |
|---|
| 出荷履歴の作成 | Insert Records | Shipment_History | Sales_Order_Line_Item ルックアップへ事前に渡した受注明細ID（ZohoレコードID）で紐付け。登録先レイアウト「生産連携」を固定 Layout.id で指定（本番 32322000000407862） |
| 入庫管理の作成 | Insert Records | Inbound_Management | payload の項目名は Quotation_Item_Cost だが入る値は明原価・発注明細（Purchase_Order_Line_Item_Cost）のレコードID（名前と実体のねじれに注意）。inbound_quantity（合格）／rejected_quantity（不合格）／Accounting_Confirmed |
| 納期回答の更新 | Update Records | Quote_Items | Latest_Start_Date／Earliest_Shipping_Date／Delivery_Date_Error の3項目を更新 |
- Zoho CRM API経由では Deluge 入力規則が実行されない（出荷数量超過チェック等は効かない）。数量上限判定の責務分界は 未確定
- KPMはリクエストに
trigger キーを送らないため、Zoho側の workflow / approval / blueprint は発火する
4.2 金流データ生成の制御原則
原則：金流データ（出荷請求・入金予定・出金記録等）は商流の当事者環境でのみ生成。物流・在庫系データ（出庫履歴・消込）は処理を行う環境で生成。
| 処理 | スティル環境（苅野連携分） | 苅野環境 | スティル環境（独自受注） |
|---|
| 出庫履歴生成・在庫減算・数量消込 | 実行 | 戻し連携で反映 | 実行 |
| 出荷請求明細・出荷請求・入金予定 | 生成しない | 生成 | 生成 |
| 入庫処理・入庫算消込 | 実行 | 戻し連携で反映 | 実行 |
| 出金記録・出金予定日 | 生成しない | 生成 | 生成 |
- 判定は親明細の「苅野環境からのデータ連携」フラグを参照（経路では苅野連携分と独自分を区別できない）。親明細不明時は金流生成せずエラー記録・通知
- 苅野側の戻し受信は既存WF（出荷管理_統合更新 等）が発火する形で書き込む（
trigger 抑止で書くと請求が不発）。再送時の二重生成を防ぐ冪等性ガード必須
- 合計請求書の発行元は苅野環境とスティル環境で変動させる 2026-08-25 確定。
generateConsolidatedInvoicePDF.dg に直書きの「株式会社 スティル」を環境別の値（組織変数等）へ置換する実装が必要
4.3 苅野に残るスティル仕入先明原価の消込・出金 2026-09-01 確定
スティル仕入先の明原価はスティルへ連携されず（§3）、KPMでは内作工程のため外注入庫データも発生しない。苅野側の消込は以下の方式で行う。
| 項目 | 内容 |
|---|
| 方式 | 親受注明細の出荷が全量完了した時点で、紐づく仕入先＝株式会社スティルの明原価すべてに入庫管理レコードを自動生成して全量入庫済みにする（合格数量＝明原価数量、入庫日＝出荷完了日） |
| 部分出荷 | 消し込まない。受注明細数量と各明原価数量は1対1対応ではなく（工程ごとに数量が異なる・重量ベース等）、按分規則が要件として定義できないため、全量完了時一括が唯一成立する方式 |
| 経理確認済 | FALSE で生成。出金記録の生成は経理が確認済チェックを入れた時点とし、「出荷＝支払確定」の会計判断は自動化しない（他社外注分と同運用）。経理はスティルからの会社間請求と突合してチェックする |
| 実装注意 | 明原価ステータスの直書きは禁止（入庫残数量更新が入庫管理レコードの合格数量合計から再計算するため巻き戻る）。入庫管理レコード生成方式で既存連鎖（統合更新→ステータス更新→発注書ステータス再計算→経理確認済→出金記録）に乗せる |
| 判定・除外 | スティル判定は仕入先レコードIDで行う（名称文字列比較は避ける）。値引き行（Is_Discount_Line）は除外。出荷取消・返品時の巻き戻しは詳細設計で定義 |
| 内作原価 | 苅野連携分の内作原価（材料・工数・重量実績）はKPM側で管理し、Zohoスティル環境に内作明原価は作らない |
5KPM API 連携経路（現行9経路・本番稼働中）
方式：Zoho CRM → KPM の一方向 Outbound、REST/JSON、APIキー認証（x-api-key）。組織変数 kpm_api_base_url／kpm_api_key。
| OpenAPI経路 | 対象モジュール | トリガー | 状態 |
|---|
PUT /api/v1/items/{code} | Products | 初回ボタン、以後編集時WF（製造・仕入れレイアウトのみ。卸売品・役務は対象外） | 正常受理 |
PUT /api/v1/orders/{order_detail_number} | Sales_Order_Line_Item ほか | 作成時1本＋編集時5本のWF | 正常受理 |
DELETE /api/v1/orders/{…} | Sales_Order_Line_Item | ステータス=キャンセル時 | 正常受理 |
POST /api/v1/delivery-date/requests | Quote_Items | ボタン「納期確認依頼」 | 404・成功未確認 |
PUT /api/v1/customers/{id} | Accounts | 作成・編集WF | 正常受理 |
PUT /api/v1/suppliers/{id} | Vendors | 作成・名称変更WF | 正常受理 |
PUT /api/v1/materials/{code} | Material_Types | 作成・名称変更WF | 正常受理 |
PUT /api/v1/raw-material-receipts/{id} | Purchase_Order_Line_Item_Cost | 発注済×原材料 | 本番未検証 |
PUT /api/v1/sub-material-receipts/{id} | Purchase_Order_Line_Item_Cost | 発注済×副資材 | 本番未検証 |
5.1 外部キー
| 対象 | キー | 種別 |
|---|
| 受注 | Sales_Order_Line_Item の ZohoレコードID | ID系 |
| 得意先／仕入先 | Accounts／Vendors の ZohoレコードID | ID系 |
原材料・副資材入庫予定／外注情報 number | Purchase_Order_Line_Item_Cost の ZohoレコードID | ID系 |
| 品目 | 品目コード（PD-／RM-／SM-。Products.id ではない） | コード系 |
| 材質 | 材質コード（MT-） | コード系 |
| 納期回答 | Quote_Items.Name（自動採番） | コード系 |
スティル切替時のキーの扱い：ID系は総入れ替えになる。得意先・仕入先はKPM側で対応表による上書き（合意済み）、トランザクション系はKPM内リセット＋再登録の方針（範囲・時期は未確定、エキサイター社 C-1-a）。コード系は苅野の値のままスティル経由で連携し切替をまたいで連続（2026-08-04 認識合わせ済み）。
5.2 送信仕様の要点
- 検査項目は受注APIで18項目送信・全項目変更不可（visual／dimension／hardness／thickness／coating_thickness／weight／quantity／penetrant／magnetic_particle／ultrasonic／water_pressure／air_pressure／sand_blast／rubber_wheel／contact_face／surface_roughness／residual_magnetism／identification。2026-08-12 本番E2Eで一致確認）
- 外注情報の数的関係：鋳造=最大1件（単体object）、熱処理・加工=複数件可（配列）。
Cost_Category は actual 値で判定（鋳造=材料費／熱処理=加工費／加工=外注費 のねじれあり）
- 数量一致チェック：外注各数量が受注明細の送信数量と一致しなければ送信せず失敗理由を記録
- 再送防止：
KPM_Initial_Send_Completed／KPM（起点更新ガード）／Is_Discount_Line（値引き行除外）。結果記録（KPM_Send_Status 等）は受注系のみ
6納期回答受付APIの一本化（2026-08-19 確定）
納期回答受付API（POST /api/v1/delivery-date/requests）も含め、KPMとのやりとりはスティルZohoに一本化する。
納期確認依頼と回答の往復。回答は同期レスポンスでは返らず、KPM→スティルの Update Records（③）で戻る。苅野への反映はスティル発のリクエスト（④）で行う。
| # | 確定事項 |
|---|
| 1 | 納期回答の戻し先はスティルZohoのみ。苅野への反映はスティル側からのリクエストで実施 |
| 2 | 戻し時にZoho側ワークフローは発火する（KPMは trigger キー未送信）。KPM側改修は不要 |
| 3 | estimate_detail_number は Quote_Items.Name（自動採番）を使用 |
| 4 | 回答3項目は同期レスポンスではなく KPM→Zoho の Update Records で返る |
- 前提として苅野→スティルの見積明細連携が必要。対象は納期確認依頼を行う明細のみ（2026-08-25 宮村回答）。対応キー設計は 未設計
- KPMの404（成功ケース未確認）は未解決（エキサイター社 A-3）
7暫定処理と正式切替
- S-007A（暫定スティル除外）：現行の直接送信で、商品の工程が「スティル」かつ明原価の仕入先が「株式会社スティル」の明原価をKPMへ送る外注情報から除外。スティル環境では除外の意味が逆転するため移植せず削除
- 切替手順：正式経路の実データ検証 → 苅野→KPM直接送信の停止（納期確認依頼ボタン含む）→ S-007A 無効化・削除 → 仕様書更新・Issue #207 クローズ
- KPM→Zoho戻しの付け替え（接続先組織・OAuth・出荷履歴 Layout ID）がKPM側作業として必要（エキサイター社 C-2）
8未確定事項（データ連携仕様に関わるもの）
| # | 事項 | 確認先 |
|---|
| 1 | 混在受注の 422 invalid_combination／外注なし受注の 500 の解消 | エキサイター社 A-1・A-2 |
| 2 | トランザクション系キーのリセット＋再登録の範囲・時期・KPM側実績の扱い | エキサイター社 C-1-a |
| 3 | 対応キー設計：見積明細（納期回答API用途・両環境に同番号が並ぶ）に加え、受注明細・明原価等の連携対象トランザクション全体での苅野ID⇔スティルID対応保持（変更差分・キャンセル・戻し連携の前提） | 社内 |
| 4 | 出荷・入庫の数量上限判定の責務分界（入力規則がAPI経由で効かない） | エキサイター社・苅野様 |
| 5 | 出荷フローの詳細仕様（項目・形式・戻しタイミング・エラー再処理） | エキサイター社・苅野様 |
| 6 | 品目・材質コードの採番方式（U-17）。苅野一元登録が妥当との社内チェック済み（2026-09-01）・最終確認のみ | 苅野様 |
| 7 | 原材料・副資材入庫予定の本番検証の段取り（KPM側に取消経路なし） | エキサイター社 A-5 |
| 8 | 数量・品目等KPM変更不可項目の変更時の「キャンセル→再受注」例外フローの定義 | 社内 |
| 9 | 図面URL（苅野環境参照）のアクセス権の現状確認 | 社内 |
| 10 | 切替前（暫定経路期間）に溜まった既存スティル仕入先明原価の滞留分の清算方針 | 社内・苅野様（切替タスク） |
| 11 | §4.3 確定仕様（経理確認済チェック運用＝会社間請求との突合）の運用共有 | 苅野様・スティル経理 |
| 12 | 出荷完了後の出荷取消・返品時の巻き戻し（§4.3 で自動生成した入庫管理の取消）の詳細設計 | 社内 |