> For the complete documentation index, see [llms.txt](https://shopping-docs.toss.im/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://shopping-docs.toss.im/connect/fulfillment-api/sftp.md).

# SKU, 재고, 셀러 동기화(SFTP)

## **SFTP 인증 & 접속 정보**

SFTP는 **SSH Key 기반 인증(PEM)** 만 지원해요. ID/PW 방식은 사용하지 않고, IP ACL도 함께 적용돼요.

| 항목             | 내용                                  |
| -------------- | ----------------------------------- |
| Host           | 담당자 문의                              |
| Port           | 담당자 문의                              |
| 계정             | 풀필먼트 제휴사별 개별 발급 (개발/운영 분리)          |
| 인증             | SSH Key 기반(PEM). Public Key 전달 후 적용 |
| outbound 허용 IP | 3개 IP 등록 필요 (담당자 문의)                |

**인증 절차**

1. **\[풀필먼트]** SSH Key Pair(Private/Public)를 생성해요.
2. **\[풀필먼트]** 생성한 **Public Key**를 토스쇼핑 담당자에게 전달해요.
3. **\[토스쇼핑]** 서버 운영자가 Public Key를 SFTP 계정에 등록해요.
4. **\[풀필먼트]** Private Key(PEM)로 SFTP에 접속해요.

{% hint style="info" %}
SSH Key Pair 생성, 실제 계정명, 접속 허용 IP 등록은 모두 담당자를 통해 진행해요. 보안상 이 문서에는 실제 계정명·IP를 싣지 않아요.
{% endhint %}

### **디렉토리 구조**

```
/[fulfillment_name]/
  ├── merchant/recv/
  ├── product/recv/
  └── stock/recv/
```

* `recv/`: 풀필먼트가 파일을 업로드하는 위치

{% hint style="info" %}
`[fulfillment_name]`은 연동사별로 달라요. (예: 파스토는 `/fassto/`) 정확한 루트 경로는 담당자에게 확인해주세요.
{% endhint %}

### **파일명 규칙**

| 구분          | 파일명 패턴                      | 예시                       |
| ----------- | --------------------------- | ------------------------ |
| 일단위 전체 FEED | `{Domain}_{yyyyMMdd}.jsonl` | `product_20260401.jsonl` |

각 파일은 **JSONL**(1줄 = 1 레코드) 형식이에요.

### **merchant 파일 (셀러-계정 매핑)**

**경로**: `/[fulfillment_name]/merchant/recv/` · **파일명**: `merchant_{yyyyMMdd}.jsonl`

| 필드명                      | 타입       | 필수 | 설명                           |
| ------------------------ | -------- | -- | ---------------------------- |
| `fulfillmentAccountKey`  | String   | O  | 풀필먼트 계정 식별자                  |
| `fulfillmentAccountName` | String   | O  | 풀필먼트 계정 이름                   |
| `clientId`               | String   | O  | 토스쇼핑 셀러 식별자 (OAuth clientId) |
| `isConnected`            | Boolean  | O  | 토스 연동 여부 (`false`도 포함해서 전송)  |
| `terminatedReason`       | String   | X  | 연결 해지 사유 (해지된 경우만)           |
| `updatedAt`              | DateTime | O  | 연결 상태 변경 일시                  |

{% code title="merchant\_20260401.jsonl" %}

```jsonl
{"fulfillmentAccountKey":"FF-123","fulfillmentAccountName":"나이키","clientId":"oauth_client_id","isConnected":true,"terminatedReason":null,"updatedAt":"2026-04-01T10:00:00"}
{"fulfillmentAccountKey":"FF-456","fulfillmentAccountName":"ZARA","clientId":"oauth_client_id","isConnected":false,"terminatedReason":"계약해지","updatedAt":"2026-04-01T10:00:00"}
```

{% endcode %}

### **product 파일 (SKU 전체)**

**경로**: `/[fulfillment_name]/product/recv/` · **파일명**: `product_{yyyyMMdd}.jsonl`

필드 구성은 4.2 SKU 메타데이터 동기화의 요청 필드와 동일해요. (1줄 = 1 SKU)

{% code title="product\_20260401.jsonl" %}

```jsonl
{"skuKey":"SKU-001","skuName":"블랙/L","fulfillmentAccountKey":"3239","barcode":"8801234567890","widthMm":120,"depthMm":280,"heightMm":40,"skuTypeCode":"MAIN_PRODUCT","isUseByDateManaged":false,"isLotManaged":false,"isActive":true,"boxTypeCode":"FULFILLMENT_BOX","cushioningPackageTypeCode":"BASIC","storageConditionCode":"AMBIENT","createdAt":"2026-04-01T10:00:00","updatedAt":"2026-04-01T10:00:00"}
```

{% endcode %}

### **stock 파일 (재고 전체)**

**경로**: `/[fulfillment_name]/stock/recv/` · **파일명**: `stock_{yyyyMMdd}.jsonl` **식별 기준**: `fulfillmentPartner + fulfillmentAccountKey + skuKey + fulfillmentCenterKey` (1줄 = 1 SKU × 물류센터 조합)

필드 구성은 4.4 재고 동기화의 요청 필드와 동일해요.

{% code title="stock\_20260401.jsonl" %}

```jsonl
{"skuKey":"SKU-001","fulfillmentAccountKey":"3239","fulfillmentCenterKey":"YI01","fulfillmentCenterName":"용인01","availableQuantity":75,"onHandQuantity":80,"updatedAt":"2026-04-01T10:00:00"}
{"skuKey":"SKU-001","fulfillmentAccountKey":"3239","fulfillmentCenterKey":"YI23","fulfillmentCenterName":"용인23","availableQuantity":11,"onHandQuantity":9,"updatedAt":"2026-04-01T10:00:00"}
```

{% endcode %}

{% hint style="warning" %}
**0재고 SKU도 반드시 포함**해서 전송해주세요. 재고가 0인 SKU를 파일에서 빼면 토스쇼핑이 그 SKU의 품절 상태를 갱신하지 못해요. 주문 가능 수량의 기준은 항상 `availableQuantity`예요.
{% endhint %}

####


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://shopping-docs.toss.im/connect/fulfillment-api/sftp.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.