【Jienie2.0】カタログモール外部連携仕様（ver 1.36）

改訂履歴
1. システム全体概要
2. 商品情報の連携
- 2-1. カタログサイトでの商品検索（パンチアウト連携）
  - 2-1-1. 概要
  - 2-1-2. 前提条件
  - 2-1-3. CheckIn（チェックイン）
    - 処理シーケンス
    - データフォーマット
    - PunchOutSetUpRequest
    - PunchOutSetUpResponse
  - 2-1-4. CheckOut（チェックアウト）
    - 処理シーケンス
    - データフォーマット
    - PunchOutOrderMessage
- 2-2. バックグラウンドキーワード検索（API連携）
  - 概要
  - 前提条件
  - 処理シーケンス
  - API一覧
  - KeywordSearch（外部カタログ検索）
  - KeywordItemAdd（商品情報取得）
- 2-3. バックグラウンド商品検索（API連携）
  - 概要
  - 前提条件
  - 処理シーケンス
  - API一覧
  - ItemSearch（商品情報検索）
- 2-4. 内部商品化（API連携）
  - 概要
  - GetRegistItem（内部化カタログ登録件数取得）
  - RegistItemAdd（商品情報登録）
- 2-5. 内部商品化（SFTP）
  - 処理概要
  - 前提条件
  - ディレクトリ構成
  - 商品情報CSV仕様
  - CHKファイル仕様
  - エラーファイル仕様
3. EDI連携
- 3-1. オーダー（発注）情報の連携
  - 概要
  - 前提条件
  - 処理シーケンス
  - API一覧
  - OrderInput（発注情報登録）
- 3-2. 納期回答情報の連携
  - 概要
  - 前提条件
  - 処理シーケンス
  - API一覧
  - DeliverInput（納期回答情報登録）
- 3-3. 出荷情報の連携
  - 概要
  - 前提条件
  - 処理シーケンス
  - API一覧
  - ShipmentInput（出荷情報登録）
4. 共通コード・マスタ定義
- 4-1. 単位コード
- 4-2. 別途費用の定義
5. 補足資料
- 5-1. バックグラウンド検索
- 5-2. お客様ご利用画面とのマッピング
- 5-3. 納期回答・出荷情報の処理フロー
- 5-4. 別途費用のAPI
6. API・データサンプル
- 6-1. PunchOutSetUpRequest
- 6-2. PunchOutSetUpResponse
- 6-3. PunchOutOrderMessage
- 6-4. KeywordSearch
- 6-5. KeywordItemAdd
- 6-6. ItemSearch
- 6-7. OrderInput
- 6-8. DeliverInput
- 6-9. ShipmentInput
- 6-10. GetRegistItem
- 6-11. RegistItemAdd
7. ファイル連携仕様
- 7-1. CHKファイル
- 7-2. 商品情報SFTP形式CSV
- 7-3. 商品情報SFTP形式CSV（TO-BE）
8. 用語集

改訂履歴

本書の改訂履歴は以下のとおりです。

更新日	更新者	Version	更新内容	備考
15/11/04	関	1.00	新規作成	-
15/11/09	関	1.01	`PunchOutSetUpRequest`の最上位組織コードの説明を変更	-
15/11/10	関	1.02	「地域」表記を「拠点」表記へ変更／項番間違いの修正（3-1-4等）	-
15/12/01	関	1.03	ページ番号を追加、体裁の変更	-
15/12/04	関	1.04	物理名の記載およびエラー値を追加	-
15/12/05	関	1.05	データ型を追記。グリーン品規格の指定方法を追記	-
15/12/09	関	1.06	バックグラウンド検索の条件にグリーン品を追記。記載内容不備の修正	本文中、赤字で修正
15/12/22	関	1.07	バックグラウンド検索にてカテゴリをフリーワードにセットして検索を行う旨の記述を追加	本文中、赤字で修正
16/01/05	関	1.08	誤字の修正。cXMLのサンプルを追加	ワークシートを追加
16/01/07	関	1.09	チェックアウト項目に予備項目を追加。cXMLのサンプル記載ミスの修正	本文中、赤字で修正
16/01/07	関	1.10	`PunchOutSetUpRequest`／`PunchOutSetUpResponse`の記載ミスを修正。分類が4階層以上ある場合の設定方法を追記	-
16/01/12	関	1.11	出荷連携の項目（出荷管理番号）を追記	本文中、赤字で修正
16/01/25	関	1.12	発注・納期回答・出荷APIのサンプルを追加。拡張項目を追記	ワークシートを追加／本文中、赤字で修正
16/03/02	関	1.13	`KeywordSearch`、`KeywordItemAdd`のサンプル電文を追加	ワークシートを追加
16/03/18	関	1.14	サンプル電文への注意事項を追記	-
16/05/18	関	1.15	JSON APIの前提条件に注意事項を追記。バックグラウンド検索の補足資料を追加	ワークシートを追加
16/05/31	関	1.16	誤字修正。マスタデータ提供のご依頼を追加	本文中、赤字で修正・追記
16/07/06	関	1.17	システム全体概要に受注照会（Web-EDI）を追記。`ItemSearch`にて商品情報が存在しない場合のエラーコードを追加	本文中に追記
16/10/15	関	1.18	画面と連携項目のマッピング説明を追加	ワークシートを追加
16/10/18	関	1.19	`UserAgent`の記載を変更	本文中、赤字で追記
17/04/15	桶谷	1.20	ユーザ特定パラメータを追加	-
17/06/06	桶谷	1.21	パラメータをいくつか追加（設定により出力）	本文中、赤字で追記
18/09/26	桶谷	1.22	実態に合わせたコメントを追加。組織変更に伴う組織名の変更	ワークシートを追加／表紙
19/01/22	桶谷	1.23	消費税10%増税対応	本文
20/07/01	秋元	1.24	Jienie用資料として内容を編集	-
20/11/17	NAVAA	1.25	サプライヤに連携するAPI（`PunchOut`、`KeywordSearch`、`ItemSearch`）に`SITE_KBN`項目を追加	本文
20/12/10	NAVAA	1.26	`OrderInput`（受注登録API）に`DeliverInputURL`、`ShipmentInputURL`を追加	本文
21/01/28	NAVAA	1.27	サンプル_OrderInputを編集	-
21/03/25	NAVAA	1.28	本文「2-4. 内部商品化（API連携）」を追加	-
21/04/02	NAVAA	1.28	サンプル_KeywordSearchを追加	-
21/04/02	NAVAA	1.29	サンプル_PunchOutSetUpRequestを追加。サンプル_GetRegistItemを追加	-
21/04/02	NAVAA	1.30	サンプル_RegistItemAddを追加。「1. システム全体概要」にSFTPによる内部化を追加	-
22/04/13	NAVAA	1.31	「2-5. 内部商品化（SFTP）」を追加。3-2-4-1. `DeliverInput`（納期回答情報登録）の予備項目1：別途費用の場合、別途費用を追加する旨を記載	-
22/04/13	NAVAA	1.31	補足）別途費用のAPIを追加	-
22/04/13	NAVAA	1.31	予備項目4（注文コード）を補足	-
22/06/09	NAVAA	1.31	補足）別途費用のAPIのレスポンス項目が減る場合を追記。本文 3-1-4-1. `OrderInput`（発注情報登録）予備項目19：送料区分の説明を追記	-
22/06/13	AOKI	1.31	サンプル_ItemSearchを追加	-
22/06/30	NAVAA	1.31	本文の商品情報SFTP形式CSVの桁数を追加。補足）別途費用のAPIに`orderQuantity`を追加	-
22/06/30	NAVAA	1.31	`OrderInput`のサプライヤ品番の説明を追加（サプライヤ品番：`[ProductCd]`）	-
22/06/30	NAVAA	1.31	`ShipmentInput`の`optionalItem1`に納品日の説明を追加	-
22/07/11	NAVAA	1.31	「2-5. 内部商品化（SFTP）」にディレクトリ構成を追加	-
22/09/20	NAVAA	1.31	商品情報SFTP形式CSVを現在のフォーマットに合わせて変更	-
23/03/01	NAVAA	1.31	`DeliverInput`に`shipmentDetailNumber`（出荷明細番号）項目を追加	-
25/07/15	NAVAA	1.32	`productURL`項目を追加（①`PunchOutOrderMessage` ②`KeywordItemAdd` ③`ItemSearch`）	-
25/09/19	NAVAA	1.33	`casNo`項目を追加（①`PunchOutOrderMessage` ②`KeywordItemAdd` ③`ItemSearch`）。メーカー名称・メーカー型番項目を追加（①`ItemSearch`）	試薬横断検索
25/09/30	MORIYA	1.34	`KeywordSearch`（外部カタログ検索）の項目追加・更新。［追加］①`freeword1`（検索キーワード1）②`logicalExpression1`（論理演算1）③`freeword2`（検索キーワード2）／［更新］①`freeword`：必須→任意　②`makerModelID`：必須→任意	試薬横断検索
25/10/09	Sugihashi	1.35	試薬検索においてサプライヤ様側サイトの検索状況を確認した結果、キーワードの「OR」条件検索ができないことが判明したため項目をシンプルな構成に変更。`KeywordSearch`（外部カタログ検索）の仕様変更：項目削除（①`freeword1` ②`logicalExpression1` ③`freeword2`）	-
25/12/17	Sugihashi	1.36	「UNSPSCコード」項目を追加。対象：2-1-4-2-1. `PunchOutOrderMessage`（`name=optionalItem6`）／2-2-4-2. `KeywordItemAdd`（商品情報取得）リクエスト（`optionalItem6`）／2-3-4-1. `ItemSearch`（商品情報検索）レスポンス（`optionalItem6`）	-

1. システム全体概要

1.1 概要

本システムは、ジーニーラボ株式会社が提供する購買プラットフォーム J2システム（ジーニー2.0） と、お取引企業様が利用するカタログサイト・販売管理システムを連携する仕組みです。

J2システム（ジーニー2.0）は、購買システム と カタログモール の2つのサブシステムで構成されています。購買システムでは購入依頼・承認・発注などの購買業務を管理し、カタログモールでは外部カタログおよび内部カタログの商品検索・選択・発注連携を担います。

主な連携領域は、以下の3つです。

商品（検索）情報の連携：　商品情報の検索・取得。お取引企業様の商品を購入依頼者がどのように見られるようにするか
EDI連携：　EDI連携・発注フロー。発注情報、納期回答、出荷情報がどのようにやり取りされるか
内部カタログ化：　検索の都度APIを呼び出さずに、お取引企業様の商品をあらかじめJ2内に「登録済み」の状態にしておく別の方式

全体として、商品検索から商品選択、発注、納期回答、出荷、検収、支払予定情報までの購買業務プロセスを、カタログモールを中心として各システム間で連携します。

1.2 システム全体構成

flowchart LR
    Buyer(["バイヤ / 購入依頼者"])

    subgraph J2["J2システム（ジーニー2.0）"]
        direction TB
        Purchase["購買システム"]
        Mall["カタログモール"]
        Purchase <-->|"パンチアウト連携"| Mall
    end

    subgraph EXT["外部システム（お取引企業様）"]
        direction TB
        CatSrv["カタログサーバ<br/>（商品検索・商品マスタ）"]
        Sales["販売管理システム<br/>（受発注）"]
    end

    Buyer --> Purchase

    %% ①〜④：商品（検索）情報の連携
    Mall -->|"① パンチアウト検索<br/>CheckIn / CheckOut（cXML）"| CatSrv
    Mall -->|"② キーワード検索（API）"| CatSrv
    Mall -->|"③ 商品検索（API・サプライヤ品番指定）"| CatSrv
    CatSrv -->|"④ 内部商品化（API / SFTP・CSV一括）"| Mall

    %% ⑤〜⑦：EDI連携（受発注・納期・出荷）
    Mall -->|"⑤ オーダー／発注（API）"| Sales
    Sales -->|"⑥ 納期回答（API）"| Mall
    Sales -->|"⑦ 出荷情報（API）"| Mall

1-1. 商品（検索）情報の連携

概要

商品情報および商品検索情報については、カタログモールとお取引企業様のカタログシステム間で連携を行います。

商品検索方式として、以下の2種類を実装します。

連携方式	概要
パンチアウト方式	カタログモールからお取引企業様のカタログ検索サイトへ遷移し、外部サイト上で商品を検索・選択する
バックグラウンド検索API方式	カタログモールの検索サイトから、バックグラウンドでお取引企業様の商品検索APIを呼び出す

また、CheckOut後、またはバックグラウンド検索後にカタログモールの「お気に入り」へ登録された商品については、次回カートへ投入する際に、バックグラウンドで最新の商品情報を取得します。

各連携方式の詳細仕様については、「2. 商品情報の連携」に記載します。

商品検索の基本イメージ

flowchart LR

    USER["購入依頼者"]

    subgraph J2SYS["J2システム（ジーニーラボ株式会社）"]
        subgraph PURCHASE["購買システム（J2）"]
            MENU["カタログ購買"]
            SEARCH["カタログ検索"]
            RESULT["商品検索結果一覧"]
            FAVORITE["お気に入り"]
            CART["カート"]
            REQUEST["発注申請"]
        end
        subgraph MALL["カタログモール（J2）"]
            CROSS["商品横断検索"]
            INTERNAL["内部カタログ検索"]
            EXTERNAL["外部カタログ検索"]
            MASTER["商品マスタ"]
        end
    end

    subgraph CATALOG["取引先カタログサイト（お取引企業様）"]
        SITE_SEARCH["商品検索"]
        SITE_CART["商品選択"]
    end

    USER --> MENU
    MENU --> SEARCH
    SEARCH --> CROSS

    CROSS --> INTERNAL
    CROSS --> EXTERNAL

    INTERNAL --> MASTER

    EXTERNAL -->|"CheckIn"| SITE_SEARCH
    SITE_SEARCH --> SITE_CART
    SITE_CART -->|"CheckOut"| CART

    EXTERNAL --> RESULT
    INTERNAL --> RESULT

    RESULT --> FAVORITE
    RESULT --> CART

    FAVORITE -->|"最新商品情報を確認"| EXTERNAL

    CART --> REQUEST

    style PURCHASE fill:#eef5ff,stroke:#1e88e5,stroke-width:1px
    style MALL fill:#f7eefc,stroke:#8e24aa,stroke-width:1px
    style CATALOG fill:#eafaf0,stroke:#43a047,stroke-width:1px

    classDef user fill:#eceff1,stroke:#546e7a,stroke-width:1px,color:#263238
    classDef purchase fill:#e3f2fd,stroke:#1e88e5,stroke-width:1px,color:#0d47a1
    classDef mall fill:#f3e5f5,stroke:#8e24aa,stroke-width:1px,color:#4a148c
    classDef catalog fill:#e8f5e9,stroke:#43a047,stroke-width:1px,color:#1b5e20

    class USER user
    class MENU,SEARCH,RESULT,FAVORITE,CART,REQUEST purchase
    class CROSS,INTERNAL,EXTERNAL,MASTER mall
    class SITE_SEARCH,SITE_CART catalog

    linkStyle 6 stroke:#e65100,stroke-width:2px
    linkStyle 8 stroke:#e65100,stroke-width:2px
    linkStyle 13 stroke:#00838f,stroke-width:2px,stroke-dasharray: 4 3

お気に入り商品の最新情報確認

カタログモールのお気に入りに登録されている商品をカートに入れる際には、お取引企業様の商品検索APIを呼び出します。

検索には、サプライヤ品番等の商品識別情報を使用します。

APIの実行結果をもとに、お気に入りに登録されている商品情報と最新の商品情報を比較します。

処理パターン

商品状態	処理内容
商品情報に変更なし	そのままカートに追加する
単価差あり	利用ユーザにメッセージを表示し、最新単価でカートに追加する
商品検索不可・廃番	利用ユーザにメッセージを表示し、お気に入りから商品を削除する
廃番かつ後継品あり	後継品が存在する旨を表示し、お気に入り商品の入れ替えを利用ユーザに選択してもらう

flowchart TD

    A["お気に入り商品"]
    B["「カートに入れる」"]
    C["商品検索API呼び出し"]
    D{"商品あり？"}

    E{"単価差あり？"}
    F["そのままカート追加"]
    G["価格変更メッセージ"]
    H["最新単価でカート追加"]

    I{"後継品あり？"}
    J["廃番メッセージ"]
    K["お気に入りから削除"]
    L["後継品を案内"]
    M{"入れ替える？"}
    N["後継品へ自動入れ替え"]

    A --> B
    B --> C
    C --> D

    D -->|Yes| E
    E -->|No| F
    E -->|Yes| G
    G --> H

    D -->|No| I
    I -->|No| J
    J --> K

    I -->|Yes| L
    L --> M
    M -->|Yes| N
    M -->|No| K

    classDef flow fill:#e8eaf6,stroke:#3f51b5,stroke-width:1px,color:#1a237e
    classDef decision fill:#fff3e0,stroke:#fb8c00,stroke-width:1px,color:#e65100
    classDef success fill:#e8f5e9,stroke:#43a047,stroke-width:1px,color:#1b5e20
    classDef warning fill:#fffde7,stroke:#fbc02d,stroke-width:1px,color:#f57f17
    classDef danger fill:#ffebee,stroke:#e53935,stroke-width:1px,color:#b71c1c
    classDef info fill:#e3f2fd,stroke:#1e88e5,stroke-width:1px,color:#0d47a1

    class A,B,C flow
    class D,E,I,M decision
    class F success
    class G,H warning
    class J,K danger
    class L,N info

1-2. EDI連携

概要

カタログモールとお取引企業様の販売管理システムとの間で、購買・受発注業務に必要な情報をAPI方式で連携します。

主な連携対象は、以下の3種類です。

発注情報
納期回答情報
出荷情報

連携内容

カタログモールからお取引企業様のシステムへ、オーダー（発注）情報をAPI方式で連携します。
お取引企業様のシステムからカタログモールへ、納期回答情報をAPI方式で連携します。
お取引企業様のシステムからカタログモールへ、出荷情報をAPI方式で連携します。

納期回答には、「受注」「受注辞退」「サプライヤ納品予定日」等の情報を含みます。

EDI連携の基本フロー

sequenceDiagram
    participant Purchase as 購買システム（J2）
    participant Mall as カタログモール（J2）
    participant Sales as 販売管理システム（お取引企業様）

    Note over Purchase,Mall: ＜J2システム（ジーニーラボ株式会社）＞

    rect rgb(235, 245, 255)
        Note over Purchase,Sales: ① 発注情報
        Purchase->>Mall: 発注情報連携
        Mall->>Sales: OrderInput（発注登録API）
        Sales-->>Mall: 処理結果
        Mall-->>Purchase: 連携完了通知
    end

    rect rgb(235, 255, 235)
        Note over Purchase,Sales: ② 納期回答情報
        Sales->>Mall: DeliverInput（納期回答登録API）
        Mall-->>Sales: 処理結果
        Mall->>Purchase: 納期回答連携
    end

    rect rgb(255, 245, 220)
        Note over Purchase,Sales: ③ 出荷情報
        Sales->>Mall: ShipmentInput（出荷登録API）
        Mall-->>Sales: 処理結果
        Mall->>Purchase: 出荷情報連携
    end

発注情報の連携

購買システム「ジーニー2.0」からカタログモールへ連携されたオーダーをもとに、お取引企業様のオーダー登録APIを呼び出します。

