> 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/undefined.md).

# 시작 전 준비

### 시작 전 준비

연동을 시작하기 전에 인증·환경·IP ACL을 먼저 세팅해야 해요. 이 부분이 가장 자주 막히는 지점이라 꼼꼼히 확인해주세요.

#### Base URL & 환경 분리

개발(테스트)과 운영 환경은 **별도 API Key, SFTP 계정, 접속 허용 IP**로 완전히 분리되어 있어요. 한 환경의 자격 증명을 다른 환경에서 쓰면 인증에 실패해요.

| 환경      | API Base URL                         |
| ------- | ------------------------------------ |
| 운영      | `https://shopping-fep.toss.im`       |
| 개발(테스트) | `https://shopping-fep-alpha.toss.im` |

{% hint style="warning" %}
개발용 자격 증명과 운영용 자격 증명을 **섞어 쓰지 마세요.** API Key·SFTP 계정·허용 IP 모두 환경마다 따로 발급돼요. 운영 배포 시점에 운영 자격 증명으로 교체하는 과정을 연동 일정에 미리 포함해주세요.
{% endhint %}

#### 인증 방식 2종

토스쇼핑 도착보장 연동은 **API 종류에 따라 인증 방식이 달라요.** 이걸 혼동하면 연동 초반에 401이 반복돼요.

| API 그룹                                | 필요한 인증                                               |
| ------------------------------------- | ---------------------------------------------------- |
| **계정 등록 / 계정 해제**                     | OAuth2 Client Credentials **Access Token** + API Key |
| **그 외 모든 API** (SKU·재고·주문·취소·배송·CAPA) | API Key + IP ACL                                     |

**API Key 인증 (대부분의 API)**

대부분의 API는 고정된 **API Key**를 헤더에 담아 호출해요. 별도의 토큰 발급 과정이 없어요. API Key는 개발 환경와 운영 환경이 별도의 키에 해당해요

<table><thead><tr><th width="300.24609375">헤더명</th><th>필수</th><th>설명</th></tr></thead><tbody><tr><td><code>X-Toss-Shopping-Connect-Api-Key</code></td><td>O</td><td>발급받은 API Key</td></tr><tr><td><code>X-Toss-Shopping-Connect-Tx-Id</code></td><td>O</td><td>거래 추적용 ID (로깅·디버깅 목적)</td></tr><tr><td><code>Authrization</code></td><td>X</td><td>셀러의 Access Token (계정 등록 / 계정 해제에서만 사용)</td></tr></tbody></table>

**OAuth2 인증 (계정 등록/해제 전용)**

계정 등록·해제 API는 위 API Key에 더해 **OAuth2 Access Token**이 추가로 필요해요. API Key만 보내면 401이 떨어져요.

**토큰 발급 절차**

1. 셀러에게서 `Access Key`, `Secret Key`를 수령해요.
2. Token Endpoint에 `POST`로 Access Token을 발급받아요.
3. 발급된 토큰을 유효기간 내에 `Authorization: Bearer {token}` 헤더로 사용해요. 만료(401) 시 재발급 후 재호출해요.

