Coupang Partners SDK 🛒

쿠팡 파트너스 API를 쉽게 사용할 수 있도록 도와주는 TypeScript/JavaScript SDK입니다.

✨ 특징

🔐 자동 인증: HMAC SHA256 CEA 서명 자동 생성
📘 TypeScript 지원: 완전한 타입 안정성 제공
🚀 다양한 API 지원: 상품검색, GoldBox, CoupangPL, 딥링크 API
🛡️ 향상된 에러 핸들링: HTTP 에러, JSON 파싱 에러 자동 처리
🔄 자동 재시도: 네트워크 오류 시 자동 재시도 로직
📊 상세 로깅: 구조화된 로깅 시스템과 디버그 모드
🧪 테스트 UI: 실시간 API 테스트를 위한 웹 인터페이스 제공

📦 설치

npm install coupang-partners-sdk-standalone

yarn add coupang-partners-sdk-standalone

🚀 빠른 시작

기본 설정

import { CoupangPartnersClient } from 'coupang-partners-sdk-standalone';

const client = new CoupangPartnersClient({
  accessKey: 'your-access-key',
  secretKey: 'your-secret-key',
});

상품 검색

// 키워드로 상품 검색
const searchResult = await client.searchProducts('아이폰', {
  limit: 10,
  imageSize: '230x230',
});

if (searchResult.rCode === '0') {
  const products = searchResult.data?.productData || [];
  console.log(`Found ${products.length} products`);

  products.forEach(product => {
    console.log(`${product.productName} - ₩${product.productPrice.toLocaleString()}`);
  });
}

GoldBox 상품 조회

// GoldBox 특가 상품 조회
const goldboxResult = await client.goldbox({
  subId: 'my-tracking-id',
  imageSize: '300x300',
});

if (goldboxResult.rCode === '0') {
  const products = goldboxResult.data || [];
  console.log(`Found ${products.length} GoldBox products`);
}

CoupangPL 상품 조회

// CoupangPL 상품 조회
const coupangplResult = await client.coupangPL({
  limit: 50,
  imageSize: '512x512',
  subId: 'my-tracking-id',
});

if (coupangplResult.rCode === '0') {
  const products = coupangplResult.data || [];
  console.log(`Found ${products.length} CoupangPL products`);
}

딥링크(Deeplink) 생성

// 쿠팡 URL을 파트너스 제휴 링크로 변환
const deeplinkResult = await client.deeplink({
  coupangUrls: [
    'https://www.coupang.com/vp/products/184614775',
    'https://www.coupang.com/vp/products/123456789',
  ],
  subId: 'my-tracking-id', // 선택사항
});

if (deeplinkResult.rCode === '0') {
  const links = deeplinkResult.data || [];
  links.forEach(link => {
    console.log(`Original: ${link.originalUrl}`);
    console.log(`Shortened: ${link.shortenUrl}`);
    console.log(`Landing: ${link.landingUrl}`);
  });
}

📚 사용 예제

필터링과 함께 GoldBox 사용

// 클라이언트 사이드 필터링 적용
const filteredResult = await client.goldboxWithFilters(
  {
    imageSize: '230x230',
  },
  {
    minPrice: 10000, // 최소 1만원
    maxPrice: 100000, // 최대 10만원
    categories: ['패션'], // 패션 카테고리만
    rocketOnly: true, // 로켓배송만
    freeShippingOnly: false, // 무료배송 조건 없음
  }
);

고급 설정 옵션

const client = new CoupangPartnersClient(
  {
    accessKey: 'your-access-key',
    secretKey: 'your-secret-key',
  },
  {
    timeout: 15000, // 15초 타임아웃
    debug: true, // 디버그 모드 활성화
  }
);

설정 업데이트

// 런타임에서 설정 변경
client.updateConfig({
  timeout: 20000,
  debug: false,
});

// 새 API 키로 업데이트
client.updateConfig({
  credentials: {
    accessKey: 'new-access-key',
    secretKey: 'new-secret-key',
  },
});

🧪 테스트 UI