連携タイミングは、リアルタイムを想定します。

flowchart LR

    APPROVER["承認者"]

    subgraph J2SYS["J2システム（ジーニーラボ株式会社）"]
        J2["購買システム（J2）"]
        MALL["カタログモール（J2）"]
    end

    subgraph EXT["お取引企業様"]
        SALES["販売管理システム"]
    end

    APPROVER -->|"購入依頼を承認"| J2
    J2 -->|"発注情報"| MALL
    MALL -->|"OrderInput（発注登録API）"| SALES
    SALES -->|"処理結果"| MALL

納期回答情報の連携

お取引企業様が納期回答を入力する際に、カタログモールの納期回答登録APIを呼び出します。

カタログモールへ登録された納期回答結果は、購買システム「ジーニー2.0」へ連携されます。

連携タイミングは、リアルタイムを想定します。

出荷情報の連携

お取引企業様のシステムで出荷情報が入力された後、カタログモールの出荷登録APIを呼び出します。

カタログモールに登録された出荷結果は、購買システム「ジーニー2.0」へ連携されます。

連携タイミングは、リアルタイムを想定します。

EDI連携一覧

連携情報	方向	主な処理
発注情報	カタログモール → 販売管理システム	発注情報登録
納期回答情報	販売管理システム → カタログモール	納期回答登録
出荷情報	販売管理システム → カタログモール	出荷情報登録
検収情報	購買側 → 取引先側	検収情報連携
支払予定情報	取引先側 → 購買側	締め処理後の支払予定情報連携

1-3. 内部カタログ化

概要

お取引企業様の商品情報をカタログモールの商品マスタへ登録し、内部カタログ商品として検索・利用できるようにします。

内部カタログ化された商品は、外部カタログサイトへ直接遷移することなく、カタログモール上で検索結果として表示できます。

内部カタログ化の基本イメージ

flowchart LR

    SUPPLIER["お取引企業様"]

    subgraph CATALOG["商品情報提供"]
        PRODUCT["商品情報"]
        CSV["CSVファイル"]
        API["API連携"]
    end

    subgraph MALL["カタログモール"]
        REGISTER["商品情報登録"]
        MASTER["商品マスタ"]
        INTERNAL["内部カタログ検索"]
        RESULT["商品検索結果一覧"]
    end

    SUPPLIER --> PRODUCT

    PRODUCT --> CSV
    PRODUCT --> API

    CSV --> REGISTER
    API --> REGISTER

    REGISTER --> MASTER
    MASTER --> INTERNAL
    INTERNAL --> RESULT

内部カタログ化の連携方式

内部カタログの商品情報登録については、主に以下の連携方式を使用します。

方式	概要
API連携	APIを利用して内部カタログの商品情報を登録する
SFTP連携	商品情報CSVおよび関連ファイルをSFTPで連携する
Webメンテナンス	カタログメンテナンス画面から商品情報を管理する

API連携の詳細については「内部商品化（API連携）」、SFTP連携の詳細については「内部商品化（SFTP）」に記載します。

システム全体のまとめ

本システム全体は、以下の3つの連携領域で構成されます。

領域	目的	主な連携方式
商品（検索）情報連携	複数の外部・内部カタログから商品を検索・選択する	PunchOut / REST API
EDI連携	発注後の受発注業務情報をシステム間で連携する	REST API
内部カタログ化	外部の商品情報を商品マスタへ登録し、内部商品として利用する	API / SFTP / Web

全体として、ユーザーはジーニー2.0を入口として商品を検索し、カタログモールを経由して外部カタログおよび内部カタログの商品を利用できます。

商品選択後は、発注、納期回答、出荷、検収、支払予定情報までの購買プロセスを、カタログモールとお取引企業様の販売管理システム間で連携します。

2-1. カタログサイトでの商品検索（パンチアウト連携）

2-1-1. 概要

カタログサイトでの商品検索では、カタログモールからお取引企業様のカタログサイトへ接続し、外部カタログサイト上で商品の検索および選択を行うパンチアウト連携方式を使用します。

主な機能は、以下の2つです。

機能	概要
CheckIn（チェックイン）	お取引企業様のカタログサーバへの接続要求および認証を行い、カタログ検索サイトをWebブラウザ上に表示する
CheckOut（チェックアウト）	外部カタログサイトで選択し、カートに入れた商品をカタログモールのカートへ連携する

画面遷移は、原則としてページ切り替え方式とし、Frameは使用しない想定です。

2-1-2. 前提条件

パンチアウト連携では、以下の通信・データ形式を使用します。

項目	内容
通信方式	HTTPSによる暗号化通信
データ形式	cXMLに準拠したXMLデータ
文字コード	UTF-8
画面遷移方式	原則としてページ切り替え
Frame利用	使用しない想定

パンチアウト連携は、以下の流れで実行されます。

flowchart LR

    subgraph J2SYS["J2システム"]
        MALL["カタログモール"]
        CART["カタログモールのカート"]
    end

    subgraph EXT["外部カタログサイト（お取引企業様）"]
        SEARCH["商品検索"]
        SELECT["商品選択"]
        CONFIRM["カート確認"]
    end

    MALL -->|"① CheckIn<br/>接続・認証"| SEARCH
    SEARCH --> SELECT
    SELECT --> CONFIRM
    CONFIRM -->|"② CheckOut<br/>商品情報返却"| CART

    classDef j2 fill:#e3f2fd,stroke:#1e88e5,stroke-width:1px,color:#0d47a1
    classDef ext fill:#e8f5e9,stroke:#43a047,stroke-width:1px,color:#1b5e20

    class MALL,CART j2
    class SEARCH,SELECT,CONFIRM ext

2-1-3. CheckIn（チェックイン）

2-1-3-1. 処理シーケンス

CheckInは、カタログモールから外部カタログサイトへ接続するための処理です。

購入依頼者が購買システムへログインし、「カタログ購買」を選択すると、購買システムからカタログモールへのパンチアウト接続が行われます。

その後、カタログモール上で対象の外部カタログを選択すると、カタログモールから外部カタログサイトへPunchOutSetupRequestを送信します。

外部カタログサイトは認証処理を行い、PunchOutSetupResponseを返却します。

正常に認証された場合、レスポンスに含まれるStartPageのURLを使用して、対象の外部カタログサイトへリダイレクトします。

sequenceDiagram

    actor User as 購入依頼者
    participant J2 as 購買システム（J2）
    participant Mall as カタログモール（J2）
    participant Catalog as 外部カタログサイト（お取引企業様）

    rect rgb(235, 245, 255)
        Note over User,J2: ① 購買システムへのログイン
        User->>J2: ログイン
        J2-->>User: 購買システムトップページ表示

        User->>J2: 「カタログ購買」をクリック
    end

    rect rgb(235, 255, 235)
        Note over J2,Mall: ② J2⇔カタログモール間のCheckIn
        J2->>Mall: PunchOutSetupRequest<br/>ログイン認証依頼
        Mall-->>J2: PunchOutSetupResponse<br/>ログイン認証結果

        J2->>Mall: カタログモールURLへリダイレクト
        Mall-->>User: カタログモールトップページ表示
    end

    rect rgb(255, 245, 220)
        Note over Mall,Catalog: ③ カタログモール⇔外部カタログサイト間のCheckIn
        User->>Mall: 対象カタログアイコンをクリック

        Mall->>Catalog: PunchOutSetupRequest<br/>ログイン認証依頼
        Catalog-->>Mall: PunchOutSetupResponse<br/>ログイン認証結果

        Mall->>Catalog: StartPage URLへリダイレクト
        Catalog-->>User: 外部カタログトップページ表示
    end

ステータスコード別の処理

PunchOutSetupResponseのステータスコードに応じて、以下の処理を行います。

ステータス	処理
200	`StartPage`に指定されたURLを表示する
4xx	選択された外部カタログへ接続できない旨のメッセージをユーザー画面に表示する
5xx	外部カタログサーバへの接続を1回リトライする。再接続できない場合は、接続できない旨のメッセージを表示する

2-1-3-2. データフォーマット

CheckIn処理では、以下のcXMLメッセージを使用します。

PunchOutSetupRequest
PunchOutSetupResponse

2-1-3-2-1. PunchOutSetupRequest

PunchOutSetupRequestは、カタログモールから外部カタログサイトへ送信する接続・認証要求です。

データ構造

cXML
├── Header
│   ├── From
│   │   └── Credential
│   │       ├── Identity
│   │       └── SharedSecret
│   │
│   ├── To
│   │   └── Credential
│   │       ├── Identity
│   │       └── SharedSecret
│   │
│   └── Sender
│       ├── Credential
│       │   ├── Identity
│       │   └── SharedSecret
│       └── UserAgent
│
└── Request
    └── PunchOutSetupRequest
        ├── BuyerCookie
        ├── Extrinsic（companyCode）
        ├── Extrinsic（departmentCompanyCode）
        ├── Extrinsic（topLevelDepartmentCode）
        ├── Extrinsic（departmentCode）
        ├── Extrinsic（userID）
        ├── Extrinsic（catalogCode）
        ├── Extrinsic（SITE_KBN）
        ├── Extrinsic（DAIHYOID）
        └── BrowserFormPost
            └── URL

タグ・属性一覧

階層	タグ名称	属性・用途
1	cXML	`payloadID`、`timestamp`
2	Header	ヘッダー情報
3	From	送信元情報
4	Credential	`domain`
5	Identity	送信元識別情報
5	SharedSecret	共有認証情報
3	To	送信先情報
4	Credential	`domain`
5	Identity	送信先識別情報
5	SharedSecret	共有認証情報
3	Sender	実際の送信者情報
4	Credential	`domain`
5	Identity	送信者識別情報
5	SharedSecret	共有認証情報
4	UserAgent	ユーザーエージェント情報
2	Request	リクエスト本体
3	PunchOutSetupRequest	`operation`
4	BuyerCookie	セッション識別情報
4	Extrinsic	`name=companyCode`
4	Extrinsic	`name=departmentCompanyCode`
4	Extrinsic	`name=topLevelDepartmentCode`
4	Extrinsic	`name=departmentCode`
4	Extrinsic	`name=userID`
4	Extrinsic	`name=catalogCode`
4	Extrinsic	`name=SITE_KBN`
4	Extrinsic	`name=DAIHYOID`
4	BrowserFormPost	商品選択後の戻り先情報
5	URL	CheckOut時の送信先URL

サンプル

上記データ構造に基づくPunchOutSetupRequestのサンプルは以下のとおりです。

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>

<cXML
    version="1.2.014"
    payloadID="20220202080127.99999.12718.catalogmall"
    timestamp="2022-02-02T08:01:27+09:00">

    <Header>

        <From>
            <Credential domain="DUNS">
                <Identity>00000000</Identity>
                <SharedSecret>********</SharedSecret>
            </Credential>
        </From>

        <To>
            <Credential domain="DUNS">
                <Identity>99999999</Identity>
                <SharedSecret>********</SharedSecret>
            </Credential>
        </To>

        <Sender>
            <Credential domain="NetworkId">
                <Identity>ABCDEF</Identity>
                <SharedSecret>********</SharedSecret>
            </Credential>

            <UserAgent>CatalogMall 1.0</UserAgent>
        </Sender>

    </Header>

    <Request>

        <PunchOutSetupRequest operation="create">

            <BuyerCookie>20220202080127.99999.12718.catalogmall</BuyerCookie>

            <Extrinsic name="companyCode">jn-sol</Extrinsic>
            <Extrinsic name="departmentCompanyCode">jn-sol-dc01</Extrinsic>
            <Extrinsic name="topLevelDepartmentCode">DM10</Extrinsic>
            <Extrinsic name="departmentCode">DM1001</Extrinsic>
            <Extrinsic name="userID">u0001234</Extrinsic>
            <Extrinsic name="catalogCode">1234</Extrinsic>
            <Extrinsic name="SITE_KBN">Jienielab</Extrinsic>
            <Extrinsic name="DAIHYOID">DAI00001</Extrinsic>

            <BrowserFormPost>
                <URL>https://catalogmall.example.com/checkout/receive</URL>
            </BrowserFormPost>

        </PunchOutSetupRequest>

    </Request>

</cXML>

departmentCompanyCode、departmentCode、SITE_KBN、DAIHYOIDなど、設定により送付有無が変わるExtrinsic項目についても、送付する場合のタグ形式を示すため、上記サンプルにはすべて記載しています。

エスケープ対象文字

XMLデータでは、以下の文字を適切にエスケープする必要があります。

< > & ' "

2-1-3-2-2. PunchOutSetupResponse

PunchOutSetupResponseは、外部カタログサイトがPunchOutSetupRequestを受信した後、カタログモールへ返却する認証結果です。

正常時には、StartPage内のURLに外部カタログサイトの遷移先URLを設定します。

データ構造

cXML
└── Response
    ├── Status
    └── PunchOutSetupResponse
        └── StartPage
            └── URL

タグ・属性一覧

階層	タグ名称	属性・用途
1	cXML	`payloadID`、`timestamp`
2	Response	レスポンス本体
3	Status	`code`、`text`
3	PunchOutSetupResponse	パンチアウト接続結果
4	StartPage	遷移先情報
5	URL	外部カタログサイトの遷移先URL

ステータスコード一覧

code	文字列
200	OK
204	No Connect
400	Bad Request
401	Unauthorized
403	Forbidden
450	Not Implemented
500	Internal Server Error
560	Temporary Server Error

2-1-4. CheckOut（チェックアウト）

2-1-4-1. 処理シーケンス

CheckOutは、外部カタログサイトで選択された商品情報をカタログモールへ返却し、カタログモールのカートへ投入する処理です。

購入依頼者は、外部カタログサイトで商品を検索・選択し、外部サイト側のカートを確認します。

その後、「チェックアウト」操作を行うと、外部カタログサイトからカタログモールへPunchOutOrderMessageが送信されます。

カタログモールは受信した商品情報をもとにカートを生成し、購入依頼者にカタログモールのカート画面を表示します。

sequenceDiagram

    actor User as 購入依頼者
    participant Mall as カタログモール（J2）
    participant Catalog as 外部カタログサイト（お取引企業様）

    rect rgb(235, 245, 255)
        Note over User,Catalog: ① 外部カタログサイトでの商品検索・選択
        User->>Catalog: 商品検索
        User->>Catalog: 商品をカートに入れる
        User->>Catalog: 「カートを見る」をクリック

        Catalog-->>User: 外部カタログのカートページ表示
    end

    rect rgb(235, 255, 235)
        Note over User,Mall: ② チェックアウト・カート情報連携
        User->>Catalog: 「チェックアウト」をクリック

        Catalog->>Mall: PunchOutOrderMessage<br/>カート情報送信
    end

    rect rgb(255, 245, 220)
        Note over Mall,User: ③ カタログモールのカート生成・表示
        Mall->>Mall: 商品情報をカートへ登録

        Mall-->>User: カタログモールのカート表示
    end

2-1-4-2. データフォーマット

CheckOut処理では、PunchOutOrderMessageを使用して、外部カタログサイトからカタログモールへ商品情報を連携します。

2-1-4-2-1. PunchOutOrderMessage

PunchOutOrderMessageは、外部カタログサイトのカートに登録された商品情報をカタログモールへ返却するためのcXMLメッセージです。

複数の商品が選択されている場合、ItemInを繰り返して商品情報を送信します。

データ構造

cXML
├── Header
│   ├── From
│   │   └── Credential
│   │       └── Identity
│   │
│   ├── To
│   │   └── Credential
│   │       └── Identity
│   │
│   └── Sender
│       ├── Credential
│       │   └── Identity
│       └── UserAgent
│
└── Message
    └── PunchOutOrderMessage
        ├── BuyerCookie
        │
        ├── PunchOutOrderMessageHeader
        │   └── Total
        │       └── Money
        │
        └── ItemIn（繰り返し可能）
            ├── ItemID
            │   └── SupplierPartID
            │
            └── ItemDetail
                ├── UnitPrice
                │   └── Money
                ├── Description
                │   └── ShortName
                ├── UnitOfMeasure
                ├── ManufacturerPartID
                ├── ManufacturerName
                ├── LeadTime
                └── Extrinsic

主要商品情報項目

ItemInでは、商品ごとに以下の情報を連携します。

基本商品情報

項目	内容
quantity	数量
SupplierPartID	サプライヤ品番
UnitPrice / Money	商品単価
currency	通貨コード
Description	商品説明
ShortName	商品名称
UnitOfMeasure	数量単位
ManufacturerPartID	メーカー品番
ManufacturerName	メーカー名
LeadTime	リードタイム

サプライヤ情報

Extrinsic name	内容
SupplierCode	サプライヤコード
SupplierName	サプライヤ名称

商品概要・仕様情報

Extrinsic name	内容
itemSummary	商品概要
itemSpec1	商品仕様1
itemSpec2	商品仕様2
itemSpec3	商品仕様3

購買単位情報

Extrinsic name	内容
purchaseUnitCode	購買単位コード
purchaseUnitName	購買単位名称
purchaseUnitQuantityPerCarton	1梱包あたりの購買単位数量
quantityUnitCode	数量単位コード
quantityUnitName	数量単位名称
quantityPerCarton	1梱包あたりの数量

カテゴリ情報

Extrinsic name	内容
largeCategorycode	大分類コード
largeCategoryname	大分類名称
middleCategorycode	中分類コード
middleCategoryname	中分類名称
smallCategorycode	小分類コード
smallCategoryname	小分類名称

環境・価格・注文条件

Extrinsic name	内容
greenItem	グリーン商品情報
taxClass	税区分
postageFlag	送料区分
regularPrice	標準価格
orderLot	注文ロット
minOrderQuantity	最小注文数量

URL・商品識別情報

Extrinsic name	内容
itemURL1	商品関連URL 1
itemURL2	商品関連URL 2
itemURL3	商品関連URL 3
productURL	商品ページURL
casNo	CAS番号

任意拡張項目

個別の商品属性を連携するため、以下の任意項目を使用できます。

optionalItem1
optionalItem2
optionalItem3
...
optionalItem20

グリーン商品情報の取り扱い

利用企業ごとに、グリーン対象となる規格を事前登録します。

CheckOut後、カタログモールのカート内では、登録されているグリーン規格のみをグリーン商品として表示します。

以下の場合、グリーン商品として表示されません。

利用企業側で対象規格が登録されていない場合
外部カタログサイト上ではグリーンマークが表示されていても、連携値が設定されていない場合

したがって、外部カタログサイト上の表示だけではなく、PunchOutOrderMessageで連携されるグリーン商品情報と、利用企業ごとのグリーン対象規格設定をもとに表示判定を行います。

CheckOut後の画面遷移

外部カタログサイト側でPunchOutOrderMessage送信後のレスポンスBodyに画面制御処理を実装することで、購買システムのページを再読み込みし、外部カタログ画面を閉じることができます。

処理イメージは以下のとおりです。

外部カタログサイト
        │
        │ PunchOutOrderMessage
        ▼
カタログモール
        │
        │ 商品情報登録
        ▼
カート生成
        │
        │ 親画面を購買システムへ遷移
        ▼
外部カタログ画面をClose

2-1. パンチアウト連携の全体まとめ

パンチアウト連携は、CheckInとCheckOutの2つの主要処理で構成されます。

