시작 전 준비

시작 전 준비

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

Base URL & 환경 분리

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

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

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

인증 방식 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는 개발 환경와 운영 환경이 별도의 키에 해당해요

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

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) 시 재발급 후 재호출해요.

자세한 내용은 API 인증 토큰 발급받기 문서를 참고해 주세요

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

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

등록 절차

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

인프라 IP가 바뀌면 즉시 담당자에게 통보해주세요. 개발 환경에서 IP를 등록했더라도 운영 환경에서는 운영용 IP를 다시 등록해야 해요.

공통 응답 Envelope

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

성공 응답

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

에러 응답

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

필드	타입	필수	설명
resultType	String	O	SUCCESS 또는 FAIL
success	Object/Boolean	조건부	성공 시 실제 응답 데이터, 에러 시 null
error	Object	조건부	에러 시 code·reason 객체, 성공 시 null
error.errorCode	String	O	에러 코드에 메시지
error.reason	String	X

에러 코드

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

HTTP Status	에러 코드	설명
200	BAD_REQUEST	API Key 누락 또는 유효하지 않은 요청
200	INVALID_IP	허용되지 않은 IP
200	SERVICE_ERROR	토스쇼핑 서비스 에러 (재시도 필요)
5XX	INTERNAL_SERVER_ERROR	토스쇼핑 서버 장애 (재시도 필요)

날짜/시간 포맷

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

모든 시각은 KST 기준으로 해석해요.

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

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

솔루션사와의 연동을 원한다면 고객사 운영 정책에 맞춰 토스쇼핑 담당자와 합의해 주세요

셀러 연동 해제 API 준비

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

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

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

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

풀필먼트에서 토스 호출할 때 방화벽을 해제했는지 또한 체크하는 것이 좋아요