For the complete documentation index, see llms.txt. This page is also available as Markdown.

빠른 시작

토큰 발급부터 게시글에 넣을 링크를 얻기까지, 복사해서 바로 실행할 수 있는 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?