토스쇼핑 Open API 개발기 5편에서는 지금까지 진행한 OAuth 인증, 상품 조회, 상품 상세 조회에 이어 쉐어링크 발급 API를 실제로 호출해 shortUrl과 originUrl을 정상적으로 받아온 과정을 정리한다.
들어가며
지난 4편에서는 베스트 상품 목록에서 확보한 상품 하나를 대상으로 상품 상세 조회 API까지 연동을 마쳤다. 이번 5편에서는 같은 상품을 이용해 실제로 수익 집계가 걸리는 쉐어링크 발급 API를 호출하고, 그 결과로 shortUrl과 originUrl이 정상적으로 반환되는 것까지 확인했다. 이 글은 상품을 홍보하거나 구매를 권유하는 글이 아니라, Jukebox 플러그인에서 토스쇼핑 Open API 연동을 단계적으로 검증해 나가는 개발 로그(DevLog)다.
지금까지의 진행 상황
토스쇼핑 Open API 연동은 처음부터 한 번에 완성한 것이 아니라, 각 API 호출이 정상 동작하는지를 하나씩 확인하며 단계적으로 진행하고 있다.
처음에는 API 사용을 위한 승인과 Access Key / Secret Key 발급부터 진행했다. 이후 OAuth 토큰 발급과 Health API 호출로 서버 간 기본 연결을 확인했고, 연결이 확인된 뒤에는 베스트 상품 목록 API로 실제 상품 1건을 조회하는 데 성공했다. 그렇게 확보한 상품 ID를 이용해 상품 상세 조회 API까지 연동을 완료한 것이 4편의 내용이다.
이번 5편에서는 4편에서 상세 조회까지 마친 동일한 상품을 대상으로, 쉐어링크 발급 API를 호출하는 단계로 이어진다.
1편 API 키 발급 → 2편 OAuth·Health API 연결 확인 → 3편 상품 조회 API → 4편 상품 상세 조회 API → 5편 쉐어링크 발급 API (이번 글)
쉐어링크 발급 API란
토스쇼핑 Open API에서 쉐어링크 발급은 제휴사가 소개한 상품에서 발생한 구매 성과를 수익으로 정산받기 위한 핵심 기능이다. 공식 문서에서도 안내하듯, 상품 목록·상세 조회 API로 상품 정보를 확보한 다음 상품별로 쉐어링크(추적 링크)를 발급받아야 이후 발생하는 구매가 정산에 집계되는 구조다. 즉 지금까지 조회·상세조회 단계를 검증한 것은 이 쉐어링크 발급까지 이어지기 위한 준비 과정이었다고 볼 수 있다.
참고로 이번 테스트에서는 쉐어링크 발급에 write 권한이 포함된 scope로 OAuth 토큰을 발급받아 사용했다. 앞선 2편에서 발급한 토큰은 조회 권한 위주였기 때문에, 이번 호출을 위해 플러그인의 토큰 발급 로직에 쉐어링크 발급용 scope를 추가하는 작업이 먼저 필요했다.
테스트 환경
이번에도 별도의 신규 플러그인을 만들지 않고, 기존에 사용 중인 API 테스트 플러그인(jukebox-toss-sharelink-api-test)에 쉐어링크 발급 기능을 추가하는 방식으로 진행했다. WordPress 기반의 Jukebox 사이트에서 커스텀 플러그인을 통해 토스쇼핑 Open API를 직접 호출하고 있으며, API 기능을 하나씩 검증할 때마다 이 플러그인을 버전업하는 방식을 유지하고 있다.
API 호출에 사용한 Access Key, Secret Key, OAuth Access Token, 서버 공인 IP, Publisher ID는 개발기 특성상 본문에 실제 값을 노출하지 않고 마스킹하여 표기한다.
API 호출 과정
이번 테스트에서 사용한 상품은 4편에서 상세 조회까지 확인한 것과 동일한 상품이다.
| 항목 | 값 |
|---|---|
| 상품명 | 스파클 생수, 무라벨, 2L, 24개 |
| tacaItemId | 90382271 |
호출 과정은 다음과 같은 순서로 진행했다.
- 기존에 발급받은 Access Key / Secret Key로 쉐어링크 발급 권한(
writescope)이 포함된 OAuth Access Token 발급 - 4편에서 확보한
tacaItemId로 대상 상품 지정 - Jukebox 플러그인에 등록된 Publisher ID를 함께 파라미터로 전달
- 쉐어링크 발급 API 호출
API의 요청 구조와 파라미터는 토스쇼핑 쉐어링크 Open API 공식 문서에서 안내하는 연동 흐름(인증 정보 발급 → 액세스 토큰 발급 → 연결 확인 → 상품 조회 → 상세 조회 → 쉐어링크 발급)을 그대로 따랐다.
실제 테스트 결과
호출 결과 별다른 오류 없이 정상 응답을 받았다.
| 항목 | 결과 |
|---|---|
| HTTP Status | 200 |
| resultType | SUCCESS |
| tacaItemId | 90382271 |
| Publisher ID | 0c5d****7d93 (마스킹) |
| 서버 출발지 IP | 141.164.**.*** (마스킹) |
응답 본문에는 shortUrl과 originUrl 두 종류의 URL이 함께 반환됐다.
shortUrl과 originUrl
응답으로 받은 두 URL은 역할이 다르다. shortUrl은 실제로 게시물이나 채널에 노출할 때 사용하는 축약된 형태의 추적 링크이고, originUrl은 그 축약 링크가 실제로 연결되는 원본 경로로, 발급 시 사용한 Publisher ID와 연동 키가 쿼리 파라미터로 포함되어 있다.
| 구분 | 값 (테스트용) |
|---|---|
| shortUrl | https://toss.shopping/_m/XiKiH7F8 |
| originUrl | https://toss.shopping/t/56199215?k=e7f0-...(마스킹)&referrer=affiliate |
위 링크는 이번 API 연동 테스트 과정에서 실제로 발급받은 값이지만, 이 글은 상품을 소개하거나 구매를 유도하기 위한 글이 아니므로 클릭 가능한 링크가 아닌 코드 형태로만 기록해 둔다. originUrl의 쿼리 파라미터 중 일부는 식별 정보에 해당해 일부 마스킹했다.
이번 단계에서 확인한 것
이번 5편에서 쉐어링크 발급까지 성공하면서, 상품 조회 → 상품 상세 조회 → 쉐어링크 발급이라는 기본적인 상품 처리 흐름의 핵심 API 호출을 모두 개별적으로 검증했다. 지금까지의 개발은 각 API가 정상적으로 호출되는지를 하나씩 확인하는 과정이었고, 이번 단계에서 그 마지막 조각인 쉐어링크 발급까지 확인이 끝난 상태다.
아직 구현하지 않은 것
다음 항목들은 이번 테스트에서 다루지 않았고, 아직 구현하거나 검증하지 않은 부분이다.
- 여러 상품을 자동으로 선별하는 기능
- 조회한 상품을 자동으로 저장하는 기능
- 쉐어링크를 여러 상품에 대해 대량으로 발급하는 기능
- 상품 정보를 기반으로 SNS 콘텐츠를 자동 생성하는 기능
- 판매 성과를 자동으로 집계하는 기능
- 상품을 WordPress에 자동으로 게시하는 기능
현재까지는 각 API 기능을 개별적으로 검증한 상태이며, “자동화 시스템이 완성됐다”고 표현할 단계는 아니다.
다음 개발 방향
지금까지 확인한 API를 하나의 workflow로 연결하는 것이 다음 단계다. 가장 먼저 생각하고 있는 형태는 다음과 같다.
상품 1건 입력 → 상품 정보 조회 → 상품 상세 정보 조회 → 쉐어링크 발급 → 결과 저장
이후 필요에 따라 상품 후보 수집 → 상품 선별 → 상세 조회 → 쉐어링크 발급 → 결과 관리 형태로 확장하는 것을 고려하고 있다. 다만 이 부분은 아직 구현하지 않은 향후 개발 계획이다.
이번 5편에서는 토스쇼핑 Open API의 쉐어링크 발급 API를 호출해 HTTP 200 / resultType SUCCESS와 함께 shortUrl, originUrl을 정상적으로 받는 것까지 확인했다. 이로써 상품 조회부터 쉐어링크 발급까지, 기본적인 상품 처리 흐름에 필요한 핵심 API 연동을 개별적으로 모두 검증한 상태다.
자주 묻는 질문
쉐어링크 발급 API를 호출하려면 어떤 정보가 필요한가요?
이번 테스트에서는 write 권한이 포함된 OAuth Access Token, 대상 상품의 tacaItemId, 그리고 Jukebox 플러그인에 등록된 Publisher ID가 필요했다.
shortUrl과 originUrl은 어떻게 다른가요?
shortUrl은 실제 게시물에 노출하는 축약된 추적 링크이고, originUrl은 그 링크가 실제로 연결되는 원본 경로로 Publisher ID 등 식별 정보가 쿼리 파라미터에 포함되어 있다.
이번 테스트로 자동화가 완성됐나요?
아니다. 이번 단계는 쉐어링크 발급 API 호출 자체가 정상 동작하는지를 확인한 것이고, 여러 상품을 자동으로 선별하거나 콘텐츠를 자동 생성하는 기능은 아직 구현하지 않았다.
Access Key, Secret Key, Publisher ID 같은 정보는 왜 공개하지 않나요?
이 값들은 실제 API 호출 권한과 계정을 식별하는 인증 정보이기 때문에, 개발기 본문에서는 노출하지 않고 일부만 마스킹해 표기하거나 값을 아예 넣지 않는다.
다음 편에서는 어떤 내용을 다루나요?
지금까지 검증한 API들을 하나의 workflow로 연결하는 과정을 다룰 예정이다. 상품 조회부터 쉐어링크 발급, 결과 저장까지 이어지는 흐름을 구현하는 내용이 될 것으로 예상한다.
이전 개발기
마무리
상품 조회, 상품 상세 조회에 이어 쉐어링크 발급까지 API 호출 자체는 모두 정상적으로 동작하는 것을 확인했다. 다음 단계는 이 개별 API들을 하나의 흐름으로 엮어, 상품 1건을 입력하면 조회부터 쉐어링크 발급까지 이어지는 작은 workflow를 만들어보는 것이다. 자세한 구현 내용은 다음 편에서 이어서 기록할 예정이다.