관리자 화면만으로는 부족해질 때
카페24 관리자에서 주문을 보면 대부분의 운영은 됩니다. 그런데 ERP로 보내야 한다, 가맹·디자이너별로 다시 계산해야 한다, 우리 회사만 쓰는 검수 화면이 필요하다, 주문이 들어온 뒤 외부 프로그램에 자동으로 넣어야 한다 같은 요구가 생기면, 주문 데이터를 코드로 가져와야 합니다.
이때 쓰는 것이 카페24 API입니다. 가능 여부부터 말하면, 주문 목록·상세·품목·배송·일부 상태 변경은 API로 읽고 쓸 수 있습니다. 다만 관리자에서 보이는 그대로 한 번에 export되는 구조가 아니라, 인증·권한·조회 방식·별도 서버까지 포함한 흐름으로 설계해야 합니다. 카페24 주문 데이터를 외부에서 쓰려면, 목록 조회만으로는 부족하고 주문 상세·품목·상태까지 어떤 필드가 필요한지 먼저 정한 뒤 API·웹훅·별도 서버로 가져오는 구조를 잡는 편이 안전합니다.
주문 데이터를 가져오는 실무 흐름
첫 단계는 인증입니다. 카페24 API는 OAuth로 액세스 토큰을 발급받고, 필요한 권한(스코프)만 열어 사용합니다. 주문을 읽으려면 주문 조회 권한, 상태를 바꾸려면 쓰기 권한이 추가됩니다. 토큰과 클라이언트 시크릿은 쇼핑몰 스킨이나 브라우저에 두지 않고, 별도 서버에만 보관합니다.
두 번째는 무엇을 가져올지입니다. 주문 ‘목록’ API는 날짜·상태별로 주문번호와 요약 정보를 줍니다. ERP 전송, 정산, 품목별 수당 계산처럼 라인 단위 처리가 필요하면 ‘주문 상세’와 품목(아이템) 정보를 추가로 읽어야 합니다. 부분 취소·환불·교환처럼 상태가 바뀌는 업무는 상세를 다시 읽어 현재 취소 가능 수량과 금액을 확인한 뒤 API를 호출하는 흐름이 흔합니다.
세 번째는 언제 가져올지입니다. 정해진 시간에 하루치를 모아 가져오는 ‘조회(폴링)’ 방식과, 주문이 생기면 카페24가 우리 서버로 알려 주는 ‘웹훅’ 방식이 있습니다. 실시간에 가깝게 외부로 보내야 하면 웹훅·큐·재시도를 함께 두고, 하루 한 번 집계면 배치 조회만으로도 시작할 수 있습니다. 많은 경우 최종 구조는 카페24 API → 별도 서버(DB·로그) → ERP·정산·관리 화면 순입니다.
주문 API로 자주 하는 활용
외부 ERP·WMS에 주문·품목·배송 정보를 전송합니다. 가맹·후원·디자이너별 매출·수당을 주문 라인 기준으로 다시 계산합니다. 앱스토어에 없는 관리자 검수·리포트 화면에 필요한 컬럼만 모읍니다. 주문 상태 변경(출고·취소 등)을 우리 규칙에 맞게 자동화합니다. 각각 필요한 API 범위와 ‘읽기만 하는지·카페24 쪽 데이터를 바꾸는지’가 다릅니다.
기본·앱과의 경계
엑셀 내보내기·앱 export만으로 충분하면 API까지 가지 않아도 됩니다. 반복 수작업이 많거나, 외부 시스템과 양방향으로 맞춰야 하거나, 우리 규칙으로 가공·저장해야 하면 API·별도 서버 쪽을 검토합니다. 앱이 주문 데이터를 이미 다른 DB에 모아 준다면, 카페24 API를 직접 부르지 않고 앱 데이터를 쓸 수도 있지만, 앱을 바꿀 때 이전 데이터·필드가 남는지는 미리 확인해야 합니다.
- 인증: OAuth 토큰·스코프·서버 보관
- 조회: 목록 → 상세 → 품목 순으로 필요 범위 확장
- 시점: 배치 조회 vs 웹훅(이벤트) + 재시도
- 구성: API → 별도 서버 → ERP·정산·관리 화면
설계 전에 알아두면 좋은 제한과 실수
API 호출에는 제한(레이트리밋)이 있어, 주문이 많을 때 목록·상세를 한꺼번에 긁어 오면 막히거나 느려질 수 있습니다. 기간·상태·페이지를 나눠 가져오고, 이미 처리한 주문은 다시 부르지 않도록 마지막 처리 시점을 서버에 남기는 편이 안전합니다.
같은 주문을 두 번 ERP에 넣거나, 취소 API를 중복 호출하면 운영 사고로 이어질 수 있습니다. 주문번호·품목·처리 회차 같은 멱등 키를 서버에 두고, 웹훅이 두 번 와도 한 번만 처리하도록 설계합니다. 부분 취소·환불은 주문 상세를 다시 읽지 않고 호출하면 실패하거나 금액이 어긋나는 경우가 많습니다.
개인정보·결제 관련 필드는 꼭 필요한 범위만 저장하고, 관리 화면 접근 권한을 나눕니다. 테스트몰과 실몰 토큰·앱을 분리해, 연동 검증 후 실몰에 적용하는 순서를 지키는 것이 좋습니다. API 스펙·권한 정책은 바뀔 수 있으므로, ‘한 번 붙이면 끝’이 아니라 유지보수·로그·재처리 경로를 같이 두는 편이 현실적입니다.
안 될 때·비쌀 때 대안
당장 API 개발 여력이 없으면, 1차는 관리자 export·앱 리포트로 범위를 줄이고, 반복 업무가 줄었는지 먼저 확인합니다. 실시간이 꼭 필요하지 않으면 하루 1~2회 배치만으로도 CS 부담이 크게 줄어드는 경우가 있습니다. 읽기만 필요하고 규칙이 단순하면 앱+수작업, 읽기·쓰기·외부 연동이 섞이면 API·별도 서버 쪽으로 범위를 키우는 식으로 나눕니다.
- 목록만 가져와 품목·옵션이 빠져 ERP·정산이 틀어짐
- 웹훅·배치 중복 실행으로 같은 주문 두 번 전송
- 토큰·시크릿을 프론트·스킨에 넣어 유출
- 부분 취소·환불 전 상세 재조회 없이 API 호출
- 실몰에서 테스트 없이 대량 조회·상태 변경
옴니어스가 주문 API 연동을 설계할 때
옴니어스는 ‘주문 API 붙여 주세요’만으로 시작하지 않고, 어떤 화면·ERP·정산 규칙에 어떤 주문 필드가 필요한지부터 같이 적습니다. 읽기만 하면 되는지, 카페24 쪽 상태를 바꿔야 하는지, 웹훅이 필요한지를 나눈 뒤, 토큰·별도 서버·로그·재시도를 한 세트로 제안합니다.
기본·앱으로 되는 부분은 API까지 키우지 않도록 안내하고, 주문 라인 단위 계산·외부 연동·맞춤 관리 화면처럼 API가 필요한 구간만 1차·2차로 나눕니다. 자료가 정리되어 있지 않아도, 지금 엑셀로 하는 주문 처리 한 가지와 보내고 싶은 외부 프로그램 이름만 알려 주셔도 방향 잡는 데 도움이 됩니다.
주문 API 다음에 보면 좋은 글·페이지
API와 별도 서버가 왜 함께 필요한지, 부분 취소·외부 정산을 맞춘 사례, 수당·정산형 커스텀 사례, 제작 전 요구사항 체크리스트를 이어서 읽어 보시면 주문 연동 설계에 도움이 됩니다.
서비스·진행 방식·FAQ에서 연동 범위와 진행 흐름을 더 볼 수 있고, 문의 페이지에 ‘주문을 어디로·어떤 주기로 보내고 싶은지’만 남겨 주셔도 됩니다. 필요한 API 범위와 1차 구성을 기준으로 안내해 드립니다.