flowchart LR

    USER["購入依頼者"]

    subgraph J2SYS["J2システム（ジーニーラボ株式会社）"]
        MALL["カタログモール"]
        CART["カタログモールのカート"]
    end

    subgraph EXT["外部カタログサイト（お取引企業様）"]
        AUTH["認証"]
        SEARCH["商品検索"]
        SELECT["商品選択"]
        EXTCART["外部カート"]
    end

    USER -->|"対象カタログを選択"| MALL

    MALL -->|"① CheckIn<br/>PunchOutSetupRequest/<br/>PunchOutSetupResponse"| AUTH
    AUTH --> SEARCH
    SEARCH --> SELECT
    SELECT --> EXTCART

    EXTCART -->|"② CheckOut<br/>PunchOutOrderMessage"| CART

    CART -->|"カート画面表示"| USER

CheckInでは、PunchOutSetupRequestとPunchOutSetupResponseを使用して、認証および外部カタログサイトへの画面遷移を行います。

CheckOutでは、PunchOutOrderMessageを使用して、外部カタログサイトで選択された商品情報をカタログモールへ返却します。

これにより、購入依頼者は外部カタログサイトの商品検索機能を利用しながら、選択した商品をジーニー2.0の購買プロセスへ連携できます。

2-2. バックグラウンドキーワード検索（API連携）

2-2-1. 概要

バックグラウンドキーワード検索は、カタログモールに入力された検索条件をもとに、外部カタログの商品検索APIをバックグラウンドで実行し、検索結果をカタログモールの商品検索結果一覧へ表示するための連携方式です。

パンチアウト連携とは異なり、購入依頼者が外部カタログサイトへ画面遷移することなく、カタログモール上から複数のカタログの商品を検索できます。

バックグラウンドキーワード検索では、主に以下の2つのAPIを使用します。

API名	機能	処理概要
KeywordSearch	外部カタログ検索	カタログモールに入力された検索キーワードをもとに商品検索を要求し、検索結果の商品件数を取得する
KeywordItemAdd	商品情報送信	検索条件にヒットした商品情報をカタログモールへ非同期で送信する

基本的な処理は、以下の2段階で行われます。

① KeywordSearch
   カタログモール
        ↓ 検索条件
   外部カタログ
        ↓
   検索件数を返却

② KeywordItemAdd
   外部カタログ
        ↓ 商品情報を非同期送信
   カタログモール
        ↓
   検索結果一覧に表示

2-2-2. 前提条件

バックグラウンドキーワード検索では、カタログモールと外部カタログサーバ間でAPI通信を行います。

基本的な通信条件は以下のとおりです。

項目	内容
通信方式	HTTPS
連携方式	API連携
データ形式	JSON
Content-Type	`application/json`
検索処理	KeywordSearch
商品情報返却	KeywordItemAdd
商品情報返却方式	非同期
返却単位	KeywordSearchの`returnCount`に基づいて分割送信
処理完了判定	KeywordItemAddの`finalFlag`で判定

検索結果の商品情報は、一括で返却するのではなく、指定された返却件数単位で分割して非同期送信できます。

2-2-3. 処理シーケンス

バックグラウンドキーワード検索の基本的な処理フローは以下のとおりです。

sequenceDiagram

    actor User as 購入依頼者
    participant Mall as カタログモール（J2）
    participant Catalog as 外部カタログサーバ（お取引企業様）

    rect rgb(235, 245, 255)
        Note over User,Catalog: ① 検索要求・件数取得
        User->>Mall: 検索条件を入力
        User->>Mall: 検索実行

        Mall->>Catalog: KeywordSearch<br/>検索条件送信

        Catalog->>Catalog: 商品検索処理

        Catalog-->>Mall: KeywordSearch Response<br/>検索商品件数を返却
    end

    rect rgb(235, 255, 235)
        Note over Mall,Catalog: ② 商品情報の非同期・分割送信
        loop returnCount単位で送信
            Catalog->>Mall: KeywordItemAdd<br/>商品情報送信
            Mall-->>Catalog: 処理結果
        end

        Catalog->>Mall: KeywordItemAdd<br/>finalFlag = 9（送信完了）

        Mall-->>Catalog: 処理結果
    end

    rect rgb(255, 245, 220)
        Note over Mall,User: ③ 検索結果の統合・表示
        Mall->>Mall: 検索結果を統合
        Mall-->>User: 商品検索結果一覧を表示
    end

処理の流れは以下のとおりです。

購入依頼者がカタログモールに検索条件を入力します。
カタログモールから外部カタログサーバへKeywordSearchを送信します。
外部カタログサーバは検索条件をもとに商品を検索します。
KeywordSearchのレスポンスとして、検索対象の商品件数を返却します。
外部カタログサーバは、検索された商品情報をKeywordItemAddで非同期送信します。
商品情報はreturnCountで指定された件数単位で分割して送信できます。
すべての商品情報の送信が完了した場合、finalFlag = 9を設定します。
カタログモールは受信した商品情報を検索結果として表示します。

2-2-4. API一覧

API名	内容
KeywordSearch（外部カタログ検索）	カタログモールに入力された検索キーワードをもとに商品検索を要求する。処理結果として取得件数を返却する
KeywordItemAdd（商品情報送信）	検索キーワードにヒットした商品情報を非同期でPOSTする。返却単位はKeywordSearchの返却件数パラメータに基づく

2-2-4-1. KeywordSearch（外部カタログ検索）

概要

KeywordSearchは、カタログモールから外部カタログサーバへ検索条件を送信し、条件に一致する商品の検索を要求するAPIです。

外部カタログサーバは検索処理を実行し、検索対象の商品件数をレスポンスとして返却します。

商品情報そのものはKeywordSearchのレスポンスでは返却せず、後続のKeywordItemAddを使用して非同期でカタログモールへ送信します。

リクエスト

認証・制御情報

パラメータ名	必須	説明
loginID	○	外部カタログサーバへのログインユーザID
loginPWD	○	外部カタログサーバへのログインパスワード
payloadID	○	ユニークとなる識別子
timestamp	○	データ作成日時
catalogCode	○	カタログコード
companyCode	○	会社コード
departmentCompanyCode		部門会社コード
topLevelDepartmentCode	○	最上位組織コード
departmentCode		部門コード。設定により送付可能
SITE_KBN		サイト区分。マスタ設定により送付可能

payloadID

payloadIDには、リクエストを一意に識別できる値を設定します。

基本構成は以下のとおりです。

日付.プロセスID.ランダム数値.ホスト名

timestamp

データ作成日時を以下の形式で設定します。

YYYY-MM-DDThh:mm:ss-hh:mm

検索条件

パラメータ名	必須	説明
freeword		検索キーワード
freeword1		検索キーワード
casNo		CAS番号
makerModelID		メーカー型番
makerName		メーカー名称
greenItem		グリーン品規格
sortType		検索結果の表示順
excludeKeyword		除外キーワード

freeword / freeword1

検索キーワードを指定します。

複数のキーワードを指定する場合は、キーワード間を空白文字で区切ります。

また、外部カタログから提供されたカテゴリマスタの小分類名を検索キーワードとして設定して検索を要求する場合があります。

その場合は、指定された小分類名に紐づく商品情報をすべて返却します。

greenItem

検索条件にグリーン品が指定された場合、利用企業の検索対象規格を設定します。

規格の種類は、PunchOutOrderMessageと同様に桁位置で指定します。

sortType

検索結果の表示順を指定します。

値	表示順
0	標準
1	価格が安い順
2	価格が高い順
3	標準納期が短い順
4	カタログ品番の昇順
5	カタログ品番の降順

未指定の場合は0：標準を使用します。

excludeKeyword

検索結果から除外するキーワードを指定します。

複数のキーワードを指定する場合は、全角または半角の空白文字で区切ります。

キーワード間はAND条件として扱います。

商品情報返却制御

パラメータ名	必須	説明
keywordItemAddURL	○	検索商品を返却するKeywordItemAddのフルURL
firstReturnCount		初回返却商品検索件数。1ページに表示される最大件数
maxReturnCount		返却最大商品検索件数
returnCount	○	非同期で商品情報を返却する際の1回あたりの返却件数

返却イメージ

例えば、以下の条件の場合、

検索ヒット件数：250件
maxReturnCount：200件
returnCount：50件

最大返却対象は200件となり、KeywordItemAddを使用して50件単位で商品情報を送信します。

KeywordItemAdd #1 → 50件
KeywordItemAdd #2 → 50件
KeywordItemAdd #3 → 50件
KeywordItemAdd #4 → 50件 + finalFlag = 9

レスポンス

パラメータ名	必須	説明
payloadID	○	リクエスト時のpayloadID
timestamp	○	リクエスト時のtimestamp
command	○	実行したAPIの名称
version	○	実行したAPIのバージョン
catalogCode	○	リクエスト時のカタログコード
response	○	実行結果
error	条件付き	エラー情報。responseが`failure`の場合は必須
result		実行結果情報
result.itemCount	○	検索条件に合致した商品件数

response

値	意味
success	成功
failure	失敗

error

response = failureの場合、以下のエラー情報を設定します。

パラメータ名	必須	説明
code	○	エラーコード
message	○	エラーメッセージ

itemCount

検索キーワードに合致した商品件数を設定します。

リクエストのmaxReturnCountが実際の検索件数より小さい場合は、maxReturnCountの値を設定します。

例：

実際の検索件数：1,000件
maxReturnCount：500件

result.itemCount = 500

KeywordSearch ステータスコード

code	文字列	説明
200	OK	正常終了
400	Bad Request	外部カタログサーバ側でリクエストを受け付けられない場合
401	Unauthorized	認証できない場合
403	Forbidden	権限がない場合
450	Not Implemented	KeywordSearchの処理が実装されていない場合
500	Internal Server Error	外部カタログサーバ側で内部エラーが発生した場合
560	Temporary Server Error	サーバ再起動、メンテナンス等により一時的に処理を受け付けられない場合

2-2-4-2. KeywordItemAdd（商品情報取得）

概要

KeywordItemAddは、KeywordSearchで検索条件にヒットした商品情報を、外部カタログサーバからカタログモールへ非同期で送信するAPIです。

複数の商品を送信する場合は、itemINを繰り返して設定します。

商品情報の返却単位は、KeywordSearchのreturnCountに基づきます。

リクエスト基本情報

パラメータ名	必須	説明
loginID	○	外部カタログサーバへのログインユーザID
payloadID	○	KeywordSearchリクエスト時のpayloadID
timestamp	○	KeywordSearchリクエスト時のtimestamp
catalogCode	○	KeywordSearchリクエスト時のcatalogCode
itemIN		商品情報。複数商品の場合は繰り返し設定
finalFlag	○	商品情報送信の完了状態

itemIN：基本商品情報

パラメータ名	必須	説明
SupplierPartID	○	サプライヤ品番
itemName	○	商品名
makerModelID	○	メーカー型番
makerName	○	メーカー名称
standardDeliveryTime	○	標準納期
supplierCode	○	サプライヤコード
supplierName	○	サプライヤ名
itemSummary	○	商品概要
itemSpec1	○	商品仕様1
itemSpec2		商品仕様2
itemSpec3		商品仕様3

購入単位・数量単位情報

パラメータ名	必須	説明
purchaseUnitCode	○	購入単位区分
purchaseUnitName	○	購入単位名
purchaseUnitQuantityPerCarton	○	購入単位入数
quantityUnitCode	○	数量単位区分
quantityUnitName	○	数量単位名
quantityPerCarton	○	数量単位入数

カテゴリ情報

パラメータ名	必須	説明
largeCategorycode	○	大分類コード
largeCategoryname	○	大分類名
middleCategorycode	○	中分類コード
middleCategoryname	○	中分類名
smallCategorycode	○	小分類コード
smallCategoryname	○	小分類名

smallCategorycodeおよびsmallCategorynameの設定内容は、PunchOutOrderMessageの設定内容と同様です。

グリーン商品・税・送料情報

パラメータ名	必須	説明
greenItem		グリーン品規格
taxClass	○	課税区分
postageFlag	○	送料区分・別途費用区分

taxClass

値	内容
0	課税（税込）
1	課税（税抜き）
2	非課税
3	免税
4	経過措置（税込）
5	経過措置（税抜き）
7	不課税
14	軽減課税（税込）
15	軽減課税（税抜き）

postageFlag

値	内容
1	別途費用。受注時に単価決定、または注文時に納品先に応じて別途費用を取得
2	単独購入の場合、パンチアウト連携による購入が必要

価格・注文条件

パラメータ名	必須	説明
regularPrice	○	定価
currencyCode	○	通貨コード
saleUnitPrice	○	販売単価
orderLot	○	発注ロット
minOrderQuantity	○	最低発注数

URL情報

パラメータ名	必須	説明
itemURL1	○	商品画像URL1
itemURL2		商品画像URL2
itemURL3		商品画像URL3
productURL		商品詳細画面のURL

商品状態・後継品情報

パラメータ名	必須	説明
itemDivision	○	商品区分
SuccessorItemCd		後継品番
returnProprietyFlag	○	返品可否

itemDivision

値	内容
0	通常
1	製造中止
2	販売中止

returnProprietyFlag

値	内容
0	返品可
1	返品不可

受注品など、調整後に返品できない商品については1：返品不可を指定します。

任意項目

optionalItem1からoptionalItem20までの予備項目を使用できます。

仕様書上で用途が定義されている項目は以下のとおりです。

パラメータ名	用途
optionalItem1	仕入単価
optionalItem2	JANコード
optionalItem4	注文コード
optionalItem6	UNSPSCコード
その他	予備項目

外部カタログサイト側で仕入単価を保持している場合、optionalItem1は必須となります。

finalFlag

finalFlagは、検索された商品情報の送信状態を表します。

値	内容
0	未完了
9	終了。抽出された商品情報の送信がすべて完了

分割送信イメージ

sequenceDiagram

    participant Catalog as 外部カタログ（お取引企業様）
    participant Mall as カタログモール（J2）

    rect rgb(255, 245, 220)
        Note over Catalog,Mall: 送信中（finalFlag = 0）
        Catalog->>Mall: KeywordItemAdd<br/>商品 1～50<br/>finalFlag = 0（未完了）
        Mall-->>Catalog: success

        Catalog->>Mall: KeywordItemAdd<br/>商品 51～100<br/>finalFlag = 0（未完了）
        Mall-->>Catalog: success
    end

    rect rgb(235, 255, 235)
        Note over Catalog,Mall: 送信完了（finalFlag = 9）
        Catalog->>Mall: KeywordItemAdd<br/>商品 101～120<br/>finalFlag = 9（送信完了）
        Mall-->>Catalog: success
    end

KeywordItemAdd レスポンス

パラメータ名	必須	説明
payloadID	○	リクエスト時のpayloadID
timestamp	○	リクエスト時のtimestamp
command	○	実行したAPIの名称
version	○	実行したAPIのバージョン
catalogCode	○	リクエスト時のcatalogCode
response	○	実行結果
error	条件付き	エラー情報

response

値	内容
success	成功
cancel	中止。商品検索が再度実行された場合に返却
failure	失敗

response = failureの場合は、以下のエラー情報を返却します。

パラメータ名	必須	説明
code	○	エラーコード
message	○	エラーメッセージ

KeywordItemAdd ステータスコード

code	文字列	説明
200	OK	正常終了
400	Bad Request	外部カタログサーバ側でリクエストを受け付けられない場合
403	Forbidden	権限がない場合
450	Not Implemented	KeywordItemAddの処理が実装されていない場合
500	Internal Server Error	外部カタログサーバ側で内部エラーが発生した場合
560	Temporary Server Error	サーバ再起動、メンテナンス等により一時的に処理を受け付けられない場合

2-2. バックグラウンドキーワード検索の全体まとめ

バックグラウンドキーワード検索は、KeywordSearchとKeywordItemAddの2つのAPIを組み合わせて実現します。

flowchart LR

    USER["購入依頼者"]

    MALL_SEARCH["カタログモール<br/>検索画面"]

    KEYWORD["① KeywordSearch<br/>検索条件送信"]

    EXT["外部カタログ<br/>商品検索"]

    COUNT["② 検索件数返却"]

    ITEM["③ KeywordItemAdd<br/>商品情報非同期送信"]

    RESULT["④ 検索結果一覧"]

    USER --> MALL_SEARCH
    MALL_SEARCH --> KEYWORD
    KEYWORD --> EXT
    EXT --> COUNT
    COUNT --> MALL_SEARCH
    EXT --> ITEM
    ITEM --> RESULT
    RESULT --> USER

処理のポイントは以下のとおりです。

カタログモールからKeywordSearchで検索条件を送信する。
外部カタログは検索結果の商品件数を返却する。
商品情報はKeywordItemAddを使用して非同期で送信する。
大量の商品情報はreturnCount単位で分割送信できる。
最後の商品情報送信時にfinalFlag = 9を設定する。
カタログモールは受信した商品情報を統合して検索結果一覧に表示する。

この仕組みにより、購入依頼者は外部カタログサイトへ画面遷移することなく、カタログモール上で外部カタログの商品を検索・比較できます。

2-4. 内部商品化（API連携）

2-4-1. 概要

内部商品化（API連携）は、外部カタログの商品情報をカタログモールの商品マスタへ登録し、内部カタログ商品として利用できるようにするための連携です。

主に以下の2つのAPIを使用します。

API名	内容
GetRegistItem	内部カタログへ登録対象となる商品の件数を取得する
RegistItemAdd	内部カタログへ商品情報を登録する

基本的な流れは以下のとおりです。

sequenceDiagram
    participant Mall as カタログモール（J2）
    participant Catalog as 外部カタログサーバ（お取引企業様）

    rect rgb(235, 245, 255)
        Note over Mall,Catalog: ① 登録対象件数の取得
        Mall->>Catalog: GetRegistItem<br/>登録対象商品の件数取得
        Catalog-->>Mall: itemCount返却
    end

    rect rgb(235, 255, 235)
        Note over Mall,Catalog: ② 商品情報の分割送信
        loop returnCount単位で分割送信
            Catalog->>Mall: RegistItemAdd<br/>商品情報登録
            Mall-->>Catalog: 実行結果
        end
    end

    rect rgb(255, 245, 220)
        Note over Mall,Catalog: ③ 送信完了
        Catalog->>Mall: RegistItemAdd<br/>finalFlag = 9（送信完了）
        Mall-->>Catalog: 登録完了
    end

2-4-2. API一覧

API名	内容
GetRegistItem	商品の件数を取得する。外部カタログ登録件数取得
RegistItemAdd	商品情報を登録する。商品情報登録

2-4-3. GetRegistItem（内部化カタログ登録件数取得）

概要

GetRegistItemは、カタログモールから外部カタログサーバへ、内部商品化対象の商品件数を問い合わせるAPIです。

対象となる商品は、前回登録日時であるregistLastTimeより後に更新された商品です。

初回実行時は、registLastTimeに空文字を設定します。

リクエスト

パラメータ名	必須	説明
loginID	○	外部カタログサーバへのログインユーザID
loginPWD	○	外部カタログサーバへのログインパスワード
payloadID	○	ユニークとなる識別子
timestamp	○	データ作成日時
catalogCode	○	カタログコード
registLastTime	○	前回登録日時。これより後に更新された商品を処理対象にする
RegistItemAddURL	○	商品情報を返却するRegistItemAddのURL
returnCount	○	非同期で返却する単位件数

payloadID形式

日付.プロセスID.ランダム数値.ホスト名

timestamp形式

