쇼핑몰 API 연동 시 주문·상품·배송 데이터 구조

작성 2026-09-16

외부 채널과 연동할 때 주고받는 상품·주문·배송 데이터의 최소 구조와, 채널마다 다른 상태값을 내부 기준으로 변환하는 매핑 계층의 필요성을 설명합니다.

연동은 통신이 아니라 번역이다

외부 쇼핑몰이나 오픈마켓, 물류사와 연동할 때 사람들은 대개 "어떤 방식으로 호출하느냐"를 먼저 묻습니다. 하지만 실제 프로젝트에서 시간을 잡아먹는 것은 통신 방식이 아니라 서로 다른 개념을 우리 개념으로 옮기는 일입니다. 채널마다 상품 구조가 다르고, 주문 상태 이름이 다르고, 배송비를 계산하는 시점이 다릅니다.

그래서 연동 설계의 핵심은 변환 계층을 두는 것입니다. 외부 데이터를 그대로 우리 테이블에 넣지 않고, 우리 기준으로 바꾼 뒤 저장합니다.

주고받는 데이터는 크게 셋

1) 상품

내보낼 때 최소한 필요한 항목입니다.

• 내부 식별자(SKU) — 절대 바뀌지 않는 값
• 채널 식별자 — 채널이 부여한 상품/옵션 번호. 매핑 테이블에 저장합니다
• 표시 정보 — 상품명, 이미지, 상세
• 판매 조건 — 가격, 재고, 판매 가능 여부

2) 주문

가져올 때 조심할 점은 주문과 주문 항목의 단위입니다. 채널에 따라 항목별로 주문번호가 따로 발급되기도 하고, 부분 취소가 항목 단위로 일어나기도 합니다. 우리 쪽에서는 항상 다음 구조를 유지하는 편이 안전합니다.

• 주문 — 주문자, 결제 정보, 채널, 채널 주문번호
• 주문 항목 — SKU, 수량, 단가, 항목 상태, 채널 항목번호
• 배송 건 — 수령인, 배송지, 운송장. 주문과 1:N

수령인 정보는 주문이 아니라 배송 건에 두는 편이 낫습니다. 한 주문이 여러 곳으로 나뉘어 가는 경우를 자연스럽게 표현할 수 있기 때문입니다.

3) 배송

• 택배사 코드 — 채널마다 코드 체계가 다르므로 내부 코드로 통일하고 변환표를 둡니다
• 운송장 번호 — 박스 단위로 발급됩니다
• 배송 상태 — 채널의 상태값을 내부 상태로 매핑합니다

상태값 매핑이 진짜 일이다

채널 A의 "배송준비중"과 채널 B의 "출고대기"가 같은 의미일 수도, 다를 수도 있습니다. 그대로 저장하면 통계가 무의미해지고, 관리자 화면에서 상태가 뒤섞입니다.

• 내부 상태를 먼저 정의합니다 — 우리 업무 기준으로 10개 안팎이면 충분합니다
• 채널별 상태 → 내부 상태 변환표를 코드가 아니라 데이터로 관리합니다
• 변환되지 않는 값이 들어오면 버리지 말고 '미분류'로 저장하고 알림을 띄웁니다. 조용히 무시하면 나중에 원인을 못 찾습니다

동기화에서 반복되는 실수

전체 조회를 반복하는 것

매번 전체 주문을 가져오면 건수가 늘수록 느려지고 호출 한도에 걸립니다. 변경 시각 기준으로 증분 조회하고, 마지막으로 성공한 시각을 저장해 이어서 가져옵니다. 이때 시계 차이를 감안해 약간의 여유를 두고 겹쳐서 가져오는 편이 안전합니다.

중복 처리를 막지 않는 것

같은 주문이 두 번 들어오는 일은 흔합니다(재시도, 겹친 조회 구간). 채널 주문번호에 유일 제약을 걸고, 이미 있으면 갱신하는 방식으로 처리해야 주문이 두 건으로 쪼개지는 사고를 막을 수 있습니다.

실패를 로그로만 남기는 것

연동은 반드시 실패합니다. 상대 서버 점검, 네트워크, 형식 변경. 실패 건을 재처리 가능한 데이터로 남겨 두고 관리자 화면에서 볼 수 있게 해야 합니다. 로그 파일에만 남기면 아무도 보지 않습니다.

재고 동기화의 방향

가장 사고가 잦은 부분입니다. 한 상품을 여러 채널에서 팔면 재고를 어떻게 나눌지 정해야 합니다.

• 공유 — 전체 재고를 모든 채널에 동일하게 노출. 단순하지만 동시 주문 시 초과 판매 가능
• 배분 — 채널별 할당량을 둠. 초과 판매는 막지만 할당 조정 운영이 필요
• 안전 재고 — 실제보다 적게 노출해 여유를 둠. 가장 현실적인 절충

어느 방식이든 재고 변경은 한 곳(내부 시스템)에서만 일어나고, 채널로는 내보내기만 하도록 방향을 고정해야 혼선이 없습니다.

정리

연동 설계에서 기억할 것은 세 가지입니다. 식별자는 매핑 테이블로, 상태값은 변환표로, 실패는 재처리 가능한 데이터로. 이 셋을 지키면 채널이 하나 늘어도 구조를 바꾸지 않고 붙일 수 있습니다. 반대로 외부 형식을 그대로 받아 저장하면, 채널이 늘 때마다 테이블이 늘어납니다.

관련 내용