Karino / Still / KPM — Data Integration Specification
苅野・スティル・KPM データ連携仕様
作成日 2026-08-25
最終更新 2026-08-25（宮村判断3件を反映）
作成者 宮村（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）。
-
6
入庫 KPM → スティル → 苅野
外注の明原価・発注明細に対応する入庫が発生すると、KPMからスティルへ入庫管理データが届き、スティルで入庫処理と明原価の消込を実行。入庫管理データ＋消込結果（2つの箱）を苅野へ戻す。出金記録などの金流データは苅野側で生成する（§4）。
2マスターデータ連携（順方向）
| 送信元 → 先 | 連携データ | トリガー |
|---|
| 苅野 → スティル | 商品マスター | マスタ作成時 |
| スティル → KPM | 商品マスター（苅野連携分＋スティル独自分をまとめて） | スティルでの作成時 または 苅野からの受信時 |
- マスタは苅野＝親・スティル＝子。親で登録→子へ自動連携、子で登録したものは親へ逆流させない
- 取引先・仕入先マスタは受注処理をトリガーにトランザクションに紐づけて連携（常時同期ではない）
- 材質は販売管理側では材質コード・材質名のみ保持（詳細はKPM側で付加）
3トランザクション連携（順方向）
受注処理により 見積書・見積明細・明原価（見積明細）→ 受注書・受注明細・明原価/発注明細 へ変換され、明原価は仕入先ごとに発注書へ取りまとめられる。
連携の主体は受注明細。受注処理完了をトリガーに、受注明細を起点とするツリー（明原価・発注明細／発注書／取引先・仕入先マスタ）を連携する。見積明細は納期回答API（納期確認依頼）を利用する場合のみ連携する例外で、見積段階のその他のデータは連携しない（2026-08-25 確定）。
| 送信元 → 先 | 連携データ | 対象外 | トリガー |
|---|
| 苅野 → スティル | 受注明細（製造レイアウト）＝連携の主体／明原価・発注明細／発注書（ステータス含む）／取引先・仕入先マスタ（いずれも苅野連携フラグ付与） | 「卸売」「役務」明細 | 受注処理完了時 |
| 苅野 → スティル | 見積明細（納期回答API利用時のみの例外連携） | 納期確認依頼を行わない見積明細 | 納期確認依頼時 |
| スティル → KPM | 受注明細／明原価・発注明細／発注書／取引先／仕入先 | — | 苅野からの受信完了時 |
- スティル絡みの判定は工程3項目方式：商品の
Material（素材）／Heat_Treatment（熱処理）／Processing（加工）を、未選択→0／スティル→1／外注→2 に変換してKPMへ送信
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 に直書きの「株式会社 スティル」を環境別の値（組織変数等）へ置換する実装が必要
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用途のみ・2026-08-25 決定）の対応キー設計（見積明細番号は両環境に同番号が並ぶ） | 社内 |
| 4 | 出荷・入庫の数量上限判定の責務分界（入力規則がAPI経由で効かない） | エキサイター社・苅野様 |
| 5 | 出荷フローの詳細仕様（項目・形式・戻しタイミング・エラー再処理） | エキサイター社・苅野様 |
| 6 | 品目・材質コードの採番方式（苅野一元登録の可否、U-17） | 苅野様 |
| 7 | 原材料・副資材入庫予定の本番検証の段取り（KPM側に取消経路なし） | エキサイター社 A-5 |