YYYY-MM-DDThh:mm:ss-hh:mm(UTC)

registLastTime

初回：Blank('')
形式：YYYY-MM-DDThh:mm:ss-hh:mm(UTC)

returnCountの例

returnCount = 100 の場合、
RegistItemAddを100件単位で呼び出す。

レスポンス

パラメータ名	必須	説明
payloadID	○	リクエスト時のpayloadID
timestamp	○	リクエスト時のtimestamp
command	○	実行したAPIの名称
version	○	実行したAPIのバージョン
catalogCode	○	リクエスト時のカタログコード
response	○	success：成功 / failure：失敗
error	条件付き	responseがfailureの場合は必須
result.itemCount	○	商品件数

error

パラメータ名	必須	説明
code	○	エラーコード
message	○	エラーメッセージ

ステータスコード

code	文字列	説明
200	OK	正常終了
400	Bad Request	外部カタログサーバ側でリクエストを受け付けられない場合
403	Forbidden	権限がない場合
450	Not Implemented	GetRegistItemの処理が実装されていない場合
500	Internal Server Error	外部カタログサーバ側で内部エラーが発生した場合
560	Temporary Server Error	サーバ再起動・メンテナンス等で処理を受け付けられない場合

2-4-4. RegistItemAdd（商品情報登録）

概要

RegistItemAddは、外部カタログサーバからカタログモールへ、内部商品化対象の商品情報を登録するAPIです。

複数商品の場合、itemINを繰り返して設定します。

すべての商品情報の送信が完了した場合、finalFlag = 9を設定します。

リクエスト基本情報

パラメータ名	必須	説明
loginID	○	外部カタログサーバへのログインユーザID
loginPWD	○	外部カタログサーバへのログインパスワード
payloadID	○	GetRegistItemリクエスト時のpayloadID
timestamp	○	GetRegistItemリクエスト時のtimestamp
catalogCode	○	GetRegistItemリクエスト時のcatalogCode
itemIN		商品情報。複数商品の場合は繰り返し設定
finalFlag	○	0：未完、9：終了

itemIN：キー情報

パラメータ名	必須	説明
buyerCompanyCode		バイヤ企業コード
topLevelDepartmentCode		最上位組織コード。代理店の選定に利用
SupplierPartID	○	サプライヤ品番

itemIN：基本商品情報

パラメータ名	必須	説明
itemName	○	商品名
makerModelID	○	メーカー型番
makerName	○	メーカー名称
standardDeliveryTime	○	標準納期
supplierCode	○	サプライヤコード
supplierName	○	サプライヤ名
itemSummary	○	商品概要
itemSpec1	○	商品仕様1
itemSpec2		商品仕様2
itemSpec3		商品仕様3

itemIN：単位・数量情報

パラメータ名	必須	説明
purchaseUnitCode	○	購入単位区分
purchaseUnitName	○	購入単位名
purchaseUnitQuantityPerCarton	○	購入単位入数
quantityUnitCode	○	数量単位区分
quantityUnitName	○	数量単位名
quantityPerCarton	○	数量単位入数

itemIN：カテゴリ情報

パラメータ名	必須	説明
largeCategorycode	○	大分類コード
largeCategoryname	○	大分類名
middleCategorycode	○	中分類コード
middleCategoryname	○	中分類名
smallCategorycode	○	小分類コード
smallCategoryname	○	小分類名

itemIN：グリーン・税・送料情報

パラメータ名	必須	説明
greenItem		グリーン品規格
taxClass	○	課税区分
postageFlag	○	送料区分・別途費用区分

taxClass

値	内容
0	課税（税込）
1	課税（税抜き）
2	非課税
3	免税
4	経過措置（税込）
5	経過措置（税抜き）
7	不課税
14	軽減課税（税込）
15	軽減課税（税抜き）

postageFlag

値	内容
0	無し
1	別途費用。受注時に単価決定

itemIN：価格・注文条件

パラメータ名	必須	説明
regularPrice	○	定価。オープン価格の場合はALL9を設定
currencyCode	○	通貨コード
saleUnitPrice	○	販売単価
orderLot	○	発注ロット。指定がない場合は1
minOrderQuantity	○	最低発注数。指定がない場合は1

itemIN：URL・商品状態

パラメータ名	必須	説明
itemURL1	○	商品画像URL1
itemURL2		商品画像URL2
itemURL3		商品画像URL3
itemDivision	○	商品区分
SuccessorItemCd		後継品番
returnProprietyFlag	○	返品可否

itemDivision

値	内容
0	通常
1	製造中止
2	販売中止

returnProprietyFlag

値	内容
0	返品可
1	返品不可

itemIN：関連商品・予備項目

パラメータ名	説明
RelateProduct1	関連商品1のサプライヤ品番
RelateProduct2	関連商品2のサプライヤ品番
RelateProduct3	関連商品3のサプライヤ品番
RelateProduct4	関連商品4のサプライヤ品番
RelateProduct5	関連商品5のサプライヤ品番
optionalItem1	予備項目1。仕入単価
optionalItem2	予備項目2。JANコード
optionalItem3〜20	予備項目

外部カタログサイト側で仕入単価を保持している場合、optionalItem1は必須です。

itemIN：販売期間・更新日時・検索キーワード

パラメータ名	必須	説明
startDate	○	販売開始日
endDate		販売終了日
registTime		商品の最新更新日時
searchkeyword		サプライヤ品番、品名、メーカー型番、メーカー品名、サプライヤ名称以外の検索キーワード

registTime形式

YYYY-MM-DDThh:mm:ss-hh:mm(UTC)

finalFlag

値	内容
0	未完了
9	終了。抽出された商品情報の送信が完了

レスポンス

パラメータ名	必須	説明
payloadID	○	リクエスト時のpayloadID
timestamp	○	リクエスト時のtimestamp
command	○	実行したAPIの名称
version	○	実行したAPIのバージョン
catalogCode	○	リクエスト時のcatalogCode
response	○	success：成功 / cancel：中止 / failure：失敗
error	条件付き	responseがfailureの場合は必須

response

値	内容
success	成功
cancel	中止。商品検索が再度実行された場合に返却
failure	失敗

error

パラメータ名	必須	説明
code	○	エラーコード
message	○	エラーメッセージ

2-4. 内部商品化（API連携）のまとめ

内部商品化API連携は、外部カタログの商品情報をカタログモールの商品マスタへ登録するための仕組みです。

処理は大きく以下の2段階です。

GetRegistItemで、前回登録日時以降に更新された登録対象商品の件数を取得する。
RegistItemAddで、対象商品をreturnCount単位でカタログモールへ登録する。

これにより、外部カタログの商品情報を内部カタログ商品として検索・利用できるようになります。

2-5. 内部商品化（SFTP）

2-5-1. 概要

内部商品化（SFTP）は、外部システムから商品情報ファイルをSFTP経由でカタログモールへ連携し、ジーニーシステムの内部商品として登録するための連携方式です。

外部システムは、商品情報をCSV形式またはZIP形式のファイルとしてSFTP公開エリアへ配置します。

ジーニーシステムは対象ファイルを取得し、バックアップ、商品登録、バリデーションチェックを実施します。

処理結果は、CHKファイルおよびエラー内容に応じたCSVファイルとして、SFTP公開エリアへ出力されます。

2-5-2. 全体処理フロー

flowchart LR

    subgraph EXT["外部システム"]
        CSV["商品情報CSV"]
        ZIP["ZIPファイル"]
    end

    subgraph SFTP["SFTP公開エリア"]
        TOJ2["ToJ2"]
        FROMJ2["FromJ2"]
    end

    subgraph J2["ジーニーシステム"]
        CHECK["① ファイル存在確認"]
        GET["② ファイル取得"]
        BACKUP["③ バックアップ"]
        DELETE["④ 公開エリアから削除"]
        REGISTER["⑤ 内部商品登録"]
        VALIDATION{"⑥ チェック結果"}
    end

    CSV --> TOJ2
    ZIP --> TOJ2

    TOJ2 --> CHECK
    CHECK --> GET
    GET --> BACKUP
    BACKUP --> DELETE
    DELETE --> REGISTER
    REGISTER --> VALIDATION

    VALIDATION -->|"正常"| CHK["CHKファイル"]
    VALIDATION -->|"データエラー"| NG["*_NG.csv"]
    VALIDATION -->|"CSV変換不可"| FORMAT["*_FORMAT_ERROR.csv"]

    CHK --> FROMJ2
    NG --> FROMJ2
    FORMAT --> FROMJ2

2-5-3. 処理概要

内部商品化（SFTP）の処理は、R1からR6までの6つのステップで構成されます。

処理ID	処理内容
R1	SFTP公開エリアに対象ファイルが存在するかチェックする。存在しない場合はログを出力して処理を終了する
R2	処理対象ファイルをSFTP公開エリアからGETする
R3	GETしたファイルをバックアップ領域へコピーする
R4	SFTP公開エリアから対象ファイルを削除する
R5	ジーニーシステムで内部商品登録を行う
R6	バリデーションチェック等により内部商品化できないデータが存在する場合、チェックエラーファイルを作成する

処理フロー詳細

flowchart TD

    START["処理開始"]

    R1{"R1<br/>対象ファイルが<br/>存在するか？"}

    LOG["ログを出力"]
    END1["処理終了"]

    R2["R2<br/>対象ファイルをGET"]

    R3["R3<br/>バックアップ領域へコピー"]

    R4["R4<br/>SFTP公開エリアから<br/>対象ファイルを削除"]

    R5["R5<br/>内部商品登録"]

    R6["R6<br/>バリデーションチェック"]

    RESULT{"チェック結果"}

    OK["正常登録"]
    NG["チェックエラーファイル作成"]

    END2["処理終了"]

    START --> R1

    R1 -->|"存在しない"| LOG
    LOG --> END1

    R1 -->|"存在する"| R2
    R2 --> R3
    R3 --> R4
    R4 --> R5
    R5 --> R6

    R6 --> RESULT

    RESULT -->|"正常"| OK
    RESULT -->|"エラーあり"| NG

    OK --> END2
    NG --> END2

    classDef flow fill:#e8eaf6,stroke:#3f51b5,stroke-width:1px,color:#1a237e
    classDef decision fill:#fff3e0,stroke:#fb8c00,stroke-width:1px,color:#e65100
    classDef success fill:#e8f5e9,stroke:#43a047,stroke-width:1px,color:#1b5e20
    classDef danger fill:#ffebee,stroke:#e53935,stroke-width:1px,color:#b71c1c
    classDef info fill:#e3f2fd,stroke:#1e88e5,stroke-width:1px,color:#0d47a1

    class START,R2,R3,R4,R5,R6,END1,END2 flow
    class R1,RESULT decision
    class LOG info
    class OK success
    class NG danger

2-5-4. 前提条件

SFTPで連携する商品情報ファイルの基本条件は以下のとおりです。

項目	内容
ファイル形式	CSV
文字コード	Shift_JIS または UTF-8
ヘッダー	あり
区切り文字	カンマ
ダブルクォーテーション	あり
フィールド内改行	CRLFを使用しない

CSV形式の基本イメージ

"商品コード","商品名","メーカー型番","メーカー名","販売単価"
"ITEM001","商品A","MODEL-A","メーカーA","1000"
"ITEM002","商品B","MODEL-B","メーカーB","2000"

実際の商品情報CSVの項目定義については、別途「商品情報SFTP形式CSV」の仕様を参照します。

2-5-5. ディレクトリ構成

SFTP公開エリアは、カタログコード単位で構成されます。

カタログコード/
│
├── ToJ2/
│   │
│   ├── *.zip
│   └── *.csv
│
└── FromJ2/
    │
    ├── *.CHK
    ├── *_NG.csv
    └── *_FORMAT_ERROR.csv

ディレクトリ・ファイルの役割

パス・ファイル	用途
`カタログコード/`	公開ルートディレクトリ。SFTPログイン時に接続するルート
`ToJ2/`	外部システムからJ2へ送信するデータを配置するディレクトリ
`*.zip`	内部商品化対象のZIPファイル
`*.csv`	内部商品化対象の商品情報CSVファイル
`FromJ2/`	J2から出力する内部商品登録結果を配置するディレクトリ
`*.CHK`	処理結果を記録したチェックファイル
`*_NG.csv`	内容チェックでNGとなったデータを出力するファイル
`*_FORMAT_ERROR.csv`	CSV変換できないファイルのエラー情報を出力するファイル

2-5-6. ToJ2ディレクトリ

概要

ToJ2は、外部システムからジーニーシステムへ内部商品化対象の商品情報を送信するためのディレクトリです。

カタログコード/
└── ToJ2/
    ├── product_001.csv
    ├── product_002.csv
    └── product_003.zip

処理対象ファイル形式は以下のとおりです。

ZIPファイル
CSVファイル

CSVファイルの最大件数

1つのCSVファイルに格納できる最大件数は、タイトル行を含めて10,001件です。

したがって、1ファイルあたりの商品データ件数は最大10,000件となります。

1行目        ：タイトル行（ヘッダー）
2～10,001行目：商品データ

最大商品件数：10,000件

商品件数が10,000件を超える場合は、複数のCSVファイルへ分割して連携します。

2-5-7. FromJ2ディレクトリ

概要

FromJ2は、ジーニーシステムによる内部商品登録の処理結果を出力するためのディレクトリです。

カタログコード/
└── FromJ2/
    ├── product_001.CHK
    ├── product_001_NG.csv
    └── product_001_FORMAT_ERROR.csv

主に以下の3種類の結果ファイルを出力します。

ファイル	用途
CHKファイル	内部商品登録処理全体の実行結果を確認する
NGファイル	データ内容のチェックでエラーとなった商品を確認する
FORMAT_ERRORファイル	CSVとして正常に変換・処理できないデータを確認する

2-5-8. CHKファイル

内部商品登録処理の実行後、処理結果をCHKファイルとしてFromJ2ディレクトリへ配置します。

CHKファイルには、以下の処理情報が含まれます。

項目	内容
処理開始日時	内部商品登録処理を開始した日時
処理終了日時	内部商品登録処理が終了した日時
処理件数	処理対象となった総件数
OK件数	正常に処理された件数
NG件数	エラーとなった件数

処理結果のイメージは以下のとおりです。

処理件数：10,000件
├── OK：9,950件
└── NG：50件

CHKファイルにより、ファイル単位で内部商品登録処理の実行結果を確認できます。

2-5-9. NGファイル

商品情報の内容をチェックした結果、内部商品化できないデータが存在する場合、NGファイルを作成します。

ファイル名の形式は以下のとおりです。

*_NG.csv

NGファイルの対象となるのは、CSVファイル自体は読み込み可能であるものの、商品情報の内容に問題があるケースです。

例：

必須項目が設定されていない
項目の値が許容範囲外
コード値が不正
日付形式が不正
数値項目に不正な文字列が設定されている
その他、内部商品登録のバリデーション条件を満たしていない

flowchart LR

    CSV["商品情報CSV"]
    READ["CSV読込"]
    VALIDATE["バリデーション"]

    OK["正常商品<br/>内部商品登録"]
    NG["エラー商品<br/>*_NG.csv"]

    CSV --> READ
    READ --> VALIDATE

    VALIDATE -->|"OK"| OK
    VALIDATE -->|"NG"| NG

2-5-10. FORMAT_ERRORファイル

CSVファイルを正常に変換・処理できない場合、FORMAT_ERRORファイルを作成します。

ファイル名の形式は以下のとおりです。

*_FORMAT_ERROR.csv

FORMAT_ERRORは、商品データの項目値のバリデーションエラーではなく、CSVファイルとして正常に解析できない場合に使用します。

処理結果ファイルの役割は以下のように整理できます。

エラー種類	出力ファイル
商品データ内容のエラー	`*_NG.csv`
CSVフォーマット・変換エラー	`*_FORMAT_ERROR.csv`

2-5-11. SFTP内部商品化の全体像

flowchart LR

    subgraph SUPPLIER["外部システム"]
        CREATE["商品情報作成"]
        EXPORT["CSV / ZIP出力"]
    end

    subgraph SFTP["SFTP公開エリア"]
        TO["ToJ2"]
        FROM["FromJ2"]
    end

    subgraph PROCESS["ジーニーシステム"]
        DETECT["ファイル検出"]
        DOWNLOAD["ファイル取得"]
        BACKUP["バックアップ"]
        REMOVE["元ファイル削除"]
        IMPORT["商品情報取込"]
        VALIDATE["バリデーション"]
        REGISTER["内部商品登録"]
        OUTPUT["結果ファイル生成"]
    end

    CREATE --> EXPORT
    EXPORT --> TO

    TO --> DETECT
    DETECT --> DOWNLOAD
    DOWNLOAD --> BACKUP
    BACKUP --> REMOVE
    REMOVE --> IMPORT
    IMPORT --> VALIDATE

    VALIDATE -->|"正常データ"| REGISTER
    VALIDATE -->|"NGデータ"| OUTPUT

    REGISTER --> OUTPUT
    OUTPUT --> FROM

2-5. 内部商品化（SFTP）のまとめ

内部商品化（SFTP）は、外部システムの商品情報をファイル連携によってジーニーシステムの内部商品として登録する仕組みです。

処理のポイントは以下のとおりです。

外部システムが商品情報CSVまたはZIPファイルをToJ2へ配置する。
ジーニーシステムが対象ファイルの存在を確認する。
対象ファイルをSFTP公開エリアから取得する。
取得したファイルをバックアップ領域へコピーする。
SFTP公開エリアから処理対象ファイルを削除する。
ジーニーシステムで内部商品登録を実行する。
内部商品化できないデータが存在する場合、エラーファイルを作成する。
処理結果をCHK、NG、FORMAT_ERRORの各ファイルとしてFromJ2へ配置する。

ディレクトリ構成は、以下のように整理されます。

外部システム
      │
      │ CSV / ZIP
      ▼
    ToJ2
      │
      ▼
ジーニーシステム
      │
      ├── ファイル取得
      ├── バックアップ
      ├── 内部商品登録
      └── バリデーション
      │
      ▼
   FromJ2
      │
      ├── *.CHK
      ├── *_NG.csv
      └── *_FORMAT_ERROR.csv

API連携方式が商品情報をAPI経由で逐次連携するのに対し、SFTP方式ではCSVまたはZIPファイルを使用して商品情報を一括連携します。

3-1. オーダー（発注）情報の連携

3-1-1. 概要

オーダー（発注）情報の連携では、カタログモールから販売システム管理サーバへ発注情報を連携します。

発注情報の登録には、OrderInput APIを使用します。

1つの注文に複数の明細が存在する場合は、Detailを繰り返して設定します。

発注情報には、主に以下の情報が含まれます。

注文番号・注文明細番号
依頼会社・依頼部門情報
依頼者情報
依頼日・注文日・希望納期
カタログ情報
サプライヤ情報
商品情報
注文単価・注文数量・注文金額
納入先情報
予備項目
納期回答登録APIのURL
出荷登録APIのURL

3-1-2. 前提条件

発注情報の連携には、OrderInput APIを使用します。

基本的な処理イメージは以下のとおりです。

