카페24 재고 웹훅과 오프라인 POS 연동, 온·오프라인 재고를 맞춘 사례

온라인 쇼핑몰과 오프라인 매장을 함께 운영하다 보면 재고 수량이 서로 다르게 표시되는 문제가 발생할 수 있습니다.

매장에서 상품이 판매되어 POS 재고는 줄었는데 카페24 쇼핑몰에는 수량이 그대로 남아 있거나, 온라인에서 품절된 상품이 매장 POS에는 판매 가능한 상품으로 남아 있는 경우입니다.

이번 사례에서는 카페24의 재고 변경 웹훅과 별도 서버를 이용해 카페24 온라인몰과 오프라인 POS의 재고를 연동하고, 중복 처리와 재고 충돌을 줄이는 구조를 적용했습니다.

온라인몰과 오프라인 매장에서 같은 상품을 판매한다면 하나의 상품을 두 시스템이 함께 관리하게 됩니다.

예를 들어 매장에 상품이 10개 있다고 가정해 보겠습니다.

매장에서 2개가 판매되면 POS에는 재고가 8개로 변경됩니다.

그런데 이 내용이 카페24에 전달되지 않으면 온라인몰에는 여전히 10개가 남아 있는 것으로 표시될 수 있습니다.

반대로 온라인 주문으로 재고가 줄었는데 POS에 반영되지 않으면 실제 매장 재고와 POS에 표시되는 수량이 달라질 수 있습니다.

특히 다음과 같은 문제가 반복될 수 있습니다.

웹훅은 카페24에서 상품이나 재고에 특정 변경이 발생했을 때, 미리 연결해 둔 서버에 변경 내용을 전달하는 방식입니다.

예를 들어 카페24의 상품 재고가 변경되면 다음과 같은 흐름으로 처리할 수 있습니다.

카페24 재고 변경 → 웹훅 전달 → 별도 서버 확인 → POS 재고 변경

이 방식을 사용하면 사람이 카페24 관리자에서 재고를 확인하고 다시 POS에 입력하는 과정을 줄일 수 있습니다.

다만 웹훅을 사용한다고 해서 두 시스템의 재고가 항상 0초의 차이도 없이 완전히 동시에 변경되는 것은 아닙니다.

네트워크 지연이나 서버 오류, 재전송 등이 발생할 수 있기 때문에 웹훅을 안정적으로 처리할 별도 서버와 오류 재처리 구조가 중요합니다.

이번 연동에서는 카페24 화면이나 쇼핑몰 스킨에서 재고를 직접 처리하지 않고 별도 서버를 중간에 두었습니다.

기본적인 흐름은 다음과 같습니다.

① 카페24 재고 변경

카페24에서 상품 또는 옵션의 재고가 변경됩니다.

↓

② 재고 웹훅 수신

카페24가 별도 서버로 변경 내용을 전달합니다.

↓

③ 상품·옵션 매핑 확인

카페24 상품번호와 옵션 정보가 POS의 SKU 또는 바코드와 연결되어 있는지 확인합니다.

↓

④ 목표 재고 계산

현재 재고와 변경 내용을 기준으로 POS에 어떤 수량을 반영할지 결정합니다.

↓

⑤ POS 또는 재고 DB 반영

POS API가 제공되는 경우 POS에 직접 전달하고, 필요한 경우 중간 재고 DB를 통해 처리합니다.

↓

⑥ 처리 결과 기록

성공, 실패, 중복, 보류 등의 처리 결과를 서버 로그에 기록합니다.

카페24와 POS가 서로 다른 상품번호를 사용한다면 단순히 재고 수량만 전달해서는 안 됩니다.

예를 들어 카페24에서는

상품 A / 검정 / M

으로 관리하지만 POS에서는

SKU-10023

이라는 코드로 관리할 수 있습니다.

따라서 두 시스템의 상품과 옵션을 연결하는 매핑 테이블이 필요합니다.

일반적으로 다음과 같은 정보를 관리할 수 있습니다.

이 매핑 정보가 정확하지 않으면 같은 상품을 서로 다른 상품으로 인식해 재고가 잘못 변경될 수 있습니다.

재고 연동에서 중요한 부분 중 하나가 멱등 처리입니다.

쉽게 말하면 같은 변경 요청이 여러 번 들어오더라도 실제 재고에는 한 번만 반영되도록 만드는 것입니다.

예를 들어 카페24에서 재고 변경 이벤트가 발생했고 서버가 이를 처리했다고 가정해 보겠습니다.

네트워크 상황에 따라 동일한 이벤트가 다시 전달될 수 있습니다.

이때 서버가 아무런 확인 없이 POS에 다시 반영하면 재고가 중복으로 변경될 수 있습니다.

