온라인은 품절인데, POS에는 재고가 남아 있던 과제
이 사례는 카페24expert 채널로 들어온, 오프라인 매장 POS와 카페24 온라인몰을 같이 쓰는 운영에서 시작됐습니다. 매장에서 판매하면 POS 수량은 줄지만 온라인에는 그대로 남아 주문이 들어오거나, 반대로 온라인에서 품절 처리했는데 매장 단말에는 수량이 남아 CS가 반복됐습니다.
엑셀로 하루 두 번 맞추는 방식으로는 피크 타임에 버티기 어려웠고, 카페24 관리자에서 재고를 수동 수정해도 POS와 ‘누가 최신인지’가 정해져 있지 않아 다시 어긋났습니다. 기본 재고 화면·앱만으로는 매장 POS의 품목 코드·창고 단위까지 자동으로 이어 주기 어려웠습니다.
- 온라인 품절·재고 변경과 POS 수량이 서로 다른 시점 기준으로 움직임
- 옵션·바코드·SKU 매핑이 없으면 같은 상품인데 수량이 갈라짐
- 웹훅 누락·중복 시 한쪽만 반영되어 과매·품절 오표시 위험
- 수작업 보정은 피크 타임에 따라가지 못함
재고 웹훅을 서버가 받아, POS 반영 순서와 충돌 규칙을 고정한 구현
접근의 핵심은 스킨이나 프론트에서 재고를 맞추지 않고, **카페24 품절·재고 변경 웹훅을 별도 서버가 수신한 뒤 POS API(또는 중간 재고 DB)에 반영**하는 흐름이었습니다. 카페24 상품·옵션 식별자와 POS 바코드·SKU를 매핑 테이블로 두고, 웹훅 payload의 수량·품절 플래그를 해석한 다음 POS에 보낼 증감·절대값을 계산했습니다.
같은 웹훅이 두 번 오거나 순서가 뒤바뀌는 경우를 대비해 **이벤트 ID·상품키·수신 시각 기준 멱등 처리**를 서버에 두었습니다. 이미 처리한 이벤트는 건너뛰고, POS 호출이 실패하면 재시도 큐에 남겨 운영자가 상태와 사유를 볼 수 있게 했습니다. ‘매장 판매가 우선인지, 온라인 주문이 우선인지’처럼 동시 변경 시 어느 쪽을 이길지 **충돌 규칙**을 문장으로 먼저 맞춘 뒤 코드에 반영했습니다.
토큰·웹훅 시크릿은 서버에만 두고, OAuth 스코프는 상품·재고 조회·웹훅 수신에 필요한 범위로 최소화했습니다. 테스트몰에서 품절 토글·부분 재고 감소·POS 실패 재시나리오를 돌린 뒤 실몰 키로 전환하는 Expert 검수 흐름을 같이 잡았습니다.
흐름을 나눈 기준
① 카페24 품절·재고 웹훅 수신 → ② 서명·시크릿 검증 후 매핑 조회 → ③ 충돌 규칙으로 목표 수량 결정 → ④ POS(또는 재고 DB) 반영 → ⑤ 성공·실패·스킵을 운영 로그에 기록. POS에서 먼저 팔린 경우에는 반대 방향(POS → 카페24 재고 API)도 같은 서버가 담당하되, 양방향이 서로 무한 루프를 만들지 않도록 ‘출처 플래그’로 웹훅 재발행을 구분했습니다.
맞추기 어려웠던 제한
웹훅은 ‘거의 실시간’이지 완전 동시가 아닙니다. 네트워크 지연·재전송 사이에 매장·온라인이 동시에 팔리면 순간적으로 수량이 어긋날 수 있어, 과매를 막으려면 안전 재고(버퍼)나 짧은 잠금 규칙을 두는 편이 현실적입니다. POS에 옵션 단위 재고가 없고 ‘대표 상품’만 있으면 카페24 옵션별 수량과 1:1로 맞출 수 없어, 합산·안분 규칙을 먼저 합의해야 했습니다.
- 상품·옵션 ↔ POS SKU 매핑 테이블
- 웹훅 멱등·재시도·실패 재처리 화면
- 동시 판매 시 충돌 규칙·안전 재고 버퍼
- 최소 스코프 OAuth·웹훅 시크릿은 서버 전용
품절·재고 변경이 POS와 같은 근거로 맞춰진 결과
결과적으로 온라인에서 품절·재고가 바뀌면 POS 쪽도 같은 매핑 기준으로 따라가고, 매장 판매분도 서버를 거쳐 카페24 재고에 반영되는 흐름을 만들 수 있었습니다. 어긋난 건은 로그에서 어느 이벤트·어느 SKU인지 추적하고, 실패 건만 재처리할 수 있게 됐습니다.
온오프 재고를 ‘완전 실시간 일치’로 약속하기보다, **웹훅 + 서버 + 충돌 규칙**으로 오차를 줄이고 과매·오표시 CS를 줄이는 쪽이 실무에 가깝습니다. POS API가 없거나 매핑이 불완전하면 1차는 단방향(온라인 → POS 표시용)만 열고, 양방향은 2차로 미루는 것도 현실적인 대안입니다.
- 품절·재고 변경 후 POS·몰 수량 불일치 CS 감소
- 웹훅 실패·중복을 운영자가 추적·재처리 가능
- 테스트몰 검증 후 실몰 전환으로 오픈 리스크 축소
옴니어스가 카페24expert에서 이 재고 연동을 맡은 방식
옴니어스는 **카페24expert에 등록된 카페24 파트너**로, Expert 채널 의뢰에서 **카페24 API·웹훅 개발에 특화**해 작업합니다. 재고처럼 금액·판매에 바로 영향이 가는 연동은 프론트에 시크릿을 두지 않고, 최소 권한·멱등·재시도·테스트몰 분리를 전제로 **전문적으로 안전하게** 진행하는 편이 맞습니다.
상담·설계 단계에서는 ‘어느 쪽이 수량 마스터인지’, ‘옵션·바코드 매핑이 있는지’, ‘과매를 어디까지 허용할지’를 먼저 문장으로 맞춥니다. 이미 엑셀로 맞추고 계시다면, 최근 어긋난 SKU 몇 개와 POS·몰 각각의 수량만 알려 주셔도 Expert 기준으로 범위를 잡는 데 도움이 됩니다.
재고·POS 사례 다음에 보면 좋은 글·페이지
매장 마스터·온오프 운영을 넓게 본 사례는 오프라인·온라인 통합 글에서, API와 별도 서버가 왜 필요한지는 API 안내 글에서 이어서 볼 수 있습니다. Expert 연동의 다른 축(부분취소·정산)은 Expert 부분취소 사례와, 상세 품절 노출은 품절 임박 수량 글과도 맥락이 닿습니다.
서비스·Expert·포트폴리오 페이지에서 연동 유형을 더 확인할 수 있고, 문의 페이지에 현재 재고가 어긋나는 상황만 남겨 주셔도 됩니다. 웹훅·POS·매핑 범위부터 같이 정리해 드립니다.