API 인증 토큰 발급하기(통합솔루션사)

통합솔루션사가 Access Token을 발급받고 API를 호출하는 절차입니다.

토스쇼핑 API는 Bearer 인증을 요구해요. Bearer는 OAuth 프레임워크의 인증 방법입니다. 토스쇼핑 Access Token을 발급해서 API 호출 권한을 증명해주세요.

사전 준비하기

• 사전에 토스와의 계약이 필요해요. [e-mail]에 간단한 회사 설명과 함께 계약 문의 메일을 보내주세요.
• 계약이 되었다면 메일을 통해 토스쇼핑 API path에 입력할 통합솔루션 code을 받으세요.

  • 통합솔루션 code는 각 업체별 식별 코드예요. API 호출 시 path에 포함시켜 전용 경로를 활성화합니다.
  • [e-mail]에 메일을 보내서 통합솔루션 code를 요청해주세요.

연동 요청 메일은 이렇게 보내주세요. 토스 쇼핑 API 연동을 위해 API path에 사용될 통합솔루션 code 발급 요청합니다.

• 통합 솔루션사명: [회사명]
• 담당자: [이름 / 연락처 / 이메일]
• 운영 서버 IP (솔루션 -> 토스) : [IP 목록]
• 개발 서버 IP (개발연동 필요시) : [IP 목록]

판매자의 Access Token 발급받기

통합솔루션사는 Access Token 발급에 판매자의 Access Key와 Secret Key가 필요해요.

1

판매자에게 Access Key, Secret Key를 전달받으세요. 토스쇼핑의 셀러 어드민인 토스쇼핑 파트너스 > 사이드바 상단 '상점 이름' > 가맹점·계정 관리 > 페이지 하단의 '자체 개발' 섹션에서 확인할 수 있어요.

2

Access Token 발급을 위한 API를 호출해주세요.

• https://oauth2.cert.toss.im/token로 POST 요청을 보냅니다.
• Body에 아래 필드를 추가하세요.

필드명	설명
grant_type	client_credentials OAuth 인증 방식 지정
clientId	Access Key
clientSecret	Secret Key
scope	toss-shopping-fep:write 쓰기 권한 요청

curl -X POST https://oauth2.cert.toss.im/token \
    -H "Content-Type: application/x-www-form-urlencoded" \
    -H "Accept: application/json; charset=UTF-8" \
    -d "grant_type=client_credentials&client_id={토쇼파에서 확인한 access key}&client_secret={토스쇼핑파트너에서 확인한 secret key}&scope=toss-shopping-fep:write"

3

Access Token 발급에 성공하면 아래같은 JSON 응답이 반환돼요.

• Access Token은 토스쇼핑 API를 호출할 때마다 Bearer 인증에 써요. 안전하게 저장해주세요.
• 보안을 위해 유효 기간이 있어요. 만료 전 새로 발급받는 걸 권장하지만 너무 자주 요청하면 제한될 수 있어요.

{
	"access_token": "{발급된 accesse token}",
	"scope": "toss-shopping-fep:write",
	"token_type": "Bearer",
	"expires_in": 31535999
}

토스쇼핑 상품 카테고리 항목 조회 API 호출하기

Access Token으로 API를 호출해볼게요. Access Token이 유효해야 요청이 성공해요.

상품 카테고리 항목 조회 API는 GET 방식의 간단한 엔드포인트예요. 카테고리 ID를 넣으면 하위 카테고리를, 넣지 않으면 최상위 1차 카테고리를 반환합니다. 여기서는 1차 카테고리들을 확인해볼게요.

1

API 인증 header에 Bearer {발급된 access token}을 입력해주세요.

호출 시 path에 통합솔루션 code를 replace 해서 사용해 주세요.

• path 형식 예시: /api/v3/shopping-fep/{통합솔루션 code}/…

curl --location --request GET 'https://shopping-fep.toss.im/api/v3/shopping-fep/{통합솔루션 code}/products/categories/children' \
--header 'Authorization: Bearer {발급된 access token}'

2

호출에 성공하면 아래같은 응답을 반환합니다.

{
  "resultType": "SUCCESS",
  "success": {
    "items": [
      {
        "id": 14817,
        "name": "가구/홈데코",
        "level": 1,
        "parentId": null,
        "isLeaf": false,
        "policy": null
      },
      …
      {
        "id": 30343,
        "name": "출산/유아동",
        "level": 1,
        "parentId": null,
        "isLeaf": false,
        "policy": null
      },
      {
        "id": 34635,
        "name": "패션의류잡화",
        "level": 1,
        "parentId": null,
        "isLeaf": false,
        "policy": null
      }
    ]
  }
}

Access Token 오류가 발생해요

• Access Token의 유효 기간을 확인하세요.
• 정상적인 Header 형식(Authorization: Bearer {token}) 으로 전달했는지 확인하세요.
• Access Token에 오탈자나 공백이 없는지 확인하세요.
• 올바른 API 환경(예: 테스트 / 라이브)를 사용 중인지 확인하세요.

Access Token 발급과 API 호출을 성공적으로 마쳤습니다! 이제 토스쇼핑 API의 다양한 기능을 활용해 보세요.