flowchart LR

    subgraph J2SYS["J2システム（ジーニーラボ株式会社）"]
        USER["購入依頼者"]
        APPROVER["承認者"]
        J2["購買システム（J2）"]
        subgraph MALL["カタログモール（J2）"]
            ORDER["発注情報"]
            API["OrderInput"]
        end
    end

    subgraph EXT["お取引企業様"]
        SALES["販売管理システム"]
        ORDER_DATA["受注情報"]
    end

    USER -->|"購入依頼"| APPROVER
    APPROVER -->|"承認"| J2

    J2 --> ORDER
    ORDER --> API

    API -->|"発注情報登録"| SALES
    SALES --> ORDER_DATA

    SALES -->|"処理結果"| API

3-1-3. 処理シーケンス

オーダー情報の基本的な連携フローは以下のとおりです。

sequenceDiagram

    actor User as 購入依頼者
    actor Approver as 承認者

    participant J2 as 購買システム（J2）
    participant Mall as カタログモール（J2）
    participant Sales as 販売管理システム（お取引企業様）

    Note over J2,Mall: J2システム（ジーニーラボ株式会社）

    rect rgb(235, 245, 255)
        Note over User,J2: ① 購入依頼・承認
        User->>J2: 購入依頼
        J2->>Approver: 承認依頼

        Approver->>J2: 承認
    end

    rect rgb(235, 255, 235)
        Note over J2,Sales: ② 発注情報登録
        J2->>Mall: 発注情報連携

        Mall->>Sales: OrderInput<br/>発注情報登録

        Sales->>Sales: 発注情報受付・登録

        Sales-->>Mall: OrderInput Response<br/>処理結果・受信件数
    end

    rect rgb(255, 245, 220)
        Note over Mall: ③ 連携結果の記録
        Mall->>Mall: 連携結果を記録
    end

処理の流れは以下のとおりです。

購入依頼者が購入依頼を行います。
承認者による承認後、発注情報が生成されます。
発注情報がカタログモールへ連携されます。
カタログモールから販売システム管理サーバへOrderInputを送信します。
販売システム管理サーバは発注情報を受信し、登録処理を行います。
販売システム管理サーバは、処理結果および受信件数をレスポンスとして返却します。

3-1-4. API一覧

API名	内容
OrderInput	販売システム管理サーバへ発注情報を登録する

3-1-4-1. OrderInput（発注情報登録）

概要

OrderInputは、カタログモールから販売システム管理サーバへ発注情報を登録するためのAPIです。

複数の注文明細が存在する場合は、Detailを繰り返して設定します。

OrderInput
│
├── loginID
├── loginPWD
├── payloadID
├── timestamp
│
├── Detail
│   ├── 注文情報
│   ├── 依頼者情報
│   ├── 商品情報
│   ├── 金額情報
│   ├── 納入先情報
│   └── 予備項目
│
├── Detail
│   └── ...
│
├── sendCount
├── DeliverInputURL
├── ShipmentInputURL
└── SITE_KBN

リクエスト

基本情報

パラメータ名	必須	説明
loginID	○	販売システム管理サーバへのログインユーザID
loginPWD	○	販売システム管理サーバへのログインパスワード
payloadID	○	ユニークとなる識別子
timestamp	○	データ作成日時
Detail		発注明細情報。複数明細行がある場合は繰り返し設定
sendCount	○	送信件数
DeliverInputURL	○	カタログモールの納期回答登録APIを呼び出すURL
ShipmentInputURL	○	カタログモールの出荷登録APIを呼び出すURL
SITE_KBN		サイト区分。マスタ設定により送付可能

payloadID

payloadIDには、リクエストを一意に識別する値を設定します。

日付.プロセスID.ランダム数値.ホスト名

timestamp

データ作成日時を以下の形式で設定します。

YYYY-MM-DDThh:mm:ss-hh:mm(UTC)

Detail（発注明細情報）

注文管理情報

パラメータ名	必須	説明
division		区分
orderNumber	○	注文番号
orderDetailNumber	○	注文明細番号

division

値	内容
N	新規
U	更新
D	取消

divisionにより、対象の注文情報が新規登録、更新、取消のいずれであるかを識別します。

依頼会社・部門情報

パラメータ名	必須	説明
requestCompanyCode	○	依頼会社コード
requestCompanyName	○	依頼会社名
requestDepartmentCode	○	依頼部門コード
requestDepartmentName	○	依頼部門名

依頼者情報

パラメータ名	必須	説明
requestUserCode	○	依頼者コード
requestUserName	○	依頼者名
requestUserTelNumber	○	依頼者電話番号
requestUserMail		依頼者メールアドレス
comment		コメント

日付情報

パラメータ名	必須	説明
requestDate	○	依頼日（起票日）
orderDate	○	注文日（承認日）
expectationDeliveryDate	○	希望納期

希望納期について

バイヤー企業が最短納期を希望する場合は、expectationDeliveryDateを空白、つまり文字列長0で連携します。

通常の場合：
expectationDeliveryDate = 指定された希望納期

最短希望の場合：
expectationDeliveryDate = ""

課税区分

パラメータ名	必須	説明
taxClass		課税区分

taxClassの値

値	内容
0	課税（税込）
1	課税（税抜き）
2	非課税
3	免税
4	経過措置（税込）
5	経過措置（税抜き）
7	不課税
14	軽減課税（税込）
15	軽減課税（税抜き）

カタログ情報

パラメータ名	必須	説明
catalogCode	○	カタログコード
catalogName	○	カタログ名

サプライヤ情報

パラメータ名	必須	説明
SupplierCompanyCode	○	サプライヤ企業コード
SupplierCompanyName	○	サプライヤ名
SupplierPartID	○	サプライヤ品番

SupplierPartIDの設定

通常商品、送料、別途費用について、以下の形式でサプライヤ品番を設定します。

通常商品：
[productCd]

送料：
[ProductCD]_SOURYOU

別途費用：
[ProductCD]_SPECIAL

例：

通常商品：ABC001

送料：ABC001_SOURYOU

別途費用：ABC001_SPECIAL

メーカー情報

パラメータ名	必須	説明
makerName	○	メーカー名
makerPartID	○	メーカー型番

通貨情報

パラメータ名	必須	説明
currencyCode	○	通貨コード
currencyName	○	通貨名

注文金額情報

パラメータ名	必須	説明
orderUnitPrice	○	注文単価
orderQuantity	○	注文数量
orderAmount	○	注文金額

注文金額情報は、以下の3つの要素で構成されます。

注文単価 × 注文数量 → 注文金額

納入先情報

パラメータ名	必須	説明
deliveryDestinationCompanyName	○	納入先企業名
deliveryDestinationPostnumber	○	納入先郵便番号
deliveryDestinationAddress1	○	納入先住所1
deliveryDestinationAddress2		納入先住所2
deliveryDestinationAddress3		納入先住所3
deliveryDestinationDepartmentName	○	納入先部門名
deliveryDestinationContactUserName	○	納入先担当者
deliveryDestinationTelNumber		納入先電話番号
deliveryDestinationFaxNumber		納入先FAX番号

予備項目

optionalItem1からoptionalItem20までの予備項目を利用できます。

パラメータ名	用途
optionalItem1	予備項目1：仕入単価
optionalItem2	予備項目2：JANコード
optionalItem3	予備項目3
optionalItem4	予備項目4
optionalItem5	予備項目5
optionalItem6	予備項目6
optionalItem7	予備項目7
optionalItem8	予備項目8
optionalItem9	予備項目9
optionalItem10	予備項目10
optionalItem11	予備項目11
optionalItem12	予備項目12
optionalItem13	予備項目13
optionalItem14	予備項目14
optionalItem15	予備項目15
optionalItem16	予備項目16
optionalItem17	予備項目17
optionalItem18	予備項目18
optionalItem19	送料区分
optionalItem20	予備項目20

optionalItem19：送料区分

optionalItem19は、商品・送料・別途費用を識別するために使用します。

値	内容
0	商品
1	送料
2	別途費用分

sendCount

sendCountには、OrderInputで送信する明細件数を設定します。

Detail × 3件
↓
sendCount = 3

DeliverInputURL

DeliverInputURLには、販売システム管理サーバからカタログモールへ納期回答情報を登録する際に使用するAPIのURLを設定します。

OrderInput
    │
    └── DeliverInputURL
            │
            ▼
       納期回答登録API

このURLは、後続の納期回答情報の連携で使用されます。

ShipmentInputURL

ShipmentInputURLには、販売システム管理サーバからカタログモールへ出荷情報を登録する際に使用するAPIのURLを設定します。

OrderInput
    │
    └── ShipmentInputURL
            │
            ▼
         出荷登録API

このURLは、後続の出荷情報の連携で使用されます。

SITE_KBN

SITE_KBNはサイト区分を表します。

任意項目であり、マスタ設定により送付できます。

パラメータ名	必須	説明
SITE_KBN		サイト区分。マスタ設定により送付可能

OrderInput レスポンス

販売システム管理サーバは、発注情報の処理結果をレスポンスとして返却します。

レスポンス項目

パラメータ名	必須	説明
payloadID	○	リクエスト時のpayloadID
timestamp	○	リクエスト時のtimestamp
command	○	実行したAPIの名称
version	○	実行したAPIのバージョン
response	○	実行結果
error	条件付き	エラー結果
result		実行結果情報
result.receiveCount	○	受信件数

response

値	内容
success	成功
failure	失敗

response = failureの場合、error情報の設定が必須です。

error

パラメータ名	必須	説明
code	○	エラーコード
message	○	エラーメッセージ

receiveCount

receiveCountには、販売システム管理サーバが受信した件数を設定します。

例：

送信件数：
sendCount = 5

受信件数：
receiveCount = 5

ステータスコード一覧

code	文字列	説明
200	OK	正常終了
400	Bad Request	販売システム管理サーバ側でリクエストを受け付けられない場合
403	Forbidden	権限がない場合
450	Not Implemented	OrderInputの処理が実装されていない場合
500	Internal Server Error	販売システム管理サーバ側で内部エラーが発生した場合
560	Temporary Server Error	販売システム管理サーバの再起動、メンテナンス等で処理を受け付けられない場合

3-1. オーダー（発注）情報の連携まとめ

オーダー情報の連携は、カタログモールから販売システム管理サーバへ発注情報を送信するための仕組みです。

中心となるAPIはOrderInputです。

flowchart LR

    subgraph J2SYS["J2システム（ジーニーラボ株式会社）"]
        A["購入依頼"]
        B["承認"]
        C["発注確定"]
        D["カタログモール（J2）"]
        E["OrderInput"]
    end

    subgraph EXT["お取引企業様"]
        F["販売管理システム"]
        G["受注情報登録"]
        H["処理結果返却"]
    end

    A --> B
    B --> C
    C --> D
    D --> E
    E --> F
    F --> G
    G --> H
    H --> D

主なポイントは以下のとおりです。

発注情報はOrderInputを使用して販売システム管理サーバへ連携する。
複数の注文明細がある場合はDetailを繰り返して設定する。
divisionにより、新規・更新・取消を識別する。
商品、送料、別途費用はSupplierPartIDおよびoptionalItem19で識別できる。
希望納期が最短の場合は、expectationDeliveryDateを空文字で連携する。
後続処理で使用するDeliverInputURLとShipmentInputURLを発注情報とともに連携する。
販売システム管理サーバは、処理結果と受信件数receiveCountをレスポンスとして返却する。

この連携により、ジーニー2.0で確定した発注情報を、カタログモール経由で取引先企業側の販売システムへ連携できます。

4. 共通コード・マスタ定義

本章では、商品情報連携、内部商品化、EDI連携などで共通して利用するコードおよび識別ルールについて説明します。

主な共通定義は以下のとおりです。

単位コード
別途費用の識別・連携ルール

4-1. 単位コード

4-1-1. 概要

商品情報CSV等の以下の項目には、本仕様で定義された単位コードを設定します。

購入単位コード
単位コード

商品情報を連携する際は、商品の販売形態・数量単位に対応するコードを設定してください。

4-1-2. 単位コード一覧

単位コード	単位
1	個
2	箱
3	リットル
4	パック
5	本
6	セット
7	巻
8	缶
9	脚
10	冊
11	式
12	組
13	束
14	ダース
15	袋
16	台
17	丁
18	枚
19	ケース
20	グラム
21	キログラム
22	立方メートル
23	メートル
24	包み
25	ロール
26	ミリリットル／cc
27	着
28	リール
29	足
30	部
31	双
32	シート
33	ドラム
34	ユニット
35	ロット
36	反
37	匹
38	コマ
39	件
40	文字
41	ヶ月
42	日
43	週
44	回
45	平方メートル
46	バイト
47	ビット
48	メガバイト
49	テラバイト
50	人
51	架
52	月
53	面
54	EA
55	FT
56	M
57	KIT
58	PKG
59	BOX
60	LIN
61	PAC
62	PC
63	PCS
64	PR
65	SET
66	カートン
91	人月
92	人日
93	時間
99	その他

4-1-3. 単位コードの利用イメージ

商品情報では、商品の販売形態に応じて適切な単位コードを設定します。

商品・サービス例	単位コード	単位
ボールペン1本	5	本
コピー用紙1箱	2	箱
PC1台	16	台
ソフトウェア導入一式	11	式
コンサルティング1人月	91	人月
作業1人日	92	人日
作業3時間	93	時間
その他	99	その他

flowchart LR

    PRODUCT["商品・サービス"]

    TYPE{"販売・契約単位"}

    A["物品"]
    B["数量"]
    C["役務・サービス"]
    D["その他"]

    UNIT_A["個・箱・本・台<br/>セット・ケース等"]
    UNIT_B["g・kg・L・m<br/>㎡・㎥等"]
    UNIT_C["人月・人日・時間"]
    UNIT_D["その他：99"]

    PRODUCT --> TYPE

    TYPE --> A
    TYPE --> B
    TYPE --> C
    TYPE --> D

    A --> UNIT_A
    B --> UNIT_B
    C --> UNIT_C
    D --> UNIT_D

4-2. 別途費用の定義

4-2-1. 概要

商品本体価格とは別に、送料やその他の追加費用が発生する場合があります。

本仕様では、以下の情報を使用して商品、送料、別途費用を識別します。

postageFlag
SupplierPartID
optionalItem19

各APIの用途に応じて、これらの値を設定します。

4-2-2. postageFlag

postageFlagは、商品に別途費用が発生するかどうかを示す項目です。

仕様上、利用するAPIによって定義される値が異なります。

基本的な値

値	内容
0	無し
1	別途費用
2	単独購入の場合、パンチアウト連携による購入が必要

1：別途費用の場合、以下のような処理を想定します。

受注時に単価を決定する
注文時に納品先などの条件に応じて別途費用を取得する

flowchart TD

    ITEM["商品"]

    FLAG{"postageFlag"}

    NORMAL["0：無し"]
    SPECIAL["1：別途費用"]
    PUNCHOUT["2：単独購入"]

    ORDER["通常の商品価格で処理"]

    CALC["受注時または注文時に<br/>別途費用を決定"]

    PO["パンチアウト連携で購入"]

    ITEM --> FLAG

    FLAG --> NORMAL
    FLAG --> SPECIAL
    FLAG --> PUNCHOUT

    NORMAL --> ORDER
    SPECIAL --> CALC
    PUNCHOUT --> PO

4-2-3. SupplierPartIDによる識別

発注情報を連携するOrderInputでは、通常商品、送料、別途費用をSupplierPartIDの命名ルールで識別します。

種類	SupplierPartID
通常商品	`[ProductCD]`
送料	`[ProductCD]_SOURYOU`
別途費用	`[ProductCD]_SPECIAL`

例

商品コードが以下の場合、

ABC001

連携されるサプライヤ品番は以下のようになります。

通常商品：
ABC001

送料：
ABC001_SOURYOU

別途費用：
ABC001_SPECIAL

関係イメージ

flowchart LR

    PRODUCT["商品<br/>ABC001"]

    ITEM["商品明細<br/>ABC001"]
    SHIPPING["送料明細<br/>ABC001_SOURYOU"]
    SPECIAL["別途費用明細<br/>ABC001_SPECIAL"]

    PRODUCT --> ITEM
    PRODUCT --> SHIPPING
    PRODUCT --> SPECIAL

4-2-4. optionalItem19による明細区分

OrderInputでは、optionalItem19を使用して明細の種類を識別します。

値	内容
0	商品
1	送料
2	別途費用分

識別イメージ

商品本体
├── SupplierPartID：ABC001
└── optionalItem19：0

送料
├── SupplierPartID：ABC001_SOURYOU
└── optionalItem19：1

別途費用
├── SupplierPartID：ABC001_SPECIAL
└── optionalItem19：2

4-2-5. 商品・送料・別途費用の対応関係

明細種類	SupplierPartID	optionalItem19
商品	`[ProductCD]`	0
送料	`[ProductCD]_SOURYOU`	1
別途費用	`[ProductCD]_SPECIAL`	2

4. 共通コード・マスタ定義まとめ

共通コード・マスタ定義は、各APIやファイル連携で使用される値を統一するための共通ルールです。

単位コード

商品の販売単位、数量単位、サービスの契約単位などをコードで統一します。

代表的な例は以下のとおりです。

1  ：個
2  ：箱
5  ：本
16 ：台
21 ：キログラム
23 ：メートル
50 ：人
91 ：人月
92 ：人日
93 ：時間
99 ：その他

別途費用

商品価格以外の費用については、以下の情報を組み合わせて識別します。

postageFlag
    │
    ├── 別途費用の有無・処理方式を判定
    │
SupplierPartID
    │
    ├── 商品       ：ProductCD
    ├── 送料       ：ProductCD_SOURYOU
    └── 別途費用   ：ProductCD_SPECIAL
    │
optionalItem19
    │
    ├── 0：商品
    ├── 1：送料
    └── 2：別途費用

これらの共通定義を利用することで、商品検索、内部商品化、発注情報連携などの各機能で、単位情報および追加費用情報を一貫した形式で取り扱うことができます。

5. 補足資料

本章では、カタログモール外部連携仕様を理解するための補足情報について説明します。

補足資料は、以下の4つの内容で構成されます。

バックグラウンド検索
お客様ご利用画面とのマッピング
納期回答・出荷情報の処理フロー
別途費用のAPI

5-1. バックグラウンド検索

5-1-1. 概要

本資料は、バックグラウンドキーワード検索について、外部カタログ側の想定処理を含めた処理フローを説明するものです。

バックグラウンドキーワード検索では、利用ユーザがカタログモール上で検索を実行すると、カタログモールから外部カタログへ検索要求を送信します。

外部カタログでは商品検索を行い、まず検索件数を返却した後、検索された商品情報を非同期でカタログモールへ送信します。

5-1-2. 関係システム

バックグラウンド検索には、以下の3者が関係します。

アクター・システム	主な役割
利用ユーザ	検索条件を入力し、商品検索を実行する
カタログモール	検索要求を外部カタログへ送信し、取得した商品情報を検索結果として表示する
外部カタログ	検索条件に基づいて商品を検索し、商品件数および商品情報を返却する

5-1-3. 基本処理フロー

