오픈마켓 API 연동, 마켓마다 인증·주문·상품 구조가 다른 지점

여러 마켓에 상품을 올리고 주문을 한곳에서 처리하려면 마켓마다 판매자 API를 붙여야 합니다. 저희 회사는 종합 오픈마켓의 상품 등록·수정, 카테고리·옵션 매핑, 재고 동기화, 주문 수집, 송장 전송까지 양방향 연동을 진행했고, 패션 전문몰과 해외 마켓 연동도 진행했습니다. 계약상 연동한 회사 이름은 밝히지 않습니다.

해 보면 API를 호출하는 코드보다 마켓마다 다른 규칙을 맞추는 일에 시간이 더 듭니다. 2026년 10월 기준 쿠팡, 네이버 스마트스토어, G마켓·옥션의 공식 문서로 어디가 다른지 정리했습니다.

한눈에 보는 차이

항목	쿠팡	네이버 커머스API	G마켓·옥션(ESM)
인증	HMAC-SHA256 요청 서명	OAuth2 토큰 + bcrypt 전자서명	직접 만드는 JWT(HS256)
키·토큰 유효	키 180일	토큰 3시간	토큰 유효시간 문서에 없음
사용 신청	판매자 계정(사업자 인증)에서 바로 발급	커머스API센터 가입, 애플리케이션 등록	메일 신청 후 심사, 거절될 수 있음
주문 조회 범위	일 단위 최대 31일, 분 단위 24시간 이내	변경 일시 기준, 생략 시 24시간, 한 번에 300건	문서 안에서 31일과 180일(옥션)이 다르게 적힘
호출 제한	판매자 ID 기준 초당 5회 이상이면 429	수치 비공개, 초과 시 429	주문조회 5초당 1회
형식	JSON	JSON	JSON
택배사 코드	영문 코드	영문 코드(쿠팡과 같음)	숫자 코드

1. 인증 방식이 세 마켓 모두 다릅니다

쿠팡은 요청마다 서명을 만듭니다. 요청 시각(GMT), HTTP 메서드, 경로, 쿼리를 이어 붙여 Secret Key로 HMAC-SHA256 서명을 만들고 Authorization 헤더에 넣습니다. 키 유효기간은 180일이고 만료 14일 전부터 재발급할 수 있습니다. 재발급하면 Secret Key가 새로 나옵니다.

네이버 커머스API는 토큰 방식입니다. client_id와 밀리초 단위 시각을 밑줄로 이은 값을 client_secret으로 bcrypt 해싱하고 Base64로 인코딩해 전자서명을 만든 뒤, 이 값으로 토큰을 받습니다. 서명에 넣은 시각은 5분 동안만 유효하고, 토큰은 3시간 유효합니다. 토큰이 만료되면 401(GW.AUTHN)이 오므로 그때 다시 발급받는 처리를 넣으라고 문서가 안내합니다.

G마켓·옥션은 ESM Trading API를 씁니다. 발급받은 Secret Key로 JWT를 직접 만들어 Bearer 헤더에 넣습니다. 헤더의 kid에는 ESM+ 마스터 ID를, 본문에는 사이트별 판매자 ID를 넣습니다.

세 마켓의 인증 코드는 공유할 부분이 거의 없습니다. 그래서 저희는 공통 인터페이스 아래에 마켓별 인증 모듈을 따로 두고, 키와 토큰의 만료 시각을 함께 저장합니다. 11번가도 2026년 6월 30일부터 OpenAPI 인증키 유효기간 180일 정책을 시행한다고 공지했으니, 키 만료를 미리 알리는 장치가 필요한 마켓이 늘었습니다.

2. 사용 신청 조건과 걸리는 시간이 다릅니다

