쿠팡 API 활용과 사용방법 8편 쿠팡 API V2 가이드 및 스크립트 생성기

쿠팡 파트너스 API V2 사용법과 자동화 스크립트 활용법

쿠팡 파트너스 API V2 추천 시스템: 블로그 운영자들이 자동으로 최적화된 상품을 노출할 수 있도록 도와주는 API 기능과 활용법을 소개합니다

---

쿠팡 파트너스 API는 쿠팡 파트너스 회원들이 쿠팡 내 상품 정보를 자동으로 조회하고, 추천 상품을 자신의 웹사이트나 블로그 등에 효율적으로 노출할 수 있도록 지원하는 개발자용 인터페이스입니다. 특히 V2 버전은 이전 버전인 V1과 비교해 여러 중요한 차이점을 가지고 있습니다.

사용자 중심의 추천 시스템으로, 기존 V1이 콘텐츠 내 특정 키워드나 핵심 내용을 기반으로 운영자가 보여주고 싶은 상품을 노출했다면, 쿠팡 API V2는 사용자의 환경과 행동에 맞춰 쿠팡에서 상품을 자동으로 추천하고 노출합니다. 이를 통해 방문자에게 더욱 맞춤화된 상품을 보여줄 수 있게 되었습니다.

또한,V2 버전은 보안과 기능 면에서도 크게 강화되어, 특히 HMAC 서명 방식을 활용한 안정적인 인증 체계를 갖추고 있습니다. 이처럼 쿠팡 API 활용방법에 있어 보안은 필수 요소로, 모든 API 호출 시 HMAC 서명이 포함되어야 합니다. 특정 상품을 최대한 노출시키고자 한다면, 기존에 작성한 쿠팡 상품 자동 노출 필터링 관련 글도 참고하시면 도움이 됩니다.

쿠팡 API 키 생성부터 호출까지, 파트너스 API V2 완전 정복

본 글에서는 쿠팡 자체 추천 상품 노출 방식과 쿠팡 API V2의 주요 특징을 상세히 다루며, 쿠팡 API 활용방법과 사용법은 물론, 쉽게 따라 할 수 있는 자동화 코드도 함께 제공합니다.

1. 쿠팡 파트너스 API란?

쿠팡 파트너스 API는 쿠팡 파트너스 회원들이 쿠팡 내 상품 정보를 자동으로 조회하거나, 추천 상품을 가져와 자신의 웹사이트나 블로그 등에 효율적으로 노출할 수 있도록 지원하는 개발자용 인터페이스입니다. V2 버전은 이전 버전보다 보안과 기능이 강화되어, HMAC 서명 방식으로 안정적인 인증이 가능합니다.

2. 쿠팡 API 시작하기: Access Key와 Secret Key 발급

쿠팡 파트너스 API는 최종 승인된 회원에게만 제공됩니다. 아직 최종 승인이 되지 않은 경우, 제휴 ID(AF ID)와 광고 게재 위치 및 광고 형태를 쿠팡 파트너스 메일로 문의하여 별도 검토를 받으실 수 있습니다.

API V2 키 발급 방법

1. 쿠팡 파트너스 사이트 상단 메뉴바에서 Tools 파트너스 API 로 이동하세요.
2. 생성 버튼을 클릭하면 바로 Access Key와 Secret Key를 발급받습니다.
3. 보안상 키는 절대 노출되지 않도록 관리해야 합니다.

3.쿠팡 API 호출 시 HMAC 서명 생성법

파트너스 API는 HMAC (Hash Message Authentication Code) 인증 방식을 사용합니다. 이는 API 호출 시 보안을 강화하는 암호화 프로토콜로, 모든 요청에 HMAC 서명을 포함해야 합니다.