sequenceDiagram
    actor User as 購入依頼者
    participant Mall as カタログモール（J2）
    participant Catalog as 外部カタログサーバ（お取引企業様）

    rect rgb(235, 245, 255)
        Note over User,Catalog: ① 検索要求・件数取得
        User->>Mall: 検索条件入力
        User->>Mall: 商品検索実行

        Mall->>Catalog: KeywordSearch（検索条件送信）
        Note right of Catalog: 商品検索処理

        Catalog-->>Mall: 検索件数返却（itemCount）
    end

    rect rgb(235, 255, 235)
        Note over Mall,Catalog: ② 商品情報の非同期・分割送信
        loop returnCount単位
            Catalog->>Mall: KeywordItemAdd（商品情報送信）
            Mall-->>Catalog: 処理結果
        end

        Catalog->>Mall: KeywordItemAdd<br/>finalFlag = 9（送信完了）
    end

    rect rgb(255, 245, 220)
        Note over Mall,User: ③ 検索結果の統合・表示
        Mall->>Mall: 検索結果を統合
        Mall-->>User: 商品検索結果一覧表示
    end

5-1-4. 処理のポイント

バックグラウンド検索の処理は、以下の2段階で構成されます。

第1段階：検索要求と件数取得

カタログモールはKeywordSearchを使用して、外部カタログへ検索条件を送信します。

外部カタログは商品検索を実行し、検索対象となった商品件数を返却します。

第2段階：商品情報の非同期送信

検索対象の商品情報は、KeywordItemAddを使用して外部カタログからカタログモールへ送信します。

大量の商品情報が存在する場合は、returnCountで指定された件数単位で分割して送信します。

最後の商品情報送信時には、以下を設定します。

finalFlag = 9

これにより、カタログモールはすべての商品情報の受信が完了したことを判断できます。

5-2. お客様ご利用画面とのマッピング

本資料では、APIで取得した商品情報が、カタログモールのお客様利用画面上でどのように使用されるかを整理します。

対象画面は以下の2つです。

商品検索結果一覧画面
商品詳細画面

5-2-1. 商品検索結果一覧画面

概要

商品検索結果一覧画面には、バックグラウンドキーワード検索で取得した商品情報を表示します。

使用するAPIは以下のとおりです。

KeywordSearch
KeywordItemAdd

実際の画面表示項目には、主にKeywordItemAddで取得した商品情報を使用します。

取得項目一覧

No.	取得API	取得項目	画面上の意味
①	KeywordItemAdd	`largeCategoryname`	大分類名
②	KeywordItemAdd	`middleCategoryname`	中分類名
③	KeywordItemAdd	`smallCategoryname`	小分類名
④	KeywordItemAdd	`itemName`	商品名
⑤	KeywordItemAdd	`SupplierPartID`	サプライヤ品番
⑥	KeywordItemAdd	`makerName`	メーカー名称
⑦	KeywordItemAdd	`makerModelID`	メーカー型番
⑧	KeywordItemAdd	`supplierName`	サプライヤ名
⑨	KeywordItemAdd	`standardDeliveryTime`	標準納期
⑩	KeywordItemAdd	`itemURL1`	商品画像
⑪	KeywordItemAdd	`saleUnitPrice`	販売単価
⑫	KeywordItemAdd	`greenItem`	グリーン規格
⑬	KeywordItemAdd	`postageFlag`	送料
⑭	KeywordItemAdd	`returnProprietyFlag`	返品可否

データと画面の関係

flowchart LR

    SEARCH["KeywordSearch<br/>検索要求"]

    ITEM["KeywordItemAdd<br/>商品情報取得"]

    subgraph RESULT["商品検索結果一覧画面"]
        CATEGORY["カテゴリ"]
        PRODUCT["商品名・品番"]
        MAKER["メーカー"]
        SUPPLIER["サプライヤ"]
        DELIVERY["標準納期"]
        IMAGE["商品画像"]
        PRICE["販売単価"]
        GREEN["グリーン規格"]
        SHIPPING["送料"]
        RETURN["返品可否"]
    end

    SEARCH --> ITEM

    ITEM --> CATEGORY
    ITEM --> PRODUCT
    ITEM --> MAKER
    ITEM --> SUPPLIER
    ITEM --> DELIVERY
    ITEM --> IMAGE
    ITEM --> PRICE
    ITEM --> GREEN
    ITEM --> SHIPPING
    ITEM --> RETURN

5-2-2. 商品詳細画面

概要

商品詳細画面では、ItemSearchで取得した商品情報を表示します。

ただし、単独パンチアウトのみの場合には、PunchOutOrderMessageで取得した項目を使用して画面表示を行います。

通常：
ItemSearch
    ↓
商品詳細画面

単独パンチアウトのみ：
PunchOutOrderMessage
    ↓
商品詳細画面

取得項目一覧

No.	取得API	取得項目	画面上の意味
①	ItemSearch	`itemName`	商品名
②	ItemSearch	`makerName`	メーカー名称
③	ItemSearch	`makerPartID`	メーカー品番
④	ItemSearch	`supplierName`	サプライヤ名
⑤	ItemSearch	`standardDeliveryTime`	標準納期
⑥	ItemSearch	`quantityPerCarton`	数量単位入数
⑦	ItemSearch	`minOrderQuantity`	最低発注数
⑧	ItemSearch	`orderLot`	発注ロット
⑨	ItemSearch	`regularPrice`	定価
⑩	ItemSearch	`saleUnitPrice`	販売単価
⑪	ItemSearch	`purchaseUnitQuantityPerCarton`	購入単位入数
⑫	ItemSearch	`itemURL1`	商品画像1
⑬	ItemSearch	`itemURL2`	商品画像2
⑭	ItemSearch	`itemURL3`	商品画像3
⑮	ItemSearch	`itemSummary`	商品概要
⑯	ItemSearch	`itemSpec1`、`itemSpec2`、`itemSpec3`	商品仕様1～3

商品詳細画面の情報構成

---
title: 商品詳細画面の情報構成
---
flowchart TD

    API["ItemSearch"]

    API --> BASIC["基本情報"]
    API --> ORDER["注文条件"]
    API --> PRICE["価格情報"]
    API --> IMAGE["画像情報"]
    API --> DESCRIPTION["商品説明"]

    BASIC --> B1["商品名"]
    BASIC --> B2["メーカー"]
    BASIC --> B3["メーカー品番"]
    BASIC --> B4["サプライヤ"]
    BASIC --> B5["標準納期"]

    ORDER --> O1["数量単位入数"]
    ORDER --> O2["最低発注数"]
    ORDER --> O3["発注ロット"]
    ORDER --> O4["購入単位入数"]

    PRICE --> P1["定価"]
    PRICE --> P2["販売単価"]

    IMAGE --> I1["商品画像1"]
    IMAGE --> I2["商品画像2"]
    IMAGE --> I3["商品画像3"]

    DESCRIPTION --> D1["商品概要"]
    DESCRIPTION --> D2["商品仕様1～3"]

    classDef root fill:#eceff1,stroke:#546e7a,stroke-width:1px,color:#263238
    classDef basic fill:#e3f2fd,stroke:#1e88e5,stroke-width:1px,color:#0d47a1
    classDef order fill:#e8f5e9,stroke:#43a047,stroke-width:1px,color:#1b5e20
    classDef price fill:#fff3e0,stroke:#fb8c00,stroke-width:1px,color:#e65100
    classDef image fill:#f3e5f5,stroke:#8e24aa,stroke-width:1px,color:#4a148c
    classDef description fill:#fffde7,stroke:#fbc02d,stroke-width:1px,color:#f57f17

    class API root
    class BASIC,B1,B2,B3,B4,B5 basic
    class ORDER,O1,O2,O3,O4 order
    class PRICE,P1,P2 price
    class IMAGE,I1,I2,I3 image
    class DESCRIPTION,D1,D2 description

5-3. 納期回答・出荷情報の処理フロー

5-3-1. 概要

本資料では、納期回答情報および出荷情報をカタログモールが受信した際の処理について説明します。

処理は以下の2パターンに分かれます。

正常系
異常系

納期回答情報と出荷情報は、基本的に同じ考え方で処理されます。

5-3-2. 正常系

正常系では、受信したすべての明細について注文データのステータス更新が可能な場合、対象データを正常に受け付けます。

sequenceDiagram

    participant Supplier as 販売管理システム（お取引企業様）
    participant Mall as カタログモール（J2）

    rect rgb(232, 245, 233)
        Note over Supplier,Mall: 正常系：全明細を正常受付 → COMMIT
        Supplier->>Mall: 納期回答／出荷情報送信

        Mall->>Mall: 電文チェック

        loop 明細単位
            Mall->>Mall: 対象注文の確認（更新可否）
            Note right of Mall: ステータス更新
        end

        Mall->>Mall: トランザクション確定（COMMIT）

        Mall-->>Supplier: success
    end

正常系の考え方

1つの電文
├── 明細1：更新可能
├── 明細2：更新可能
└── 明細3：更新可能

        ↓

全明細を正常受付
        ↓
COMMIT

5-3-3. 異常系

カタログモールが納期回答または出荷情報を受信した際に、注文データのステータスを更新できない明細を検出した場合、処理を中断してロールバックします。

重要な点は、エラーとなった明細のみを除外するのではなく、同一電文に含まれるすべての明細をロールバックし、電文全体を受け付けないことです。

この動作は、以下の両方に共通します。

納期回答情報
出荷情報

異常系の処理イメージ

sequenceDiagram

    participant Supplier as 販売管理システム（お取引企業様）
    participant Mall as カタログモール（J2）

    rect rgb(255, 235, 235)
        Note over Supplier,Mall: 異常系：1件でも更新不可 → 全明細ROLLBACK
        Supplier->>Mall: 納期回答／出荷情報送信

        Mall->>Mall: 明細1確認 → 更新可能
        Mall->>Mall: 明細2確認 → 更新不可

        Note over Mall: 処理中断

        Mall->>Mall: 全明細をROLLBACK<br/>（部分受付はしない）

        Mall-->>Supplier: failure
    end

ロールバックの考え方

1つの電文
├── 明細1：OK
├── 明細2：OK
├── 明細3：NG
└── 明細4：未処理

        ↓

明細3で更新不可を検出

        ↓

処理中断

        ↓

明細1、2を含めて
全明細ROLLBACK

        ↓

電文全体を受付不可

正常系・異常系比較

状態	処理結果
全明細が更新可能	全明細を受付し、処理を確定
1件でも更新不可	処理を中断
更新不可検出時	同一電文内の全明細をロールバック
部分受付	行わない
対象	納期回答・出荷情報の両方

5-4. 別途費用のAPI

5-4-1. 概要

別途費用が必要な商品について、納品先情報などの条件をもとに外部カタログから別途費用を取得します。

別途費用の取得には、GetAdditionalCost APIを使用します。

API名	内容
GetAdditionalCost	納品先情報をもとに別途費用を取得する

5-4-2. 処理フロー

sequenceDiagram

    actor User as 購入依頼者
    participant Mall as カタログモール（J2）
    participant Catalog as 外部カタログサーバ（お取引企業様）

    rect rgb(235, 245, 255)
        Note over User,Mall: ① 商品選択・注文条件入力
        User->>Mall: 商品選択
        User->>Mall: 注文数量・納品先指定
    end

    rect rgb(235, 255, 235)
        Note over Mall,Catalog: ② 別途費用の取得
        Mall->>Catalog: GetAdditionalCost<br/>（商品・数量・納品先情報を送信）

        Note right of Catalog: 商品・数量・納品先情報から<br/>別途費用を計算

        Catalog-->>Mall: AdditionalCost（別途費用）
    end

    rect rgb(255, 245, 220)
        Note over Mall,User: ③ 価格反映・表示
        Mall->>Mall: 別途費用を反映

        Mall-->>User: 商品価格＋別途費用を表示
    end

5-4-3. API一覧

API名	内容
GetAdditionalCost（別途費用取得）	納品先より別途費用を取得する

5-4-4. GetAdditionalCost

リクエスト

パラメータ名	必須	説明	型・桁数
loginID	○	外部カタログサーバへのログインユーザID	-
loginPWD	○	外部カタログサーバへのログインパスワード	-
payloadID	○	ユニークとなる識別子	-
timestamp	○	データ作成日時	-
catalogCode	○	カタログコード	文字数100
companyCode	○	会社コード	文字数100
topLevelDepartmentCode	○	最上位組織コード	文字数100
departmentCode		部門コード。設定により送付可能	文字数100
SupplierPartID	○	サプライヤ品番	文字数100
orderQuantity	○	注文数量	数値型（15,5）
deliveryDestinationCompanyName	○	納入先企業名	文字数500
deliveryDestinationPostnumber	○	納入先郵便番号	文字数20
deliveryDestinationAddress1	○	納入先住所1	文字数1000
deliveryDestinationAddress2		納入先住所2	文字数1000
deliveryDestinationAddress3		納入先住所3	文字数1000
deliveryDestinationDepartmentName		納入先部門名	文字数500
deliveryDestinationContactUserName		納入先担当者	文字数500
deliveryDestinationTelNumber		納入先電話番号	文字数100
deliveryDestinationFaxNumber		納入先FAX番号	文字数100

payloadID

payloadIDは、リクエストを一意に識別する値です。

形式は以下のとおりです。

日付.プロセスID.ランダム数値.ホスト名

timestamp

データ作成日時を以下の形式で設定します。

YYYY-MM-DDThh:mm:ss-hh:mm(UTC)

別途費用計算に使用する主な情報

GetAdditionalCostでは、主に以下の情報を外部カタログへ送信します。

flowchart LR

    PRODUCT["商品情報"]
    QUANTITY["注文数量"]
    COMPANY["会社・組織情報"]
    DELIVERY["納入先情報"]

    API["GetAdditionalCost"]

    COST["AdditionalCost<br/>別途費用"]

    PRODUCT --> API
    QUANTITY --> API
    COMPANY --> API
    DELIVERY --> API

    API --> COST

主な計算条件は以下のように整理できます。

対象商品
注文数量
購入会社
最上位組織
部門
納入先企業
郵便番号
納入先住所

5-4-5. レスポンス

パラメータ名	必須	説明
payloadID	○	リクエスト時のpayloadID
timestamp	○	リクエスト時のtimestamp
command	○	実行したAPIの名称
version	○	実行したAPIのバージョン
catalogCode	○	リクエスト時のcatalogCode
response	○	実行結果
error	条件付き	エラー結果
result		実行結果
result.AdditionalCost	○	別途費用

response

値	内容
success	成功
failure	失敗

response = failureの場合、error情報を設定します。

error

パラメータ名	必須	説明
code	○	エラーコード
message	○	エラーメッセージ

AdditionalCost

AdditionalCostには、算出された別途費用を設定します。

項目	内容
パラメータ	`AdditionalCost`
必須	○
説明	別途費用
データ型	数値型（15,5）

処理イメージ：

商品：
SupplierPartID = ABC001

注文数量：
orderQuantity = 10

納品先：
東京都〇〇区...

        ↓

GetAdditionalCost

        ↓

AdditionalCost = 算出された別途費用

5-4-6. ステータスコード

code	文字列	説明
200	OK	正常終了
400	Bad Request	外部カタログサーバ側でリクエストを受け付けられない場合
401	Unauthorized	認証できない場合
403	Forbidden	権限がない場合
450	Not Implemented	対象API処理が実装されていない場合
500	Internal Server Error	外部カタログサーバ側で内部エラーが発生した場合
560	Temporary Server Error	サーバ再起動・メンテナンス等で一時的に処理を受け付けられない場合

5. 補足資料まとめ

補足資料では、外部カタログ連携を理解するうえで重要な4つの補助的な処理・対応関係を説明しています。

flowchart TB

    SUPPLEMENT["補足資料"]

    BG["5-1<br/>バックグラウンド検索"]
    UI["5-2<br/>画面とのマッピング"]
    EDI["5-3<br/>納期回答・出荷処理"]
    COST["5-4<br/>別途費用API"]

    SUPPLEMENT --> BG
    SUPPLEMENT --> UI
    SUPPLEMENT --> EDI
    SUPPLEMENT --> COST

    BG --> BG1["KeywordSearch"]
    BG --> BG2["KeywordItemAdd"]

    UI --> UI1["検索結果一覧"]
    UI --> UI2["商品詳細"]

    EDI --> EDI1["正常系：COMMIT"]
    EDI --> EDI2["異常系：全件ROLLBACK"]

    COST --> COST1["GetAdditionalCost"]
    COST1 --> COST2["AdditionalCost"]

    classDef root fill:#eceff1,stroke:#546e7a,stroke-width:1px,color:#263238
    classDef bg fill:#e3f2fd,stroke:#1e88e5,stroke-width:1px,color:#0d47a1
    classDef ui fill:#f3e5f5,stroke:#8e24aa,stroke-width:1px,color:#4a148c
    classDef edi fill:#fff3e0,stroke:#fb8c00,stroke-width:1px,color:#e65100
    classDef success fill:#e8f5e9,stroke:#43a047,stroke-width:1px,color:#1b5e20
    classDef danger fill:#ffebee,stroke:#e53935,stroke-width:1px,color:#b71c1c
    classDef cost fill:#fffde7,stroke:#fbc02d,stroke-width:1px,color:#f57f17

    class SUPPLEMENT root
    class BG,BG1,BG2 bg
    class UI,UI1,UI2 ui
    class EDI edi
    class EDI1 success
    class EDI2 danger
    class COST,COST1,COST2 cost

各補足資料の要点は以下のとおりです。

セクション	要点
5-1. バックグラウンド検索	検索要求と商品情報取得を分離し、商品情報を非同期・分割で取得する
5-2. 画面マッピング	APIの各商品項目が検索結果一覧画面・商品詳細画面のどこで使用されるかを定義する
5-3. 納期回答・出荷処理	1件でも更新不可の明細がある場合、同一電文の全明細をロールバックする
5-4. 別途費用API	商品・注文数量・納品先などを条件として`GetAdditionalCost`で別途費用を取得する

6. API・データサンプル

6-1. 概要

本章では、カタログモールと外部カタログシステムおよび販売管理システム間で使用するAPI・データ電文のサンプルを示します。

サンプルは、以下の11種類です。

No.	サンプル	形式	主な用途
1	PunchOutSetUpRequest	XML / cXML	外部カタログへの接続要求
2	PunchOutSetUpResponse	XML / cXML	外部カタログ接続結果
3	PunchOutOrderMessage	XML / cXML	選択商品のカート返却
4	KeywordSearch	JSON	バックグラウンドキーワード検索
5	KeywordItemAdd	JSON	検索商品情報の非同期送信
6	ItemSearch	JSON	商品情報検索・最新情報取得
7	OrderInput	JSON	発注情報登録
8	DeliverInput	JSON	納期回答情報登録
9	ShipmentInput	JSON	出荷情報登録
10	GetRegistItem	JSON	内部商品化対象件数取得
11	RegistItemAdd	JSON	内部商品情報登録

6-2. サンプル利用時の共通注意事項

仕様書のサンプルシートには、以下の共通注意事項があります。

XML / cXMLサンプル

サンプルは説明用である。
実際の電文はXML仕様に準拠して作成する。
サンプルと本文仕様に差異がある場合は、本文仕様を正とする。

JSONサンプル

RequestおよびResponseの表記は説明用であり、実際の電文には含めない。
サンプル内の改行は説明用である。
実際の電文では改行またはタブは不要である。
複数明細を送信する場合は、対象配列内にデータを連続して設定する。
各データはカンマ,で区切る。
最終データの最終項目にはカンマを付けない。
値が存在しない項目や予備項目についても、仕様に従って電文上に生成する。
サンプルと本文仕様に差異がある場合は、本文仕様を正とする。

6-3. PunchOutSetUpRequest サンプル

6-3-1. 用途

PunchOutSetUpRequestは、カタログモールから外部カタログサイトへ接続・認証を要求するためのcXML電文です。