마켓	신청 조건	주의할 점
쿠팡	Wing 판매자 계정(사업자 인증), 연동업체와 자체개발 중 선택	자체개발은 호출 IP를 최대 10개 등록. 키는 바로 나오지만 권한 반영에 24시간 이상 걸릴 수 있고, 테스트 환경이 없음
네이버	커머스API센터 가입, 애플리케이션 등록, API 그룹 권한	허용하지 않은 IP에서 호출하면 403(GW.IP_NOT_ALLOWED)
G마켓·옥션	판매자 회원과 ESM+ 마스터 ID를 갖춘 뒤 메일 신청	API 범위, 서비스 URL, 최근 3개월 매출, 개발 기간을 적어 내고 심사를 받음

패션 전문몰은 계정 종류에 따라 키가 아예 나오지 않는 곳도 있습니다. 2026년 9월에 저희가 확인한 기준으로, 에이블리는 셀러스 입점 타입에서만 API 연동이 열리고, 지그재그는 발급 창을 닫으면 시크릿 키를 다시 볼 수 없습니다.

이런 차이 때문에 저희는 계약 첫 주에 마켓별 계정 종류와 권한을 점검한 목록부터 만듭니다. 키가 늦게 나오는 마켓은 뒷순번으로 돌리면 전체 일정은 밀리지 않습니다.

3. 주문을 가져오는 방식이 다릅니다

세 마켓의 공식 문서에서는 주문이 생길 때 알려 주는 웹훅을 확인하지 못했습니다. 그래서 정해진 주기로 주문을 조회해 가져오는 구조가 기본입니다.

• 쿠팡: 발주서 목록을 일 단위 페이징으로는 최대 31일, 분 단위 전체 조회로는 24시간 이내로 가져옵니다.
• 네이버: 변경 상품 주문 조회가 변경 일시를 기준으로 합니다. 종료 일시를 생략하면 시작 시각부터 24시간이 적용되고, 한 번에 최대 300건을 받은 뒤 이어서 받습니다.
• G마켓·옥션: 주문조회 API는 5초에 1회만 호출할 수 있고, 주문번호로 조회할 때는 제한이 없습니다. 조회 기간은 같은 문서 안에서 31일과 옥션 180일로 다르게 적혀 있어 실제 호출로 확인해야 합니다.

마켓마다 조회 기준이 달라서, 마켓별로 마지막에 정상 조회한 시각을 저장해 두고 그 시각보다 조금 앞에서부터 겹쳐 조회하는 편이 안전합니다. 겹친 주문은 주문번호로 걸러 냅니다. 조회와 조회 사이에 생긴 주문을 놓치지 않기 위해서입니다.

4. 호출 제한은 숫자보다 바뀔 수 있다는 점이 중요합니다

쿠팡은 판매자 ID(vendorId) 기준으로 초당 5회 이상 호출하면 제한을 걸고 429를 돌려줍니다. 제한은 수 분에서 수십 분 뒤에 풀립니다. 그런데 공지에 이 기준이 사전 고지 없이 바뀔 수 있다고 적혀 있고, 상품 관련 API의 제한을 강화한다는 공지도 따로 있었습니다.

네이버는 API별·애플리케이션별로 요청량을 제한하지만 수치를 공개하지 않습니다. 초과하면 429(GW.RATE_LIMIT)가 오고, 남은 요청량은 응답 헤더로 확인합니다.

검색해 보면 쿠팡 판매자용 API와 제휴 마케팅용 쿠팡 파트너스 API의 호출 한도가 섞여서 나오는 경우가 있습니다. 판매자 연동은 판매자 Open API 문서 원문을 기준으로 잡아야 합니다.

그래서 호출 간격은 코드에 박지 않고 마켓별 설정값으로 둡니다. 429처럼 잠시 막힌 경우는 간격을 늘려 가며 다시 시도하고, 데이터가 규격에 맞지 않아 거부된 경우는 다시 시도하지 않고 실패 목록에 남겨 사람이 확인합니다. 두 경우를 이력에서 구분해 두면 운영할 때 원인을 바로 찾을 수 있습니다.

5. 상품 옵션과 택배사 코드도 마켓마다 매핑합니다