따라서 서버에서 이벤트 ID, 상품·옵션 정보, 처리 상태 등의 정보를 확인하고 이미 처리한 이벤트라면 다시 실행하지 않도록 구성합니다.

POS API 호출이 실패한 경우에는 바로 데이터를 버리는 것이 아니라 재시도할 수 있도록 별도의 대기 상태로 저장하는 방식도 사용할 수 있습니다.

온·오프라인 재고 연동에서 가장 먼저 정해야 하는 것이 재고 충돌 규칙입니다.

예를 들어 온라인 주문과 오프라인 판매가 거의 동시에 발생했다면 어느 쪽의 재고 변경을 먼저 인정할 것인지 정해야 합니다.

대표적으로 다음과 같은 기준을 사용할 수 있습니다.

중요한 것은 개발 전에 이러한 규칙을 먼저 정하는 것입니다.

“어느 시스템의 수량이 맞는가?”를 정하지 않은 상태에서 API만 연결하면 재고가 자동으로 맞춰지지 않습니다.

가능합니다.

예를 들어 다음과 같이 구성할 수 있습니다.

카페24 → 별도 서버 → POS

온라인 주문이나 카페24 재고 변경 내용을 POS에 전달하고,

반대로

POS → 별도 서버 → 카페24

매장에서 판매된 수량을 카페24 재고에 반영할 수 있습니다.

다만 양방향 연동에서는 한 가지 문제가 있습니다.

POS에서 재고가 변경되어 카페24에 전달되고, 다시 카페24의 재고 변경 이벤트가 발생해 POS로 전달되는 식으로 재고 변경이 계속 반복되는 루프가 발생할 수 있습니다.

따라서 각 변경이 어디에서 발생했는지 구분하는 출처 정보 등을 함께 관리해야 합니다.

정확히 말하면 완전히 동시에 일치한다고 보기는 어렵습니다.

웹훅과 API를 사용하더라도 네트워크 지연이나 서버 오류, POS 처리 지연 등이 발생할 수 있습니다.

특히 온라인과 오프라인에서 같은 상품이 동시에 판매되면 짧은 시간 동안 재고가 어긋날 수 있습니다.

따라서 실제 쇼핑몰에서는 다음과 같은 안전장치를 함께 고려할 수 있습니다.

즉, 목표를 “완벽한 실시간 일치”보다 “재고 오차를 최소화하고 문제가 생겼을 때 빠르게 복구할 수 있는 구조”로 잡는 것이 현실적입니다.

이 부분도 연동 전에 확인해야 합니다.

카페24에서는

처럼 옵션별 재고를 관리하지만 POS에서는 해당 상품 전체를 하나의 수량으로 관리할 수도 있습니다.

이 경우 카페24 옵션별 재고와 POS 재고를 단순하게 1:1로 연결할 수 없습니다.

따라서

등을 먼저 결정해야 합니다.

단순한 상품 조회와 달리 재고 연동은 실제 판매와 직접 연결됩니다.

따라서 카페24와 POS 사이에 별도 서버를 두면 다음과 같은 작업을 한곳에서 관리할 수 있습니다.

또한 API 토큰이나 웹훅 보안 정보와 같은 민감한 인증 정보도 쇼핑몰 화면에 노출하지 않고 서버에서 관리할 수 있습니다.

카페24와 POS 재고 연동을 시작하기 전에 다음 항목을 확인하는 것이 좋습니다.

이 항목이 정리되면 실제 개발 범위와 비용을 훨씬 정확하게 판단할 수 있습니다.

매장 수가 적고 상품 수도 많지 않다면 엑셀이나 카페24 관리자에서 수동으로 관리하는 것이 더 간단할 수 있습니다.

반면 다음과 같은 환경이라면 자동 연동의 필요성이 커집니다.

POS에서 API를 제공하지 않는다면 완전한 자동 연동이 어려울 수 있습니다.

이 경우에는 먼저 온라인 → POS 단방향 연동을 구축한 후 필요한 범위에서 양방향 연동으로 확대하는 방법도 있습니다.

옴니어스24는 카페24 엑스퍼트(Expert)를 통해 카페24 API와 웹훅을 활용한 다양한 외부 시스템 연동을 개발하고 있습니다.

재고 연동은 단순히 API를 연결하는 것보다 상품·옵션 매핑, 재고 기준, 충돌 규칙, 중복 처리, 오류 재처리를 먼저 정하는 것이 중요합니다.

따라서 개발 전에 현재 사용 중인 POS와 카페24의 상품번호, 옵션, SKU, 재고 관리 방식을 확인하고 연동 범위를 정합니다.

필요한 경우 테스트 환경에서 먼저 재고 변경과 오류 상황을 확인한 뒤 실제 쇼핑몰과 POS에 적용하는 방식으로 진행할 수 있습니다.