主に以下の情報を送信します。

送信元情報
送信先情報
Sender認証情報
BuyerCookie
会社コード
最上位組織コード
サイト区分
CheckOut後の戻り先URL

6-3-2. サンプル構造

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>

<cXML
    version="1.2.014"
    payloadID="20220202080127.99999.12718.catalogmall"
    timestamp="2022-02-02T08:01:27+09:00">

    <Header>

        <From>
            <Credential domain="DUNS">
                <Identity>00000000</Identity>
                <SharedSecret/>
            </Credential>
        </From>

        <To>
            <Credential domain="DUNS">
                <Identity>99999999</Identity>
                <SharedSecret/>
            </Credential>
        </To>

        <Sender>
            <Credential domain="NetworkId">
                <Identity>ABCDEF</Identity>
                <SharedSecret>********</SharedSecret>
            </Credential>

            <UserAgent>CatalogMall</UserAgent>
        </Sender>

    </Header>

    <Request>

        <PunchOutSetupRequest operation="create">

            <BuyerCookie>
                20220202080127.99999.12718.catalogmall
            </BuyerCookie>

            <Extrinsic name="companyCode">
                jn-sol
            </Extrinsic>

            <Extrinsic name="topLevelDepartmentCode">
                DM10
            </Extrinsic>

            <Extrinsic name="SITE_KBN">
                Jienielab
            </Extrinsic>

            <BrowserFormPost>
                <URL>
                    CheckOut時の送信先URL
                </URL>
            </BrowserFormPost>

        </PunchOutSetupRequest>

    </Request>

</cXML>

6-3-3. 処理イメージ

sequenceDiagram
    participant Mall as カタログモール
    participant Catalog as 外部カタログ

    rect rgb(235, 245, 255)
        Note over Mall,Catalog: 接続・認証
        Mall->>Catalog: PunchOutSetUpRequest

        Note right of Catalog: Identity確認
        Note right of Catalog: SharedSecret確認
        Note right of Catalog: 利用企業・組織確認

        Catalog-->>Mall: PunchOutSetUpResponse
    end

6-4. PunchOutSetUpResponse サンプル

6-4-1. 用途

PunchOutSetUpResponseは、外部カタログサイトが接続・認証結果をカタログモールへ返却する電文です。

正常時には、外部カタログの遷移先URLを返却します。

6-4-2. 正常レスポンス例

<?xml version="1.0" encoding="UTF-8"?>

<cXML
    payloadID="20220202080127.99999.12718.catalogmall"
    timestamp="2022-02-02T08:01:27+09:00"
    xml:lang="ja_JP">

    <Response>

        <Status
            code="200"
            text="OK"/>

        <PunchOutSetupResponse>

            <StartPage>
                <URL>
                    https://test.supplier.example/Main
                </URL>
            </StartPage>

        </PunchOutSetupResponse>

    </Response>

</cXML>

6-4-3. エラーレスポンス例

<?xml version="1.0" encoding="UTF-8"?>

<cXML
    payloadID="20220202080127.99999.12718.catalogmall"
    timestamp="2022-02-02T08:01:27+09:00"
    xml:lang="ja_JP">

    <Response>

        <Status
            code="401"
            text="Unauthorized"/>

    </Response>

</cXML>

6-5. PunchOutOrderMessage サンプル

6-5-1. 用途

PunchOutOrderMessageは、外部カタログサイトで選択した商品情報をカタログモールへ返却するcXML電文です。

1つまたは複数の商品情報をItemInとして送信します。

6-5-2. 基本構造

<cXML>

    <Header>
        <From>
            <Credential domain="DUNS">
                <Identity>送信元ID</Identity>
            </Credential>
        </From>

        <To>
            <Credential domain="DUNS">
                <Identity>送信先ID</Identity>
            </Credential>
        </To>

        <Sender>
            <Credential domain="NetworkId">
                <Identity>SenderID</Identity>
            </Credential>

            <UserAgent>catalogmall 1.0</UserAgent>
        </Sender>
    </Header>

    <Message>

        <PunchOutOrderMessage>

            <BuyerCookie>
                BuyerCookie
            </BuyerCookie>

            <PunchOutOrderMessageHeader
                operationAllowed="create">

                <Total>
                    <Money currency="JPY">
                        合計金額
                    </Money>
                </Total>

            </PunchOutOrderMessageHeader>

            <ItemIn quantity="1">

                <ItemID>
                    <SupplierPartID>
                        サプライヤ品番
                    </SupplierPartID>
                </ItemID>

                <ItemDetail>

                    <UnitPrice>
                        <Money currency="JPY">
                            販売単価
                        </Money>
                    </UnitPrice>

                    <Description xml:lang="ja">
                        商品説明
                        <ShortName>
                            商品名
                        </ShortName>
                    </Description>

                    <UnitOfMeasure>
                        単位
                    </UnitOfMeasure>

                    <ManufacturerPartID>
                        メーカー型番
                    </ManufacturerPartID>

                    <ManufacturerName>
                        メーカー名
                    </ManufacturerName>

                    <LeadTime>
                        標準納期
                    </LeadTime>

                    <!-- 商品属性 -->
                    <Extrinsic name="SupplierCode"/>
                    <Extrinsic name="SupplierName"/>
                    <Extrinsic name="itemSummary"/>
                    <Extrinsic name="itemSpec1"/>
                    <Extrinsic name="itemSpec2"/>
                    <Extrinsic name="itemSpec3"/>

                    <!-- 単位情報 -->
                    <Extrinsic name="purchaseUnitCode"/>
                    <Extrinsic name="purchaseUnitName"/>
                    <Extrinsic name="purchaseUnitQuantityPerCarton"/>
                    <Extrinsic name="quantityUnitCode"/>
                    <Extrinsic name="quantityUnitName"/>
                    <Extrinsic name="quantityPerCarton"/>

                    <!-- カテゴリ -->
                    <Extrinsic name="largeCategorycode"/>
                    <Extrinsic name="largeCategoryname"/>
                    <Extrinsic name="middleCategorycode"/>
                    <Extrinsic name="middleCategoryname"/>
                    <Extrinsic name="smallCategorycode"/>
                    <Extrinsic name="smallCategoryname"/>

                    <!-- その他 -->
                    <Extrinsic name="greenItem"/>
                    <Extrinsic name="taxClass"/>
                    <Extrinsic name="postageFlag"/>
                    <Extrinsic name="regularPrice"/>
                    <Extrinsic name="orderLot"/>
                    <Extrinsic name="minOrderQuantity"/>
                    <Extrinsic name="casNo"/>

                    <!-- 予備項目 -->
                    <Extrinsic name="optionalItem1"/>
                    <!-- optionalItem2 ～ optionalItem19 -->
                    <Extrinsic name="optionalItem20"/>

                </ItemDetail>

            </ItemIn>

        </PunchOutOrderMessage>

    </Message>

</cXML>

6-6. KeywordSearch サンプル

6-6-1. 用途

KeywordSearchは、カタログモールから外部カタログへ検索条件を送信するAPIです。

レスポンスでは、検索対象となった商品件数を返却します。

商品情報そのものは、後続のKeywordItemAddで非同期送信されます。

6-6-2. Request構造例

{
  "loginID": "ABCDEF",
  "loginPWD": "********",
  "payloadID": "20220303083930.99999.13170.catalogmall",
  "timestamp": "2022-03-03T08:39:30+09:00",
  "catalogCode": "1234",
  "companyCode": "COMPANY001",
  "topLevelDepartmentCode": "DEPT001",

  "freeword": "検索キーワード",
  "casNo": "",
  "makerModelID": "",
  "makerName": "",
  "greenItem": "",
  "sortType": "0",
  "excludeKeyword": "",

  "keywordItemAddURL": "KeywordItemAddの送信先",
  "firstReturnCount": 50,
  "maxReturnCount": 500,
  "returnCount": 100
}

6-6-3. Response構造例

{
  "payloadID": "20220303083930.99999.13170.catalogmall",
  "timestamp": "2022-03-03T08:39:30+09:00",
  "command": "KeywordSearch",
  "version": "1.0",
  "catalogCode": "1234",
  "response": "success",
  "error": {
    "code": 200,
    "message": "OK"
  },
  "result": {
    "itemCount": 500
  }
}

6-7. KeywordItemAdd サンプル

6-7-1. 用途

KeywordItemAddは、KeywordSearchで検索された商品情報を外部カタログからカタログモールへ非同期送信するAPIです。

商品情報が複数件ある場合は、itemIN配列内に複数の商品を設定します。

6-7-2. Request構造

{
  "loginID": "JIENIE",
  "payloadID": "20210401.12345.6789.catalogmall.com",
  "timestamp": "2021-04-01T23:59:59.938Z",
  "catalogCode": "1234",

  "itemIN": [
    {
      "SupplierPartID": "138334",
      "itemName": "商品名",
      "makerModelID": "MODEL-001",
      "makerName": "メーカー株式会社",
      "standardDeliveryTime": 3,

      "supplierCode": "SUP001",
      "supplierName": "サプライヤ株式会社",

      "itemSummary": "商品概要",
      "itemSpec1": "商品仕様1",
      "itemSpec2": "商品仕様2",
      "itemSpec3": "商品仕様3",

      "purchaseUnitCode": "6",
      "purchaseUnitName": "セット",
      "purchaseUnitQuantityPerCarton": 10,

      "quantityUnitCode": "1",
      "quantityUnitName": "個",
      "quantityPerCarton": 5,

      "largeCategorycode": "99",
      "largeCategoryname": "大分類",
      "middleCategorycode": "99",
      "middleCategoryname": "中分類",
      "smallCategorycode": "99-99-99-99",
      "smallCategoryname": "小分類",

      "greenItem": "100000000000000000000000000000",
      "postageFlag": "0",

      "regularPrice": 1250.00000,
      "currencyCode": "JPY",
      "saleUnitPrice": 1000.00000,

      "orderLot": 1.00000,
      "minOrderQuantity": 1.00000,

      "itemURL1": "https://example.com/item1.jpg",
      "itemURL2": "",
      "itemURL3": "",

      "itemDivision": "0",
      "SuccessorItemCd": "",
      "returnProprietyFlag": "0",

      "optionalItem1": 300
    }
  ],

  "finalFlag": "9"
}

finalFlag

値	内容
0	商品情報送信途中
9	商品情報送信完了

6-8. ItemSearch サンプル

6-8-1. 用途

ItemSearchは、指定商品の最新情報を外部カタログから取得するAPIです。

主に以下の場面で使用します。

お気に入り商品をカートへ投入する
最新価格を確認する
商品の販売状態を確認する
廃番を確認する
後継品の有無を確認する

6-8-2. 処理イメージ

sequenceDiagram
    participant Mall as カタログモール
    participant Catalog as 外部カタログ

    rect rgb(235, 245, 255)
        Note over Mall,Catalog: 最新商品情報の取得
        Mall->>Catalog: ItemSearch

        Note right of Catalog: 商品情報検索
        Note right of Catalog: 価格確認
        Note right of Catalog: 販売状態確認
        Note right of Catalog: 後継品確認

        Catalog-->>Mall: 最新商品情報
    end

6-8-3. Request構造イメージ

{
  "loginID": "PURCHASEONE-MRO",
  "loginPWD": "********",
  "payloadID": "一意のID",
  "timestamp": "日時",
  "catalogCode": "カタログコード",
  "companyCode": "会社コード",
  "topLevelDepartmentCode": "最上位組織コード",
  "SupplierPartID": "サプライヤ品番"
}

6-8-4. Response商品情報の主な構造

商品基本情報
├── SupplierPartID
├── itemName
├── makerModelID
├── makerName
├── supplierCode
└── supplierName

商品説明
├── itemSummary
├── itemSpec1
├── itemSpec2
└── itemSpec3

価格・注文条件
├── regularPrice
├── saleUnitPrice
├── currencyCode
├── orderLot
└── minOrderQuantity

商品状態
├── itemDivision
├── SuccessorItemCd
└── returnProprietyFlag

予備情報
└── optionalItem1 ～ optionalItem20

6-9. OrderInput サンプル

6-9-1. 用途

OrderInputは、カタログモールから販売管理システムへ発注情報を送信するAPIです。

複数明細がある場合は、Detail配列に複数の注文明細を設定します。

6-9-2. Request構造イメージ

{
  "loginID": "ログインID",
  "loginPWD": "********",
  "payloadID": "一意のID",
  "timestamp": "日時",

  "Detail": [
    {
      "division": "N",

      "orderNumber": "注文番号",
      "orderDetailNumber": "注文明細番号",

      "requestCompanyCode": "依頼会社コード",
      "requestCompanyName": "依頼会社名",

      "requestDepartmentCode": "依頼部門コード",
      "requestDepartmentName": "依頼部門名",

      "requestUserCode": "依頼者コード",
      "requestUserName": "依頼者名",

      "requestDate": "依頼日",
      "orderDate": "注文日",
      "expectationDeliveryDate": "希望納期",

      "catalogCode": "カタログコード",
      "catalogName": "カタログ名",

      "SupplierCompanyCode": "サプライヤ企業コード",
      "SupplierCompanyName": "サプライヤ名",
      "SupplierPartID": "サプライヤ品番",

      "makerName": "メーカー名",
      "makerPartID": "メーカー型番",

      "currencyCode": "JPY",
      "currencyName": "円",

      "orderUnitPrice": 1000,
      "orderQuantity": 10,
      "orderAmount": 10000,

      "deliveryDestinationCompanyName": "納入先企業名",
      "deliveryDestinationPostnumber": "郵便番号",
      "deliveryDestinationAddress1": "住所1",

      "optionalItem1": "",
      "optionalItem19": "0",
      "optionalItem20": ""
    }
  ],

  "sendCount": 1,

  "DeliverInputURL": "納期回答登録API URL",
  "ShipmentInputURL": "出荷登録API URL"
}

6-9-3. Response例

{
  "response": "success",
  "error": {
    "code": 200,
    "message": "OK"
  },
  "result": {
    "receiveCount": 1
  }
}

6-10. DeliverInput サンプル

6-10-1. 用途

DeliverInputは、販売管理システムからカタログモールへ納期回答情報を登録するAPIです。

納期回答明細が複数ある場合は、Detail配列内に複数明細を設定します。

6-10-2. 基本構造

{
  "loginID": "ログインID",
  "loginPWD": "********",
  "payloadID": "一意のID",
  "timestamp": "日時",

  "Detail": [
    {
      "orderNumber": "注文番号",
      "orderDetailNumber": "注文明細番号",

      "deliveryStatus": "納期回答状態",

      "deliveryDate": "納品予定日",

      "comment": "コメント"
    }
  ],

  "sendCount": 1
}

6-10-3. Response構造

{
  "response": "success",
  "error": {
    "code": 200,
    "message": "OK"
  },
  "result": {
    "receiveCount": 1
  }
}

6-11. ShipmentInput サンプル

6-11-1. 用途

ShipmentInputは、販売管理システムからカタログモールへ出荷情報を登録するAPIです。

複数の出荷明細がある場合は、Detail配列内に複数明細を設定します。

6-11-2. 基本構造

{
  "loginID": "ログインID",
  "loginPWD": "********",
  "payloadID": "一意のID",
  "timestamp": "日時",

  "Detail": [
    {
      "orderNumber": "注文番号",
      "orderDetailNumber": "注文明細番号",

      "shipmentDate": "出荷日",

      "shipmentQuantity": 10,

      "deliveryCompany": "配送会社",

      "trackingNumber": "配送伝票番号"
    }
  ],

  "sendCount": 1
}

6-11-3. Response構造

{
  "response": "success",
  "error": {
    "code": 200,
    "message": "OK"
  },
  "result": {
    "receiveCount": 1
  }
}

6-12. GetRegistItem サンプル

6-12-1. 用途

GetRegistItemは、内部商品化対象となる商品件数を取得するAPIです。

前回登録日時を指定することで、それ以降に更新された商品を対象にできます。

6-12-2. Request例

{
  "loginID": "sampleUser",
  "loginPWD": "********",
  "payloadID": "20210401.12345.6789.catalogmall.com",
  "timestamp": "2021-04-01T23:59:59.938Z",
  "catalogCode": "1234",

  "registLastTime": "前回登録日時",

  "RegistItemAddURL": "商品情報登録先URL",

  "returnCount": 100
}

6-12-3. Response例

{
  "payloadID": "20210401.12345.6789.catalogmall.com",
  "timestamp": "2021-04-01T23:59:59.938Z",
  "command": "GetRegistItem",
  "version": "1.0",
  "catalogCode": "1234",

  "response": "success",

  "error": {
    "code": 200,
    "message": "OK"
  },

  "result": {
    "itemCount": 521
  }
}

この例では、内部商品化対象が521件存在することを示します。

6-13. RegistItemAdd サンプル

6-13-1. 用途

RegistItemAddは、外部カタログの商品情報をカタログモールへ送信し、内部商品として登録するためのAPIです。

複数商品を登録する場合は、itemIN配列内に複数商品を設定します。

6-13-2. Request構造

{
  "loginID": "ログインID",
  "loginPWD": "********",

  "payloadID": "20210401.12345.6789.catalogmall.com",
  "timestamp": "2021-04-01T23:59:59.938Z",

  "catalogCode": "1234",

  "itemIN": [
    {
      "buyerCompanyCode": "",
      "topLevelDepartmentCode": "",

      "SupplierPartID": "138335",
      "itemName": "商品名",

      "makerModelID": "MODEL-001",
      "makerName": "メーカー株式会社",

      "standardDeliveryTime": 3,

      "supplierCode": "SUP001",
      "supplierName": "サプライヤ株式会社",

      "itemSummary": "商品概要",
      "itemSpec1": "商品仕様1",
      "itemSpec2": "商品仕様2",
      "itemSpec3": "商品仕様3",

      "purchaseUnitCode": "6",
      "purchaseUnitName": "セット",
      "purchaseUnitQuantityPerCarton": 10,

      "quantityUnitCode": "1",
      "quantityUnitName": "個",
      "quantityPerCarton": 5,

      "largeCategorycode": "99",
      "largeCategoryname": "大分類",

      "middleCategorycode": "99",
      "middleCategoryname": "中分類",

      "smallCategorycode": "99-99-99-99",
      "smallCategoryname": "小分類",

      "greenItem": "100000000000000000000000000000",

      "postageFlag": "0",

      "regularPrice": 1250.00000,
      "currencyCode": "JPY",
      "saleUnitPrice": 1000.00000,

      "orderLot": 1.00000,
      "minOrderQuantity": 1.00000,

      "itemURL1": "https://example.com/item1.jpg",
      "itemURL2": "",
      "itemURL3": "",

      "itemDivision": "0",
      "SuccessorItemCd": "138334A",

      "returnProprietyFlag": "1",

      "optionalItem1": 980.00000,

      "optionalItem2": "",
      "optionalItem3": "",
      "optionalItem4": "",
      "optionalItem5": "",
      "optionalItem6": "",
      "optionalItem7": "",
      "optionalItem8": "",
      "optionalItem9": "",
      "optionalItem10": "",
      "optionalItem11": "",
      "optionalItem12": "",
      "optionalItem13": "",
      "optionalItem14": "",
      "optionalItem15": "",
      "optionalItem16": "",
      "optionalItem17": "",
      "optionalItem18": "",
      "optionalItem19": "",
      "optionalItem20": "",

      "startDate": "2021-04-01",
      "endDate": "",

      "registTime": "2021-04-01T23:59:59.938Z"
    }
  ],

  "finalFlag": 9
}

