쿠팡 오픈API, 키 발급 순서와 연동 범위표
쿠팡 오픈API로 상품 등록 · 주문 조회 · 송장 입력 · 반품 처리를 자기 프로그램과 잇는 방법을 정리했습니다. 영역별 연동 범위표, 직접 개발과 연동 솔루션을 고르는 기준, 윙에서 키를 받는 순서와 180일 유효기간, 개발 전에 확인할 것 8가지와 비용 요인을 담았습니다.

쿠팡 오픈API는 쿠팡 판매자가 윙(WING)에서 Access Key와 Secret Key를 발급받아 상품 등록 · 주문 조회 · 송장 입력 · 반품 처리를 자기 프로그램이나 연동 솔루션과 잇는 공개 API입니다. 공식 FAQ 기준 이용료는 없고, 별도 제휴 절차 없이 키를 받아 씁니다. 다만 키는 판매자 ID 하나에 하나만 나오고, 그 키에는 연동업체와 자체개발 가운데 하나만 등록할 수 있습니다. 그래서 키를 받기 전에 직접 개발할지 연동 솔루션을 쓸지, 상품 · 주문 · 출고 · 반품 중 어디까지 붙일지를 먼저 정합니다.
윙 가입과 첫 상품 등록은 쿠팡 윙 판매자 가입, 첫 상품 등록까지 순서에 있고, 이 글은 API 연동만 다룹니다.
쿠팡 오픈API로 무엇을 연동할 수 있나요
공식 API 문서는 업무 영역별로 묶여 있습니다. 기능 이름은 공식 문서 목차를 따랐고, 사양은 공지로 바뀔 수 있습니다.
| 영역 | 대표 기능(공식 문서 이름) | 연동하면 줄어드는 손일 |
|---|---|---|
| 상품 | 상품 생성 · 상품 수정 · 아이템별 가격 변경 · 아이템별 수량 변경 · 아이템별 판매 중지 | 상품 일괄 등록, 재고 · 가격 맞추기 |
| 배송 / 주문 | 발주서 목록 조회 · 상품준비중 처리 · 송장업로드 처리 · 주문 상품 취소 처리 | 주문 내려받기, 송장 번호 입력 |
| 반품 · 교환 | 반품 / 취소 요청 목록 조회 · 반품요청 승인 처리 · 회수 송장 등록 · 교환요청 목록조회 | 반품 접수 확인, 회수 송장 입력 |
| 고객 문의 | 상품별 고객문의 조회 · 답변, 쿠팡 고객센터 문의조회 · 답변 | 문의 모아 보기, 답변 입력 |
| 정산 | 매출내역 조회 · 지급내역조회 | 입금액과 주문 맞춰 보기 |
| 물류 정보 | 출고지 · 반품지 생성 · 조회 · 수정, 택배사 코드 | 출고지 · 반품지 관리 |
| 그 밖에 | 카테고리 · 브랜드 조회, 프로모션 · 쿠폰, 로켓그로스 | 카테고리 찾기, 쿠폰 운영 |
개발 회의에서 헷갈리기 쉬운 것은 상품을 가리키는 번호가 여러 개라는 점입니다. 공식 안내의 용어는 이렇습니다.
- sellerProductId(등록상품 ID) — 상품을 만들면 나오는 번호로, 바뀌지 않습니다.
- productId(노출상품 ID) — 쿠팡 화면에 보이는 단위로, 상품 결합 · 분리에 따라 바뀔 수 있습니다.
- vendorItemId(옵션 ID) — 가장 작은 상품 단위라 수정 · 반품에서 기준 번호로 씁니다.
- externalVendorSku(판매자상품코드) — 판매자가 옵션마다 넣는 관리용 코드로, 발주서를 조회할 때 함께 나옵니다.
자사 재고 프로그램과 묶는다면 우리 쪽 품목 코드를 판매자상품코드에 넣고, 바뀌지 않는 옵션 ID와 함께 저장해 두면 주문과 재고를 맞추기 쉽습니다.
직접 개발과 연동 솔루션은 어떻게 고르나요
키 발급 화면에서 업체 입력 방식을 연동업체와 자체개발 가운데 하나로 고릅니다. 연동업체는 목록에서 한 곳만 고를 수 있고, 자체개발은 업체명 · URL · 호출할 서버 IP를 직접 입력합니다.
| 기준 | 자체개발(직접 개발) | 연동업체(연동 솔루션) |
|---|---|---|
| 키 등록 | 업체명 · URL · 서버 IP(최대 10개) 입력 | 목록에서 쓰는 업체 1개 선택 |
| 맞는 경우 | 자사 재고 · ERP · 출고 프로그램과 실시간으로 묶을 때, 쿠팡 전용 처리 규칙이 많을 때 | 여러 오픈마켓 주문을 한 화면에서 처리하고 업무가 표준에 가까울 때 |
| 비용 구조 | 개발비 + 서버 비용 + 유지보수 | 솔루션 이용료(업체마다 다름) |
| 사양 변경 대응 | 공지를 보고 직접 고침 | 솔루션 업체가 반영 |
| 준비할 것 | 고정 IP가 있는 서버, 키 갱신 담당자 | 솔루션 계정, 키 입력 |
판매자 ID 하나에 키가 하나라서, 이미 연동 솔루션에 키를 쓰는 중이라면 같은 판매자 ID로 자체개발을 함께 등록할 수 없습니다. 이럴 때는 솔루션이 주문 · 상품 자료를 내보내는 기능이나 자체 API를 두고 있는지 그 업체에 먼저 묻고, 직접 개발로 옮길지 정합니다. 어떤 업무부터 자동화할지 고르는 순서는 업무 자동화, 어디서부터 시작하나에 있습니다.
키 발급은 어떤 순서로 하나요
- 판매자 등록 — 윙에서 판매자 등록과 사업자 인증을 마칩니다. 사업자 인증을 하지 않은 일반회원은 키를 받을 수 없습니다.
- 메뉴 찾기 — 윙에 로그인해 오른쪽 위 아이디를 누르고 판매자정보 또는 추가판매정보로 들어갑니다. 판매자 ID에 따라 메뉴 위치가 다를 수 있습니다.
- 발급 신청 — API Key 발급받기를 누르고 팝업에서 OPEN API를 고른 뒤, 약관에 동의하고 약관 동의 및 Key 발급 받기를 누릅니다.
- 업체 입력 — 연동업체 한 곳을 고르거나, 자체개발로 업체명 · URL · 서버 IP를 넣습니다. URL은 회사 홈페이지나 서비스 소개 주소를 넣고, 없으면 wing.coupang.com을 넣어도 된다고 안내돼 있습니다.
- 키 보관 — 화면에 나온 Access Key · Secret Key와 업체코드(vendorId)를 개발 담당에게 안전한 경로로 넘깁니다. 키는 온라인 문의 때도 적지 않습니다.
- 첫 호출 시점 잡기 — 처음 발급한 키는 바로 나오지만 실제 접근 권한은 내부 절차로 24시간 이상 걸릴 수 있고, 재발급 · 연동 정보 수정은 최대 30분 안에 쓸 수 있다고 안내돼 있습니다.
키 유효기간은 180일입니다. 만료 14일 전부터 재발급 버튼이 켜지고, 만료 2주 전과 1주 전에 판매자 이메일로 안내 메일이 옵니다. 재발급하면 기존 키는 바로 쓸 수 없게 되므로 재발급 → 서버에 새 키 넣기 → 호출 확인을 한자리에서 끝낼 날을 일정표에 미리 넣어 둡니다. 연동 정보 수정은 한 주에 10회까지입니다.
쿠팡 오픈API 개발 전에 무엇을 확인하나요
개발을 맡기기 전에 아래 8가지를 요구사항 문서에 적어 두면 개발 중에 되묻는 일이 줄어듭니다.
| 확인할 것 | 공식 문서 내용 | 개발에서 할 일 |
|---|---|---|
| 호출 방식 | REST · JSON · HTTPS, 호출 주소 api-gateway.coupang.com | 요청 · 응답을 기록으로 남김 |
| 인증 | 모든 요청의 Authorization 머리글에 HMAC 서명, 서명은 만든 뒤 최대 5분 유효 | 호출할 때마다 서명을 새로 만들고 서버 시계를 맞춤 |
| 접속 IP | 등록하지 않은 IP에서 부르면 403 Not allowed IP | 고정 IP 서버에서 호출, IP가 바뀌면 연동 정보 수정 |
| 테스트 환경 | 별도 테스트 환경은 제공하지 않음 | 실제 계정에서 시험용 상품 하나로 등록 · 수정 · 판매 중지를 확인 |
| 주문 조회 | 발주서 목록은 최대 31일, 한 페이지 최대 50개, 다음 페이지는 nextToken | 조회 기간을 나눠 반복 호출 |
| 배송지 변경 | 결제완료 상태에서 고객이 배송지를 바꿀 수 있음 | 상품준비중 처리 뒤 발주서 단건 조회로 배송지를 다시 확인 |
| 반품 완료 건 | 발주서 목록에서 조회되지 않음 | 반품 / 취소 요청 목록 조회를 따로 호출 |
| 상품 등록량 | 상품 등록은 하루 5천 개(옵션 기준)로 제한(공식 FAQ) | 대량 등록은 여러 날로 나눔 |
HMAC은 비밀 키로 요청 내용을 계산해 붙이는 인증 값입니다. 주문 상태 이름도 미리 맞춰 둡니다. 발주서 상태는 결제완료(ACCEPT) → 상품준비중(INSTRUCT) → 배송지시(DEPARTURE) → 배송중(DELIVERING) → 배송완료(FINAL_DELIVERY) 순이고, 업체 직접 배송으로 추적이 안 되는 건은 NONE_TRACKING입니다. 우리 프로그램의 주문 상태를 이 값과 하나씩 짝지어 두면 해석이 갈리지 않습니다.
연동 개발 비용은 무엇으로 정해지나요
API 이용료가 없으니 비용은 만드는 범위와 유지보수에서 나옵니다. 아래 다섯 가지를 적어 가면 견적을 같은 조건으로 비교할 수 있습니다.
- 연동 영역 수 — 상품만인지, 주문 · 송장 · 반품 · 문의까지인지
- 상품 구조 — 옵션 수, 카테고리별 필수 정보, 이미지 규격
- 다른 채널과 묶기 — 자사몰 · 다른 오픈마켓과 재고를 함께 맞추는지
- 서버 · 고정 IP — 등록한 IP에서만 호출되므로 고정 IP가 있는 서버가 필요
- 유지보수 — 180일마다 키 재발급, 공지로 바뀌는 API 사양 반영
프로그램 개발 견적을 영역별로 나눠 받으면 1차로 주문 · 송장만 붙이고, 상품 등록 자동화는 다음 차례로 미루는 식으로 나눠 갈 수 있습니다.
자주 묻는 질문
쿠팡 오픈API는 유료인가요?
공식 FAQ는 무료라고 안내합니다. 쿠팡 판매자라면 누구나 쓸 수 있게 공개돼 있고, 드는 돈은 직접 개발비나 연동 솔루션 이용료, 서버 비용입니다.
테스트용 환경이 따로 있나요?
키 발급 안내에 별도 테스트 환경은 제공하지 않는다고 적혀 있습니다. 실제 판매자 계정으로 시험하게 되므로 시험용 상품을 하나 정해 두고, 주문 쪽 기능은 실제 주문을 조회하는 것부터 확인합니다.
401 Specified signature is expired 오류는 왜 나나요?
HMAC 서명은 만든 뒤 최대 5분까지만 쓸 수 있어, 오래된 서명을 다시 쓰면 이 오류가 납니다. 호출할 때마다 서명을 새로 만들고, 그래도 나면 키 유효기간 180일이 지났는지 확인합니다.
연동 솔루션과 자체 개발을 같이 쓸 수 있나요?
공식 FAQ 기준으로 OpenAPI 키는 판매자 ID별로 하나만 발급되고, 연동업체 1개와 자체개발 1개를 동시에 등록할 수 없습니다. 둘 중 하나를 골라야 하므로 솔루션을 쓰는 중이라면 그 솔루션의 자료 내보내기 기능부터 확인합니다.
오늘 할 일
쿠팡에서 매일 손으로 하는 일(상품 수정 · 주문 확인 · 송장 입력 · 반품 승인 · 문의 답변)을 적고 옆에 하루 건수를 쓴 뒤, 건수가 가장 많은 일이 연동 범위표의 어느 영역인지 표시하세요.
이어서 읽기 — 파이썬 업무 자동화, 맡길 일 고르는 표와 명세 항목