{% hint style="info" %}
자세한 내용은 [API 인증 토큰 발급받기](https://shopping-docs.toss.im/dev/api-1/token) 문서를 참고해 주세요
{% endhint %}

#### IP ACL(화이트리스트) 등록

토스쇼핑 API는 **API Key에 더해 IP 기반 ACL**을 적용해요. 풀필먼트 시스템의 **공인(outbound) IP**를 사전에 등록하지 않으면 모든 호출이 거절되어요

**등록 절차**

1. **개발용 IP와 운영용 IP를 구분**해서 토스쇼핑 담당자에게 전달해요. (환경별로 따로 등록되며, SFTP와 HTTPS를 명시해 주세요)
2. 등록 완료 후 호출이 정상 통과하는지 확인해요.

{% hint style="warning" %}
인프라 IP가 바뀌면 **즉시** 담당자에게 통보해주세요. 개발 환경에서 IP를 등록했더라도 운영 환경에서는 운영용 IP를 다시 등록해야 해요.
{% endhint %}

#### 공통 응답 Envelope

모든 API 응답은 동일한 공통 구조(envelope)를 사용해요. HTTP 상태 코드와 함께 본문의 `resultType`으로 성공/실패를 판단해요.

**성공 응답**

```json
{
  "resultType": "SUCCESS",
  "success": { },
  "error": null
}
```

**에러 응답**

```json
{
  "resultType": "FAIL",
  "success": null,
  "error": {
    "code": "INVALID_REQUEST",
    "reason": "에러 상세 메시지"
  }
}
```

<table><thead><tr><th>필드</th><th width="190.1171875">타입</th><th>필수</th><th>설명</th></tr></thead><tbody><tr><td><code>resultType</code></td><td>String</td><td>O</td><td><code>SUCCESS</code> 또는 <code>FAIL</code></td></tr><tr><td><code>success</code></td><td>Object/Boolean</td><td>조건부</td><td>성공 시 실제 응답 데이터, 에러 시 <code>null</code></td></tr><tr><td><code>error</code></td><td>Object</td><td>조건부</td><td>에러 시 <code>code</code>·<code>reason</code> 객체, 성공 시 <code>null</code></td></tr><tr><td><code>error.errorCode</code></td><td>String</td><td>O</td><td>에러 코드에 메시지</td></tr><tr><td><code>error.reason</code></td><td>String</td><td>X</td><td></td></tr></tbody></table>

#### 에러 코드

토스쇼핑 서비스 오류(SERVICE\_ERROR) 또는 시스템 장애(5xx 응답)로 에러 응답시 토스에서 재시도 요청을 할 수 있습니다.

<table><thead><tr><th width="143.69921875">HTTP Status</th><th>에러 코드</th><th>설명</th></tr></thead><tbody><tr><td>200</td><td>BAD_REQUEST</td><td>API Key 누락 또는 유효하지 않은 요청</td></tr><tr><td>200</td><td>INVALID_IP</td><td>허용되지 않은 IP</td></tr><tr><td>200</td><td>SERVICE_ERROR</td><td>토스쇼핑 서비스 에러 (재시도 필요)</td></tr><tr><td>5XX</td><td>INTERNAL_SERVER_ERROR</td><td>토스쇼핑 서버 장애 (재시도 필요)</td></tr></tbody></table>

#### 날짜/시간 포맷

| 항목               | 규격                                                              |
| ---------------- | --------------------------------------------------------------- |
| 날짜시간(`DateTime`) | ISO-8601 확장 포맷. `yyyy-MM-ddTHH:mm:ss`. 예: `2026-04-01T10:00:00` |
| 날짜(`Date`)       | `YYYY-MM-DD`. 예: `2026-04-01`                                   |

{% hint style="info" %}
모든 시각은 **KST 기준**으로 해석해요.
{% endhint %}

#### 솔루션사 경유 중복 주문 방지

샵링커·사방넷·플레이오토 같은 솔루션사를 함께 사용하면, 솔루션사 경로와 토스쇼핑 폴링 경로 양쪽에서 같은 주문이 수집될 수 있어, 기본적으로는 솔루션사에 주문 정보를 내려주지 않고 있어요

{% hint style="info" %}
솔루션사와의 연동을 원한다면 고객사 운영 정책에 맞춰 토스쇼핑 담당자와 합의해 주세요
{% endhint %}

### 셀러 연동 해제 API 준비

셀러 연동 해제 API는 토스 쇼핑 파트너스에서도 요청할 수 있어요. 이에 맞게 API 스펙을 작성하여 토스 쇼핑 내부로 전달해 주세요.

보편적으로 API에는 다음 정보는 필수로 받고 있어요.

* 입력: 토스쇼핑 Access Key, 풀필먼트 고객사 코드
* 출력: 성공 유무, (실패시) 실패 사유

또한 토스 내에서는 외부로 요청할 때 여러 보안 심사를 거쳐야 하기 때문에 풀필먼트의 ip(개발, 운영 각각)와 API 스펙을 미리 전달해 주는 편이 좋아요.

{% hint style="info" %}
풀필먼트에서 토스 호출할 때 방화벽을 해제했는지 또한 체크하는 것이 좋아요
{% 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/undefined.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.