> ## Documentation Index
> Fetch the complete documentation index at: https://docs.kleep.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# SFTP データ構造

## 1. はじめに

このドキュメントでは、専用スペースがプロビジョニングされた後、SFTP 環境内でデータファイル（**商品**、**注文**、**返品**、および関連データ）を構造化する方法を説明します。

複数のショップを運営している場合、または複数の環境（本番、プリプロダクションなど）がある場合は、それぞれに別のサブフォルダーを作成してください（異なるブランド、異なる国なども同様です）。

### ディレクトリ構造の例

```
/root_space
    /shop_fr
    /shop_en
    /shop_it
```

***

## 2. データ転送スケジュール

データファイルは理想的には以下の時間帯に**毎日**転送してください。

* **午前 2:00**
* **午前 5:00**

この時間帯は、最適な処理とデータ取り込みを確保します。

***

## 3. ファイル整理基準

各ショップディレクトリ内に以下のフォルダーを作成してください。

* `products`
* `orders`
* `returns`
* `return_reasons`（任意）
* `misc`（任意）

**注意：**

* `return_reasons` フォルダーは、顧客が提供した返品理由などの追加の返品データを含むエクスポートファイルに使用されます。このエクスポートは任意です。
* `misc` フォルダーには雑多なファイルを含めることができます。このフォルダーを使用する場合は、互換性を確保するために事前に階層と構造についてご相談ください。

各エクスポートは適切なフォルダーに配置し、タイムスタンプ付きのファイル名を使用して**日付を付けて**ください。

### ファイル名フォーマットの例

```
products_2025-01-15T02-00-00.csv
```

***

## 4. エクスポートコンテンツの要件

各データセットタイプに期待されるフィールド、フォーマット、および制約の詳細な仕様は、**データ転送：テンプレート**ドキュメントに記載されています。

**商品カタログエクスポートの主要要件：**

* 在庫切れのアイテムを含む**すべての商品バリアント**をエクスポートする
* 増分処理のための**最終更新日**フィールドを含める
* 適切なサイジング分析を可能にするために完全なバリアント情報を維持する
* Kleep の表示制御のための非アクティブフラグをオプションで追加する

包括的なフィールド定義と例については、テンプレートをご参照ください。

***

## 5. エクスポート間での繰り返しデータの処理

レコードが複数の日次エクスポートに正当に表示されることがあります。例えば、特定の返品が異なるファイルに複数回含まれる場合があります。

当社の取り込みシステムは自動的に重複排除を処理し、各レコードの**最新バージョン**のみを処理します。

***

## 6. データフォーマットガイドライン

すべてのエクスポートは **CSV** フォーマットで提供してください。

Excel ファイル（`.xlsx`）はフォーマットの不整合を引き起こし、自動取り込みワークフローを複雑にする可能性があるため、推奨されません。

* **日時：** ISO 8601 フォーマットを使用：`YYYY-MM-DDTHH:MM:SSZ`、例：`2025-01-15T14:30:00Z`
* **エンコーディング：** すべてのテキストフィールドは UTF-8 エンコーディング、CSV の特殊文字を適切にエスケープする
* **ブール値：** `true`/`false`（小文字）または `True`/`False` を使用する
* **小数値：** 小数点区切りにはピリオド（`.`）を使用する。例：`129,99` ではなく `129.99`
* **Null 値：** CSV のオプションのテキストフィールドが欠落している場合は空文字列、JSON では null を使用する

### ファイル命名規則

***

SFTP データ構造ドキュメントで指定されているように、以下のフォーマットを使用してください。

```
{data_type}_{timestamp}.csv
```

例：

* `products_2025-01-15T02-00-00.csv`
* `orders_2025-01-15T02-00-00.csv`
* `returns_2025-01-15T02-00-00.csv`

***

## 7. 過去データのエクスポート

**過去データ**（日次エクスポートの一部ではないデータ）を提供する必要がある場合、以下を含むすべてのデータタイプについて**最大 1 年間の過去のレコード**をエクスポートできます。

* **商品**
* **注文**
* **返品**

過去のデータセットは **SFTP を通じて**、またはより便利な場合は**別途合意した方法で**転送できます。

# 完全な SFTP 構造の例

```
/root_space
    /shop_fr
        /products
            products_2025-01-15T02-00-00.csv
            products_2025-01-16T02-00-00.csv
        /orders
            orders_2025-01-15T02-00-00.csv
            orders_2025-01-16T02-00-00.csv
        /returns
            returns_2025-01-15T02-00-00.csv
            returns_2025-01-16T02-00-00.csv
        /return_reasons
            return_reasons_2025-01-15T02-00-00.csv  (optional)
        /misc
            (optional, please discuss hierarchy with us)

    /shop_en
        /products
        /orders
        /returns
        /return_reasons
        /misc

    /shop_it
        /products
        /orders
        /returns
        /return_reasons
        /misc

```

***