SDK와 함께 제공되는 테스트 UI를 사용하여 실시간으로 API를 테스트할 수 있습니다.

테스트 UI 실행

# 테스트 프로젝트 클론 및 설정
git clone https://github.com/mooooburg-dev/coupang-partners-sdk-standalone.git
cd using-cp-sdk-test

# 환경 변수 설정
cp .env.local.example .env.local
# .env.local 파일에 실제 API 키 입력

# 개발 서버 실행
npm run dev

테스트 UI 기능:

3개 API 테스트: 상품검색, GoldBox, CoupangPL
실시간 파라미터 조정: 키워드, 결과 수, 이미지 크기 등
응답 데이터 시각화: 상품 카드, 가격, 배송 옵션 표시
에러 처리: 상세한 에러 메시지 및 처리 상태

📝 API 레퍼런스

CoupangPartnersClient

Constructor

new CoupangPartnersClient(credentials, config?)

Parameters:

credentials: CoupangCredentials - API 인증 정보
config?: Partial<SDKConfig> - 옵션 설정

Methods

Method	Description	Parameters	Returns
`searchProducts()`	키워드 상품 검색	`keyword: string, options?: ProductSearchOptions`	`Promise<ProductSearchResponse>`
`goldbox()`	GoldBox 상품 조회	`params?: GoldBoxParams`	`Promise<GoldBoxResponse>`
`goldboxWithFilters()`	필터링된 GoldBox 조회	`params?: GoldBoxParams, filters?: FilterOptions`	`Promise<GoldBoxResponse>`
`coupangPL()`	CoupangPL 상품 조회	`params?: CoupangPLParams`	`Promise<CoupangPLResponse>`
`deeplink()`	딥링크 생성 (URL 변환)	`params: DeeplinkParams`	`Promise<DeeplinkResponse>`
`generateSignature()`	HMAC 서명 생성	`method: string, url: string`	`string`
`updateConfig()`	설정 업데이트	`config: Partial<SDKConfig>`	`void`
`getConfig()`	현재 설정 조회	-	`Omit<SDKConfig, 'credentials'>`
`healthCheck()`	헬스 체크	-	`boolean`

타입 정의

Product (검색)

interface Product {
  keyword: string;
  rank: number;
  isRocket: boolean;
  isFreeShipping: boolean;
  productId: number;
  productImage: string;
  productName: string;
  productPrice: number;
  productUrl: string;
}

GoldBoxProduct

interface GoldBoxProduct {
  categoryName: string;
  isRocket: boolean;
  isFreeShipping: boolean;
  productId: number;
  productImage: string;
  productName: string;
  productPrice: number;
  productUrl: string;
}

CoupangPLProduct

interface CoupangPLProduct {
  categoryName: string;
  isRocket: boolean;
  isFreeShipping: boolean;
  productId: number;
  productImage: string;
  productName: string;
  productPrice: number;
  productUrl: string;
}

DeeplinkData

interface DeeplinkData {
  originalUrl: string; // 원본 쿠팡 URL
  shortenUrl: string; // 단축된 제휴 링크
  landingUrl: string; // 랜딩 페이지 URL
}

DeeplinkParams

interface DeeplinkParams {
  coupangUrls: string[]; // 변환할 쿠팡 URL 배열
  subId?: string; // 추적용 서브 ID (선택사항)
}

API 응답 형식

interface ApiResponse {
  rCode: string; // "0": 성공, 기타: 에러
  rMessage: string; // 응답 메시지
  data?: Product[]; // 상품 데이터 (API별로 다름)
}

설정 옵션

interface SDKConfig {
  credentials: CoupangCredentials;
  timeout?: number; // 기본값: 10000ms
  debug?: boolean; // 기본값: false
}

interface CoupangCredentials {
  accessKey: string;
  secretKey: string;
}

🔧 에러 처리

SDK는 다양한 에러 상황을 자동으로 처리합니다:

