> ## 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 공간이 프로비저닝된 후 SFTP 환경 내에 데이터 파일(**상품**, **주문**, **반품** 및 관련 데이터)을 구성하는 방법을 설명합니다.

복수의 쇼핑몰을 운영하거나 여러 환경(prod, preprod 등)이 있는 경우, 각각에 대해 별도의 하위 폴더를 생성해 주세요(다른 브랜드 또는 다른 국가의 경우도 동일하게 적용됩니다).

### 디렉토리 구조 예시

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

***

## 2. 데이터 전송 일정

데이터 파일은 가급적 매일 다음 시간대에 전송해 주시기 바랍니다:

* **오전 02:00**
* **오전 05:00**

이 시간대를 준수하면 최적의 처리 및 데이터 수집이 보장됩니다.

***

## 3. 파일 구성 표준

각 쇼핑몰 디렉토리 내에 다음 폴더를 생성해 주세요:

* `products`
* `orders`
* `returns`
* `return_reasons` (선택 사항)
* `misc` (선택 사항)

**참고:**

* `return_reasons` 폴더는 고객이 제공한 사유 등 추가적인 반품 데이터를 포함하는 내보내기 파일에 사용됩니다. 이 내보내기는 선택 사항입니다.
* `misc` 폴더에는 기타 파일을 넣을 수 있습니다. 이 폴더를 사용하려는 경우, 호환성을 보장하기 위해 계층 구조 및 형식에 대해 사전에 협의해 주세요.

각 내보내기는 적절한 폴더에 배치되어야 하며, 타임스탬프가 포함된 파일명을 사용하여 **날짜 기반으로 구분**해 주세요.

### 파일명 형식 예시

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

***

## 4. 내보내기 콘텐츠 요구사항

각 데이터셋 유형에 대한 예상 필드, 형식 및 제약사항의 상세 사양은 **Data Transfers: Template** 문서에서 확인할 수 있습니다.

**상품 카탈로그 내보내기의 주요 요구사항:**

* 품절 상품을 포함한 **모든 상품 변형**을 내보냅니다
* 증분 처리를 위한 **최종 수정 날짜** 필드를 포함합니다
* 올바른 사이즈 분석을 위한 완전한 변형 정보를 유지합니다
* 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` not `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

```

***