6-13-3. Response構造

{
  "payloadID": "20210401.12345.6789.catalogmall.com",
  "timestamp": "2021-04-01T23:59:59.938Z",

  "command": "RegistItemAdd",
  "version": "1.0",

  "catalogCode": "1234",

  "response": "success",

  "error": {
    "code": 200,
    "message": "OK"
  }
}

6-14. API・データサンプルの関係

各サンプルの関係を整理すると、以下のようになります。

flowchart TB

    subgraph PO["① パンチアウト連携"]
        PO1["PunchOutSetUpRequest<br/>（Mall→Catalog）"]
        PO2["PunchOutSetUpResponse<br/>（Catalog→Mall）"]
        PO3["PunchOutOrderMessage<br/>（Catalog→Mall）"]

        PO1 --> PO2
        PO2 -->|"外部サイト利用"| PO3
    end

    subgraph SEARCH["② バックグラウンド検索"]
        S1["KeywordSearch<br/>（Mall→Catalog）"]
        S2["KeywordItemAdd<br/>（Catalog→Mall）"]
        S3["ItemSearch<br/>（Mall⇔Catalog・独立呼び出し）"]

        S1 -->|"検索件数"| S2
    end

    subgraph EDI["③ EDI連携"]
        E1["OrderInput<br/>（Mall→Sales）"]
        E2["DeliverInput<br/>（Sales→Mall）"]
        E3["ShipmentInput<br/>（Sales→Mall）"]

        E1 --> E2
        E2 --> E3
    end

    subgraph INTERNAL["④ 内部商品化"]
        I1["GetRegistItem<br/>（Mall→Catalog）"]
        I2["RegistItemAdd<br/>（Catalog→Mall）"]

        I1 -->|"登録対象件数"| I2
    end

    PO ~~~ SEARCH
    SEARCH ~~~ EDI
    EDI ~~~ INTERNAL

    style PO fill:#f5faff,stroke:#1e88e5,stroke-width:1px
    style SEARCH fill:#faf5fb,stroke:#8e24aa,stroke-width:1px
    style EDI fill:#fffaf0,stroke:#fb8c00,stroke-width:1px
    style INTERNAL fill:#f3faf4,stroke:#43a047,stroke-width:1px

    classDef po fill:#e3f2fd,stroke:#1e88e5,stroke-width:1px,color:#0d47a1
    classDef search fill:#f3e5f5,stroke:#8e24aa,stroke-width:1px,color:#4a148c
    classDef edi fill:#fff3e0,stroke:#fb8c00,stroke-width:1px,color:#e65100
    classDef internal fill:#e8f5e9,stroke:#43a047,stroke-width:1px,color:#1b5e20

    class PO1,PO2,PO3 po
    class S1,S2,S3 search
    class E1,E2,E3 edi
    class I1,I2 internal

6-15. サンプル一覧まとめ

業務領域	API・電文	データ方向	役割
パンチアウト	PunchOutSetUpRequest	カタログモール → 外部カタログ	接続・認証要求
パンチアウト	PunchOutSetUpResponse	外部カタログ → カタログモール	認証結果・遷移先返却
パンチアウト	PunchOutOrderMessage	外部カタログ → カタログモール	選択商品返却
商品検索	KeywordSearch	カタログモール → 外部カタログ	キーワード検索要求
商品検索	KeywordItemAdd	外部カタログ → カタログモール	商品情報非同期送信
商品検索	ItemSearch	カタログモール ↔ 外部カタログ	最新商品情報取得
EDI	OrderInput	カタログモール → 販売管理システム	発注情報登録
EDI	DeliverInput	販売管理システム → カタログモール	納期回答登録
EDI	ShipmentInput	販売管理システム → カタログモール	出荷情報登録
内部商品化	GetRegistItem	カタログモール → 外部カタログ	登録対象件数取得
内部商品化	RegistItemAdd	外部カタログ → カタログモール	商品情報登録

これらのサンプルは、個別APIを単独で理解するよりも、パンチアウト連携・バックグラウンド検索・EDI連携・内部商品化という4つの業務フロー単位で確認すると、データの方向と各APIの役割を理解しやすくなります。

7. ファイル連携仕様

7-1. CHKファイル

概要

CHKファイルは、SFTPによる内部商品化処理の結果を通知するためのファイルです。

商品情報CSVまたはZIPファイルを取り込んだ後、処理結果としてFromJ2ディレクトリへ出力されます。

出力先

カタログコード/
└── FromJ2/
    └── *.CHK

主な役割

項目	内容
処理開始日時	商品情報取込処理を開始した日時
処理終了日時	商品情報取込処理を終了した日時
処理件数	処理対象となった総件数
正常件数	正常に登録された件数
エラー件数	登録できなかった件数
処理結果	正常終了／一部エラー／異常終了など

処理イメージ

商品情報CSV
    ↓
ジーニーシステムで取込
    ↓
登録処理・チェック
    ↓
CHKファイル出力

7-2. 商品情報SFTP形式CSV

概要

商品情報SFTP形式CSVは、外部システムからジーニーシステムへ商品情報を一括連携するためのCSVファイルです。

このCSVをもとに、商品情報が内部カタログの商品マスタへ登録されます。

配置先

カタログコード/
└── ToJ2/
    └── 商品情報CSV

ファイル条件

項目	内容
ファイル形式	CSV
文字コード	Shift_JIS または UTF-8
ヘッダー	あり
区切り文字	カンマ
囲み文字	ダブルクォーテーション
最大件数	ヘッダー込み10,001行
商品データ件数	1ファイル最大10,000件

主な項目分類

分類	主な項目
商品識別情報	サプライヤ品番、商品名、メーカー型番、メーカー名
サプライヤ情報	サプライヤコード、サプライヤ名
商品説明	商品概要、商品仕様1〜3
単位情報	購入単位コード、購入単位名、数量単位コード、数量単位名
カテゴリ情報	大分類、中分類、小分類
価格情報	定価、販売単価、通貨コード
注文条件	発注ロット、最低発注数
商品状態	通常、製造中止、販売中止、後継品番
URL情報	商品画像URL、商品詳細URL
予備項目	optionalItem1〜optionalItem20

処理イメージ

外部システム
    ↓ CSV作成
ToJ2
    ↓ SFTP配置
ジーニーシステム
    ↓ 取込・チェック
内部商品マスタ

7-3. 商品情報SFTP形式CSV（TO-BE）

概要

商品情報SFTP形式CSV（TO-BE）は、将来的な運用や拡張を想定した商品情報CSV仕様です。

既存のCSV仕様をベースにしながら、内部商品化に必要な項目をより整理し、商品検索・購買・EDI連携で利用しやすい形式にすることを目的とします。

想定される改善ポイント

観点	内容
商品識別	商品コード、サプライヤ品番、メーカー型番を明確化
検索性	商品名、商品概要、仕様、検索キーワードを整理
カテゴリ	大分類・中分類・小分類を体系化
価格	定価、販売単価、仕入単価などを分離
注文条件	最低発注数、発注ロット、単位入数を明確化
商品状態	販売中止、製造中止、後継品情報を管理
画面表示	商品画像URL、商品詳細URLを利用
拡張性	optionalItemで個別項目に対応

7. ファイル連携仕様まとめ

ファイル連携仕様は、SFTPを利用して商品情報を一括登録するための仕様です。

flowchart LR

    subgraph EXT["お取引企業様"]
        A["外部システム"]
        B["商品情報CSV / ZIP"]
    end

    subgraph SFTP["SFTP連携エリア"]
        C["ToJ2（↑ 送信）"]
        F["FromJ2（↓ 受信）"]
    end

    subgraph J2SYS["J2システム（ジーニーラボ株式会社）"]
        D["カタログモール（J2）<br/>取込・チェック処理"]
        E["内部商品マスタ"]
    end

    G["CHKファイル<br/>（処理結果）"]
    H["NGファイル<br/>（データエラー）"]
    I["FORMAT_ERRORファイル<br/>（形式エラー）"]

    A --> B
    B --> C
    C --> D
    D --> E
    D --> F
    F --> G
    F --> H
    F --> I

主なポイントは以下のとおりです。

外部システムは商品情報CSVまたはZIPをToJ2へ配置する。
ジーニーシステムがファイルを取得し、内部商品登録を行う。
処理結果はFromJ2へ出力する。
正常・異常の結果確認にはCHKファイルを使用する。
商品データエラーは*_NG.csv、CSV変換エラーは*_FORMAT_ERROR.csvで確認する。

8. 用語集

本仕様書で使用する主な用語の定義を以下に示します。

8-1. システム・組織

用語	説明
J2システム（ジーニー2.0）	ジーニーラボ株式会社が開発・提供する購買プラットフォームの総称。購買システムとカタログモールの2つのサブシステムで構成される
ジーニーラボ株式会社	J2システム（ジーニー2.0）を開発・提供するシステム会社
購買システム	J2システム（ジーニー2.0）のサブシステム。ユーザ企業様の購買業務（購入依頼・承認・発注）を担う
カタログモール	J2システム（ジーニー2.0）のサブシステム。外部カタログおよび内部カタログの商品検索・選択・発注連携を担う
ユーザ企業様	J2システム（ジーニー2.0）を購買業務に利用する企業
お取引企業様	ユーザ企業様に商品を提供するサプライヤ（供給者）企業。カタログサイトや販売管理システムを通じてJ2システムと連携する
購入依頼者	ユーザ企業様内でカタログモールを利用して商品を検索・選択し購入依頼を行う担当者

8-2. パンチアウト連携

用語	説明
パンチアウト連携	カタログモールからお取引企業様の外部カタログサイトへブラウザ画面を遷移させ、外部サイト上で商品を検索・選択してカタログモールへ返却する連携方式
CheckIn（チェックイン）	パンチアウト連携の接続・認証フェーズ。カタログモールが外部カタログサイトへ `PunchOutSetupRequest` を送信し、認証後に外部カタログ画面を表示する
CheckOut（チェックアウト）	パンチアウト連携の商品返却フェーズ。外部カタログサイトで選択した商品情報を `PunchOutOrderMessage` でカタログモールへ送信し、カートへ登録する
cXML	Commerce eXtensible Markup Language の略。パンチアウト連携で使用する XMLベースの電子商取引データ形式
PunchOutSetupRequest	CheckIn 時にカタログモールから外部カタログサイトへ送信する接続・認証要求メッセージ（cXML 形式）
PunchOutSetupResponse	CheckIn 時に外部カタログサイトからカタログモールへ返却する認証結果メッセージ（cXML 形式）。正常時は `StartPage` の URL を含む
StartPage	`PunchOutSetupResponse` に含まれる外部カタログサイトの遷移先 URL
PunchOutOrderMessage	CheckOut 時に外部カタログサイトからカタログモールへ送信するカート情報メッセージ（cXML 形式）。選択した商品の `ItemIn` を含む
BuyerCookie	パンチアウト連携においてセッションを識別するための情報。 `PunchOutSetupRequest` でカタログモールが設定し、 `PunchOutOrderMessage` で外部カタログサイトが返却する
ItemIn	`PunchOutOrderMessage` において1商品分の情報を表す要素。複数商品選択時は繰り返し設定する

8-3. バックグラウンド検索

用語	説明
バックグラウンドキーワード検索	購入依頼者が外部カタログサイトへ画面遷移せず、カタログモール上の検索画面から外部カタログ商品を検索できる連携方式。 `KeywordSearch` と `KeywordItemAdd` の2つの API を使用する
バックグラウンド商品検索	サプライヤ品番等の商品識別情報を指定して外部カタログサーバへ商品情報を問い合わせる連携方式。 `ItemSearch` API を使用する
KeywordSearch	バックグラウンドキーワード検索でカタログモールから外部カタログサーバへ検索条件を送信するリクエスト API。レスポンスとして検索ヒット件数（`itemCount`）を返す
KeywordItemAdd	外部カタログサーバからカタログモールへ検索結果の商品情報を非同期で送信するコールバック API。`returnCount` 件単位で分割送信できる
ItemSearch	バックグラウンド商品検索でカタログモールから外部カタログサーバへ商品情報を問い合わせる API
returnCount	API 連携で商品情報を分割送信する際の1回あたりの送信件数
maxReturnCount	API 連携で返却する商品情報の最大件数
firstReturnCount	バックグラウンドキーワード検索において、1ページに表示される最大商品件数
finalFlag	商品情報の送信完了状態を示すフラグ。`0`：送信未完了、`9`：全件送信完了
sortType	キーワード検索結果の表示順を指定する値（0：標準 / 1：価格安い順 / 2：価格高い順など）

8-4. 内部カタログ化（内部商品化）

用語	説明
内部カタログ化（内部商品化）	外部カタログサイトの商品情報をカタログモールの商品マスタへ登録し、外部サイトへ遷移せずにカタログモール内で検索・購入できる内部カタログ商品として利用できるようにする仕組み
内部カタログ商品	内部カタログ化によってカタログモールの商品マスタへ登録された商品。外部カタログサイトへ遷移することなく検索・購入できる
外部カタログ	お取引企業様が独自に管理するカタログサイト。パンチアウト連携またはバックグラウンド検索 API を通じてカタログモールと連携する
GetRegistItem	内部商品化 API 連携においてカタログモールから外部カタログサーバへ内部商品化対象の商品件数を問い合わせる API
RegistItemAdd	内部商品化 API 連携において外部カタログサーバからカタログモールへ内部商品化対象の商品情報を登録するコールバック API
registLastTime	`GetRegistItem` リクエストで使用する前回登録日時。これより後に更新された商品を処理対象とする。初回は空文字を設定する

8-5. EDI連携

用語	説明
EDI連携	Electronic Data Interchange（電子データ交換）の略。カタログモールとお取引企業様の販売管理システムとの間で、発注・納期回答・出荷情報を電子的に連携する仕組み
OrderInput	EDI連携においてカタログモールからお取引企業様の販売管理システムへ発注情報を登録する API
DeliverInput	EDI連携においてお取引企業様の販売管理システムからカタログモールへ納期回答情報を登録する API
ShipmentInput	EDI連携においてお取引企業様の販売管理システムからカタログモールへ出荷情報を登録する API
division	`OrderInput` の `Detail` 内で発注明細の区分（N：新規 / U：更新 / D：取消）を示す項目
sendCount	`OrderInput` で送信する発注明細件数
DeliverInputURL	`OrderInput` 送信時にカタログモールがお取引企業様へ通知する、納期回答登録 API の呼び出し URL
ShipmentInputURL	`OrderInput` 送信時にカタログモールがお取引企業様へ通知する、出荷登録 API の呼び出し URL

8-6. 商品情報の共通項目

用語	説明
SupplierPartID	お取引企業様（サプライヤ）が管理する商品品番
payloadID	リクエストを一意に識別するための ID。形式：`日付.プロセスID.ランダム数値.ホスト名`
timestamp	データ作成日時。形式：`YYYY-MM-DDThh:mm:ss-hh:mm`（UTC オフセット付き）
taxClass	課税区分を示すコード（0：課税（税込）/ 1：課税（税抜き）/ 2：非課税 / 3：免税など）
postageFlag	別途費用の有無や購入方法の制約を示す区分コード
greenItem	グリーン商品の規格情報。利用企業ごとに登録されたグリーン対象規格と照合して判定する
グリーン商品	利用企業様が定めた環境基準（規格）に適合した商品。カタログモール上でグリーンマークとして表示される
orderLot	商品の発注単位数量
minOrderQuantity	最小発注数量
purchaseUnitCode	購入単位コード（例：個・本・袋など）
quantityUnitCode	数量単位コード
itemDivision	商品の販売状態区分（0：通常 / 1：製造中止 / 2：販売中止）
returnProprietyFlag	返品可否フラグ（0：返品可 / 1：返品不可）
SuccessorItemCd	廃番商品に対する後継品のサプライヤ品番
optionalItem1〜20	個別の商品属性を連携するための任意拡張項目（例：optionalItem1＝仕入単価、optionalItem2＝JANコード）
SITE_KBN	サイト区分。マスタ設定により送付するかどうかを制御するコード

8-7. SFTP連携・ファイル

用語	説明
SFTP	Secure File Transfer Protocol の略。SSH による暗号化通信を用いたファイル転送プロトコル。内部商品化（SFTP）での商品情報ファイル連携に使用する
ToJ2	外部システムからジーニーシステムへ送信するファイルを配置する SFTP ディレクトリ
FromJ2	ジーニーシステムが内部商品登録の処理結果を出力する SFTP ディレクトリ
*CHKファイル（.CHK）**	内部商品登録処理全体の実行結果（処理開始・終了日時・処理件数・OK件数・NG件数）を記録するファイル
*NGファイル（_NG.csv）**	データ内容のバリデーションチェックでエラーとなった商品情報を出力するファイル
*FORMAT_ERRORファイル（_FORMAT_ERROR.csv）**	CSV 形式として正常に解析・変換できないファイルのエラー情報を出力するファイル
カタログコード	カタログサイト・連携チャネルを識別するコード。SFTP のディレクトリ構成や API 認証に使用する

商品情報CSV（TO-BE）は、将来的な拡張・運用改善を想定した形式である。

【Jienie2.0】カタログモール外部連携仕様（ver 1.36）

目次

改訂履歴

1. システム全体概要

1.1 概要

1.2 システム全体構成

1-1. 商品（検索）情報の連携

概要

商品検索の基本イメージ

お気に入り商品の最新情報確認

処理パターン

1-2. EDI連携

概要

連携内容

EDI連携の基本フロー

発注情報の連携

納期回答情報の連携

出荷情報の連携

EDI連携一覧

1-3. 内部カタログ化

概要

内部カタログ化の基本イメージ

内部カタログ化の連携方式

システム全体のまとめ

2-1. カタログサイトでの商品検索（パンチアウト連携）

2-1-1. 概要

2-1-2. 前提条件

2-1-3. CheckIn（チェックイン）

2-1-3-1. 処理シーケンス

ステータスコード別の処理

2-1-3-2. データフォーマット

2-1-3-2-1. PunchOutSetupRequest

データ構造

タグ・属性一覧

サンプル

エスケープ対象文字

2-1-3-2-2. PunchOutSetupResponse

データ構造

タグ・属性一覧

ステータスコード一覧

2-1-4. CheckOut（チェックアウト）

2-1-4-1. 処理シーケンス

2-1-4-2. データフォーマット

2-1-4-2-1. PunchOutOrderMessage

データ構造

主要商品情報項目

基本商品情報

サプライヤ情報

商品概要・仕様情報

購買単位情報

カテゴリ情報

環境・価格・注文条件

URL・商品識別情報

任意拡張項目

グリーン商品情報の取り扱い

CheckOut後の画面遷移

2-1. パンチアウト連携の全体まとめ

2-2. バックグラウンドキーワード検索（API連携）

2-2-1. 概要

2-2-2. 前提条件

2-2-3. 処理シーケンス

2-2-4. API一覧

2-2-4-1. KeywordSearch（外部カタログ検索）

概要

リクエスト

認証・制御情報

payloadID

timestamp

検索条件

freeword / freeword1

greenItem

sortType

excludeKeyword

商品情報返却制御

返却イメージ

レスポンス

response

error

itemCount

KeywordSearch ステータスコード