// HMAC 서명 생성 Java 예시
public static String generate(String method, String uri, String secretKey, String accessKey) {
// 서명 생성 로직...
return String.format("CEA algorithm=HmacSHA256, access-key=%s, signed-date=%s,
signature=%s", accessKey, datetime, signature);
}

서명 생성 후 Authorization 헤더에 서명을 넣어 HTTP 요청을 보내면 인증이 완료됩니다.

4. 실제 쿠팡 파트너스 API 호출 예시

아래는 Java를 이용해 쿠팡 파트너스 API에 요청을 보내는 기본 예시입니다.

// OpenApiTestApplication.java 발췌
String authorization = HmacGenerator.generate(REQUEST_METHOD, URL, SECRET_KEY, ACCESS_KEY);
HttpRequest request = RequestBuilder.post(URL)
.setEntity(new StringEntity(REQUEST_JSON, "UTF-8"))
.addHeader("Authorization", authorization)
.build();
HttpResponse response = HttpClientBuilder.create().build().execute(host, request);
System.out.println(EntityUtils.toString(response.getEntity()));

성공 시 아래와 같은 JSON 결과를 받습니다.

{
"rCode": "0",
"rMessage": "",
"data": [
{
"originalUrl": "https://www.coupang.com/np/search?component=&q=good&channel=user",
"shortenUrl": "https://coupa.ng/bgQjht"
},
...
]
}

5. 파트너스 API V2 사용 시 주의사항과 자주 발생하는 문제

• Unknown error occurred 등 인증 실패 에러 발생 시, 키 값과 서명 생성 과정, API 엔드포인트 주소를 다시 한번 확인하세요.
• Access Key와 Secret Key는 개인정보와 같으니 철저히 보관해야 합니다.
• API 호출은 HTTPS 프로토콜을 사용해야 하며, CORS 정책에 맞게 설정되어야 합니다.

6. 쿠팡 API V2 키 스크립트 생성기 사용법

API 키를 직접 입력하고 쉽게 스크립트를 생성할 수 있는 간단한 웹 UI를 제공해드립니다.

UI 구성

• 쿠팡 Access Key 입력란
• 쿠팡 Secret Key 입력란
• 스크립트 생성 버튼
• 복사 및 초기화 버튼
• 생성된 API 키 코드 출력란 (읽기 전용)

주요 기능

• 입력한 키를 바탕으로 구글 앱스 스크립트용 인증 코드 자동 생성
• 복사 버튼으로 생성된 코드를 손쉽게 복사
• 초기화 버튼으로 입력값과 출력을 한번에 초기화

쿠팡 API 코드 자동생성기 사용 방법

1. 본인의 쿠팡 Access Key와 Secret Key를 입력하세요.
2. 코드 생성 버튼을 누르면 하단 출력란에 완성된 스크립트 코드가 나타납니다.
3. 복사 버튼으로 코드를 복사해 구글 앱스 스크립트에 붙여넣기 하세요.
4. 필요 시 초기화 버튼을 눌러 다시 입력할 수 있습니다.

쿠팡 API APP V2 스크립트 생성기

아래 코드는 https://script.google.com/ 사이트에 적용하세요. 적용 방법을 자세히 보시려면; 이 링크를 참고하세요.

아래에 쿠팡 API 키를 입력하면, 구글 앱스 스크립트용 코드를 생성합니다. 생성된 코드를 구글 앱스 스크립트에 붙여넣어 사용하세요.

1. 쿠팡 Access Key 2. 쿠팡 Secret Key

생성된 API 키 코드

쿠팡 API V2 스크립트 생성기

아래에 구글 앱스 주소, 광고 노출 위치, 쿠팡 제휴 아이디, 그리고 상품 노출 개수를 입력하면 블로그 사이트에 적용할 스크립트 코드를 생성합니다. 생성된 코드는 HTML의 body 상단에 삽입하시면 됩니다.

예: 광고를 노출하고자 하는 위치에 div id="coupang-ad-container"/div를 지정합니다.

1. 구글 app 주소 (WEB_APP_SEND_URL) 2. 광고 노출 ID (AD_CONTAINER_ID) 3. 쿠팡 제휴 ID 4. 노출 상품 수

생성된 스크립트 코드

HTML에 적용하는 CSS 예시

.coupang-ad-list {
 display: flex;
 flex-wrap: wrap;
 justify-content: center;
 gap: 20px;
}

.coupang-ad-item {
 margin: 10px;
 border: 1px solid #eee;
 padding: 10px;
 width: 180px;
 text-align: center;
 background: white;
 color: black;
 box-sizing: border-box;
 scroll-snap-align: start;
}

.coupang-ad-img {
 width: 150px;
 height: 150px;
 object-fit: contain;
}

.coupang-ad-name {
 white-space: normal;
 margin: 10px 0 8px;
 overflow: hidden;
 text-overflow: ellipsis;
 display: -webkit-box;
 -webkit-line-clamp: 2;
 -webkit-box-orient: vertical;
 color: #333;
 line-height: 1.4;
 font-size: 14px;
 min-height: 3.1em;
}

.coupang-ad-price {
 font-weight: bold;
 color: #0073e6;
}

.coupang-ad-footer {
 font-size: 12px;
 color: var(--pcs-border-tag-primary);
 margin-top: 15px;
 text-align: center;
}

/* 데스크탑 (768px 이상) */
@media (min-width: 768px) {
 .coupang-ad-list {
 flex-wrap: nowrap;
 justify-content: space-between;
 }

 .coupang-ad-item {
 flex: 0 0 calc((100% - 80px) / 5);
 /* 5개 일렬 배치, 간격 고려 */
 margin: 0;
 }
}

/* 모바일 (767px 이하) */
@media (max-width: 767px) {
 .coupang-ad-list {
 flex-wrap: nowrap !important;
 overflow-x: auto !important;
 scroll-snap-type: x mandatory !important;
 -webkit-overflow-scrolling: touch !important;
 padding: 10px 5px !important;
 margin: 10px 0 !important;
 gap: 12px !important;
 }

 .coupang-ad-list::-webkit-scrollbar {
 display: none !important;
 }

 .coupang-ad-item {
 flex: 0 0 auto !important;
 width: 220px !important;
 margin: 0 !important;
 border: none !important;
 box-shadow: 0 0 5px rgba(0,0,0,0.1) !important;
 border-radius: 6px !important;
 scroll-snap-align: start !important;
 background: white !important;
 }
}

쿠팡 API V2 직접 제작 시 꼭 알아야 할 주요 사항

쿠팡 API 응답 구조에 맞게 처리하기

쿠팡 RECO API는 실제 상품 정보가 data.result 배열 안에 들어 있습니다.
초기에는 data가 바로 배열인 줄 알고 처리했는데, 실제로는 data.result로 접근해야 정확한 상품 리스트를 얻을 수 있었습니다.

클라이언트 파라미터 제대로 받기

클라이언트에서 전달하는 deviceId, pageUrl, domain, ua, puid 등 필수 파라미터를 쿼리 스트링으로 받고, 이 값을 API 요청에 그대로 반영하여 쿠팡 API를 호출하도록 구현했습니다.

HMAC 시그니처(인증 헤더) 생성 코드 완성 및 적용

쿠팡 API는 모든 요청마다 인증용 **HMAC 시그니처**를 생성해 Authorization 헤더에 넣어야 합니다. 이 부분을 정확하게 구현하여 인증 오류 없이 API 요청이 정상 처리되도록 했습니다.

응답 데이터에서 필요한 정보만 추출해 클라이언트에 전달

Google Apps Script가 쿠팡 API 전체 응답을 받더라도, 클라이언트(티스토리 블로그 등)에는 상품 리스트만 data.result 형태로 깔끔하게 전달해 바로 활용할 수 있게 했습니다.

오류 발생 시 상세한 에러 메시지 반환

만약 API 호출이나 데이터 처리 중 문제가 발생하면, 어디서 오류가 났는지 알 수 있도록 상세한 에러 메시지를 포함해 응답하도록 하여 디버깅이 쉽도록 했습니다.

오류 발생 시 상세 메시지 반환하여 디버깅 쉽게

• 만약 문제가 생기면 어떤 부분에서 에러가 났는지 메시지를 포함해서 응답하도록 했어요.

쿠팡 파트너스 API V2는 파트너 여러분이 쿠팡 상품을 더 쉽게 노출하고, 맞춤형 상품 추천을 구현할 수 있도록 지원합니다. 이번 글에서 소개한 API 키 생성기와 HMAC 서명 방법을 참고해 편리하게 API를 활용하시길 바랍니다. 궁금한 점이나 오류 발생 시, 쿠팡 파트너스 고객센터 및 공식 문서에서 최신 정보를 확인하세요.

---

쿠팡 파트너스 API V2란 무엇이며, V1과 어떤 차이가 있나요?

쿠팡 파트너스 API V2는 쿠팡 상품 정보를 자동 조회하고 추천 상품을 사용자 환경에 맞게 자동 노출하는 개발자용 API입니다. 기존 V1은 운영자 중심으로 콘텐츠 키워드 기반 상품 노출이었지만, V2는 사용자 행동과 환경에 맞춘 맞춤형 추천 시스템으로 바뀌었습니다.

쿠팡 API V2를 사용하려면 어떻게 해야 하나요?

최종 승인된 쿠팡 파트너스 회원만 Access Key와 Secret Key를 발급받을 수 있습니다. 쿠팡 파트너스 사이트의 Tools > 파트너스 API 메뉴에서 키를 생성하며, 보안을 위해 키는 절대 노출하지 않아야 합니다. API 호출 시에는 HMAC 서명을 만들어 Authorization 헤더에 포함시켜야 인증이 완료됩니다.

쿠팡 API V2를 안전하고 효율적으로 활용하는 방법은 무엇인가요?

API 응답 구조(data.result)를 정확히 이해하고, 필수 파라미터(deviceId, pageUrl, domain, ua, puid)를 쿼리로 전달해야 합니다. HMAC 서명 생성 코드를 정확히 구현해 인증 오류 없이 호출하며, 오류 발생 시 상세 메시지를 받아 쉽게 디버깅할 수 있습니다. 또한, 키를 쉽게 생성하는 스크립트 생성기를 활용하면 편리합니다.