옵션 구조가 다릅니다. 쿠팡은 상품 1건 아래에 옵션 단위 상품(items)을 최대 200개 두고, 옵션명은 25자, 옵션값은 30자까지 받습니다. 네이버는 원상품 아래 채널상품을 두는 구조이고, 옵션은 단독형·조합형·입력형·표준형 네 가지이며 단독형과 조합형은 함께 쓸 수 없습니다. 패션 전문몰은 사이즈·컬러 옵션 구조가 종합몰과 달라서 저희도 매핑을 따로 잡아야 했습니다.

송장 전송 조건도 다릅니다. 쿠팡은 상품준비중 상태의 주문에만 송장을 올릴 수 있습니다. G마켓·옥션은 주문 확인 뒤에 발송 처리를 하고, 발송일은 호출 시점에서 2일 이내여야 합니다. 네이버는 여러 주문을 한 번에 발송 처리하고 성공과 실패 목록을 따로 돌려줍니다.

택배사 코드는 쿠팡과 네이버가 CJGLS(CJ대한통운), HANJIN, HYUNDAI(롯데택배), KGB(로젠), EPOST(우체국) 같은 영문 코드를 똑같이 씁니다. G마켓·옥션은 숫자 코드를 쓰고 택배사 조회 API로 확인합니다.

연동이 조용히 멈추는 날을 대비합니다

마켓 연동에서 실제로 곤란해지는 날은 붙이는 날보다 그 뒤에 조용히 멈추는 날입니다. 키가 만료되거나 마켓이 규격을 바꾸면 주문 수집이 멈춰 있는데도 관리 화면은 멀쩡해 보입니다. 며칠 뒤 고객 문의를 받고서야 알게 됩니다.

그래서 저희는 연동 완료 기준에 아래 네 가지를 넣습니다.

1. 상품 등록, 주문 수집, 송장 전송처럼 마켓이 달라도 하는 일이 같은 동작은 공통 인터페이스로 고정합니다. 새 마켓을 붙일 때는 규격 변환 부분만 만들면 됩니다.
2. 마켓별로 마지막에 정상 처리한 시각을 관리 화면에 보여 줍니다.
3. 일시 장애와 규격 거부를 구분해 기록하고, 실패 건은 목록으로 쌓아 다시 처리할 수 있게 합니다.
4. 키와 토큰의 만료일을 저장하고 만료 전에 알립니다.

연동 일정은 이렇게 잡습니다

마켓 4~5곳을 붙일 때 저희 회사가 잡는 대략의 일수입니다. 마켓 키가 나오기를 기다리는 시간은 넣지 않았습니다.

단계	일수
기존 구조 파악, 마켓별 규격 매핑 명세, 계정·권한 점검	5일
공통 구조(인증 키 관리, 연동 이력, 재시도)	5일
첫 마켓의 상품 등록부터 주문 수집, 송장 전송까지	5~7일
두 번째 마켓부터 마켓당	5일 안팎
운영자 확인 화면, 실제 주문으로 하는 테스트	7~10일

첫 마켓까지가 오래 걸리고, 공통 구조가 자리를 잡은 뒤에는 마켓 하나에 드는 시간이 눈에 띄게 줄어듭니다. 이미 다른 마켓을 연동해 쓰고 계시다면 기존 코드가 공통 구조를 쓰고 있는지에 따라 일정이 크게 갈립니다.

정리

오픈마켓 연동은 마켓 수만큼 같은 일을 반복하는 작업처럼 보이지만, 실제로는 인증, 주문 조회 범위, 호출 제한, 옵션 구조가 마켓마다 다릅니다. 견적을 받으실 때는 마켓 개수와 함께 키 만료 관리, 실패 건 재처리, 마지막 정상 처리 시각 표시가 범위에 들어 있는지 확인하십시오(견적서에서 확인하실 항목). 이 부분이 빠지면 연동은 붙어도 운영 중에 멈춘 것을 늦게 알게 됩니다.

저희 회사는 여러 마켓의 주문과 재고를 한 화면에서 처리하는 연동을 진행하고 있습니다. 연동하실 마켓 목록과 지금 쓰고 계신 시스템을 문의 페이지로 남겨 주시면, 마켓별로 먼저 준비하실 계정과 권한부터 정리해 드리겠습니다.