빠른 시작
토큰 발급부터 게시글에 넣을 링크를 얻기까지, 복사해서 바로 실행할 수 있는 5단계 예제입니다.
시작하기 전에 연동 시작하기에서 Access Key / Secret Key 발급과 출발지 IP 등록을 먼저 끝내주세요. 링크 발급에는 퍼블리셔 UUID(publisherId) 도 필요합니다. 어드민의 API 연동 화면에서 Access Key 아래 회원 연동 ID로 확인하실 수 있습니다.
아래 예제는 모두 운영 환경 기준입니다. 별도의 테스트 환경은 없습니다.
1단계 — 액세스 토큰 발급
발급받은 Access Key / Secret Key로 토스 인증 서버에서 액세스 토큰을 받습니다. 토스쇼핑 파트너 API와 동일한 인증 서버·방식(client_credentials)을 사용합니다.
토큰 발급 엔드포인트는 POST https://oauth2.cert.toss.im/token 입니다.
요청 본문은 application/x-www-form-urlencoded 형식입니다.
grant_type
client_credentials 고정
client_id
발급받은 Access Key
client_secret
발급받은 Secret Key
scope
조회만: sharelink:read / 조회 + 링크 발급: sharelink:read sharelink:write (공백으로 구분)
curl -X POST https://oauth2.cert.toss.im/token \
-H "Content-Type: application/x-www-form-urlencoded" \
-d "grant_type=client_credentials&client_id={Access Key}&client_secret={Secret Key}&scope=sharelink:read sharelink:write"응답의 access_token 값을 복사해 둡니다.
{
"access_token": "eyJhbGc...",
"scope": "sharelink:read sharelink:write",
"token_type": "Bearer",
"expires_in": 31535999
}이 토큰은 저장해 두고 계속 재사용하세요.
expires_in(초)이 유효기간이며, 만료 전에 재발급하시면 됩니다. API를 호출할 때마다 새로 발급받지 마세요. 과도한 재발급 요청은 이용이 제한될 수 있습니다.
2단계 — 연결 확인
인증과 IP 등록이 제대로 됐는지 확인합니다. HTTP 200뿐 아니라 아래처럼 resultType이 SUCCESS인지도 확인해 주세요. 이 엔드포인트는 연결성 확인 전용입니다.
이 응답이 나오면 준비가 끝난 것입니다. 실패한다면 이 페이지 아래 자주 겪는 문제를 확인해 주세요.
3단계 — 상품 목록 가져오기
지금 많이 팔리는 상품을 5개만 받아 봅니다.
여기서 tacaItemId 를 기억해 두세요. 다음 단계에서 이 값으로 링크를 발급합니다. (예제에서는 1234567890)
응답의
productUrl은 추적이 되지 않는 일반 링크입니다. 이걸 게시글에 넣으면 수익이 집계되지 않습니다. 4단계에서 발급받는 링크를 사용해 주세요.
4단계 — 쉐어링크 발급
3단계에서 얻은 tacaItemId 로 추적 링크를 발급합니다.
shortUrl 이 게시글에 넣을 링크입니다. 이 링크로 들어온 구매가 수익으로 집계됩니다.
발급받은 링크는 저장해 두고 재사용하세요. 같은 상품을 다시 요청하면 같은 링크가 나오지만, 매번 호출하면 호출 제한을 불필요하게 소모합니다.
캐시백·리워드 연동이라면
shortUrl대신originUrl에partner_ref_id를 붙여 제공해야 합니다. 주문 이벤트 수신을 봐 주세요.
5단계 — 게시
3단계에서 받은 상품명·가격과 4단계에서 받은 shortUrl 을 조합해 게시글을 구성하시면 됩니다.
이미지를 넣으시려면 먼저 공통 규약의 공통 주의사항에서 사용 범위를 확인해 주세요. 상세 페이지 이미지는 상품 상세 조회의 description.detailImageUrls로 받을 수 있습니다.
게시글에는 제휴 링크임을 알리는 대가성 문구를 함께 넣어 주세요. 표시 방법은 이용 주의사항의 대가성 문구 표시에 있습니다.
자주 겪는 문제
resultType 이 FAIL 이고 errorCode 가 SHARELINK_OPENAPI_ACCESS_DENIED
출발지 IP가 등록되지 않았거나 인증 정보가 유효하지 않습니다. 어드민에서 API를 호출하는 서버의 IP를 등록해 주세요. 내 PC가 아니라 서버 IP입니다 (IP 등록)
호출이 401로 막힘
토큰이 만료됐거나 잘못됐습니다. 1단계를 다시 실행해 주세요
호출이 403으로 막힘
응답 사유와 토큰의 스코프를 확인하세요. 링크 발급에는 sharelink:write가 필요합니다. 403만 보고 IP 오류로 단정하지 마세요
구매가 발생했는데 수익이 안 잡힘
productUrl 을 게시하셨을 가능성이 큽니다. 발급받은 shortUrl·originUrl 만 집계됩니다
응답은 왔는데 resultType 이 FAIL
HTTP 상태와 본문을 함께 확인하세요. 알려진 코드는 error.errorCode 로 구분하고, 코드가 없으면 error.reason 도 확인하세요 (오류 코드)
목록이 0건으로 옴
하루특가는 그날 편성이 없으면 0건일 수 있습니다. 오류가 아니므로 정상 처리해 주세요
같은 상품인데 링크가 두 개 생김
tacaId 로 발급하면 대표 상품이 바뀔 때 새 링크가 나옵니다. tacaItemId 로 발급해 주세요 (용어)
다음 단계
공통 규약 — 응답 형식·오류 코드·재시도·호출 제한·페이징
용어 —
tacaId와tacaItemId의 차이 등API 레퍼런스 — 엔드포인트별 상세 명세
주문 이벤트 수신 · 주문 이벤트 조회 — 캐시백·리워드처럼 구매·취소·구매확정을 제휴사 시스템에서 바로 알아야 할 때
Was this helpful?