try {
  const result = await client.searchProducts('키워드');
} catch (error) {
  if (error.message.includes('401')) {
    console.error('인증 실패: API 키를 확인하세요');
  } else if (error.message.includes('429')) {
    console.error('요청 한도 초과: 잠시 후 다시 시도하세요');
  } else if (error.message.includes('HTML error page')) {
    console.error('API 서버 오류: 서비스 점검 중일 수 있습니다');
  } else {
    console.error('알 수 없는 오류:', error.message);
  }
}

🧪 테스트

# 전체 테스트 실행
npm test

# 테스트 감시 모드
npm run test:watch

# 커버리지 리포트 생성
npm run test:coverage

📄 예제 실행

# 기본 사용 예제
npm run example

# CoupangPL API 테스트
npx ts-node examples/test-coupangpl.ts

# GoldBox API 테스트
npx ts-node examples/goldbox-api-test.ts

🛠️ 개발 명령어

# 개발 모드 (watch)
npm run dev

# TypeScript 컴파일
npm run build

# 코드 검사
npm run lint

# 코드 포맷팅
npm run format

# 패키지 준비
npm run prepublishOnly

📋 요구사항

Node.js 16+
TypeScript 4.5+ (개발 시)
Coupang Partners API 인증 키

🔄 버전 히스토리

v1.2.5

🔧 딥링크 API 응답 타입 수정 (shortUrl → shortenUrl, landingUrl 추가)
📚 README 타입 정의 및 예제 코드 업데이트

v1.2.4

🐛 딥링크 API 엔드포인트 수정
🔧 README 타입 정의 수정 (shortenUrl → shortUrl)

v1.2.3

📚 README 딥링크 API 문서 업데이트

v1.2.2

✨ 딥링크(Deeplink) API 추가
🐛 버그 수정 및 안정성 개선

v1.2.0

✨ CoupangPL API 추가
🛡️ 향상된 에러 처리 (HTML 응답, JSON 파싱 에러)
🧪 테스트 UI 제공
📚 README 전면 개편
📄 예제 파일 추가

v1.0.0

✨ 상품 검색 API 지원
✨ GoldBox API 지원
📘 완전한 TypeScript 지원
🔐 HMAC SHA256 CEA 인증

📞 지원

🐛 버그 리포트: GitHub Issues
💡 기능 요청: GitHub Discussions
📧 문의: mooooburg.dev@gmail.com

📜 라이선스

이 프로젝트는 MIT 라이선스 하에 배포됩니다.

Made with ❤️ by mooooburg-dev

⭐ Star on GitHub | 📦 NPM Package

Name		Name	Last commit message	Last commit date
Latest commit History 30 Commits
examples		examples
src		src
tests		tests
.eslintrc.js		.eslintrc.js
.gitignore		.gitignore
.prettierrc		.prettierrc
CHANGELOG.md		CHANGELOG.md
CLAUDE.md		CLAUDE.md
LICENSE		LICENSE
README.md		README.md
jest.config.js		jest.config.js
package-lock.json		package-lock.json
package.json		package.json
tsconfig.json		tsconfig.json

Folders and files

Latest commit

History

Repository files navigation

Coupang Partners SDK 🛒

✨ 특징

📦 설치

🚀 빠른 시작

기본 설정

상품 검색

GoldBox 상품 조회

CoupangPL 상품 조회

딥링크(Deeplink) 생성

📚 사용 예제

필터링과 함께 GoldBox 사용

고급 설정 옵션

설정 업데이트

🧪 테스트 UI

테스트 UI 실행

📝 API 레퍼런스

CoupangPartnersClient

Constructor

Methods

타입 정의

Product (검색)

GoldBoxProduct

CoupangPLProduct

DeeplinkData

DeeplinkParams

API 응답 형식

설정 옵션

🔧 에러 처리

🧪 테스트

📄 예제 실행

🛠️ 개발 명령어

📋 요구사항

🔄 버전 히스토리

v1.2.5

v1.2.4

v1.2.3

v1.2.2

v1.2.0

v1.0.0

📞 지원

📜 라이선스

About

Resources

License

Uh oh!

Stars

Watchers

Forks

Releases

Packages 0

Uh oh!

Contributors

Uh oh!

Languages

Packages