쿠팡 카페24 주문 송장 재고 자동연동 - 중복차단

[새벽 3시에 자동화가 멈췄고, 아무도 몰랐습니다]

주문 수집 자동화는 만들기 쉽습니다. 어려운 건 이겁니다.

· 토큰이 만료됐는데 갱신에 실패했습니다. 그다음부터 전부 401 입니다.

· 레이트리밋에 걸려서 주문 절반만 처리됐습니다. 어느 절반인지 모릅니다.

· 재시도하다가 같은 주문에 송장을 두 번 등록했습니다. 고객이 전화합니다.

· 새벽에 죽었는데 아침까지 아무도 모릅니다.

· 어제 무엇이 처리됐는지 확인할 방법이 없습니다.

이 다섯 가지를 어떻게 처리하는지가 이 프로그램의 내용 전부입니다. 돌아가는 스크립트를 파는 게 아니라, 깨질 때 무슨 일이 일어나는가를 팝니다.

[무엇을 어떻게 막는가]

1. 같은 주문에 송장이 두 번 — 2단 멱등성

로컬 DB 기록만으로는 부족합니다. DB가 날아가면 그대로 중복됩니다. 그래서 전송 직전에 마켓에 다시 물어봅니다. 이 주문 이미 발송 처리됐습니까? 로컬 기록 + 마켓 재조회, 두 겹입니다. 주문 내용이 바뀌면 지문이 바뀌어 다시 처리합니다. 멱등성이 아무것도 안 하기로 퇴화하지 않게 하는 장치입니다.

2. 재고가 두 번 깎이는 문제 — 절대수량 전송

재고를 마이너스 3 같은 증감으로 보내면 재시도 한 번에 6개가 깎입니다. 이 프로그램은 절대수량만 보냅니다. 같은 요청을 몇 번 보내도 결과가 같습니다.

3. 레이트리밋 — Retry-After 준수 + 지수 백오프

마켓이 Retry-After: 7을 주면 그 값을 그대로 지킵니다. 없으면 1초, 2초, 4초, 8초로 물러나고 여기에 난수를 섞습니다(지터). 난수가 없으면 재시도가 동시에 몰려 두 번째 차단을 부릅니다.

4. 오류를 종류별로 다르게 처리

인증 만료는 즉시 1회 갱신 후 재시도하고, 두 번째 실패면 영구오류로 승격합니다. 레이트리밋은 Retry-After를 지키고 없으면 백오프합니다. 일시 오류는 백오프 + 지터. 영구 오류는 재시도하지 않고 알린 뒤 격리합니다. 될 리 없는 요청을 반복해 계정을 위험하게 만들지 않습니다.

5. 부분 실패 격리

쿠팡이 멈춰도 카페24는 계속 돕니다. 주문 한 건이 실패해도 나머지는 넘어갑니다. 실패한 건은 다음 실행에서 다시 잡고, 이미 성공한 건은 다시 보내지 않습니다.

6. 새벽에 멈추면 알림이 옵니다

멈춘 프로세스는 스스로 신고할 수 없습니다. 그래서 다음 실행이 종료 기록 없는 이전 실행을 찾아냅니다. 실패하면 Slack이나 Discord 웹훅으로 알립니다. 정상 실행에는 알림을 보내지 않습니다. 매번 오는 알림은 사람이 무시하게 되기 때문입니다.

7. 어제 무엇이 처리됐는지 남습니다

SQLite에 실행 이력, 주문 상태, 멱등성 기록, 이벤트가 쌓입니다. report 명령 한 줄로 조회합니다.

[크롤링, 매크로, 차단 우회를 쓰지 않습니다]

쿠팡 오픈API와 카페24 Admin API, 공식 API만 사용합니다. 화면을 긁는 매크로는 마켓이 화면을 바꾸면 그날 멈춥니다. 차단 우회는 계정 정지 위험을 고객에게 넘기는 일입니다. 저는 그 방식으로 만들지 않고, 그렇게 만들어 달라는 요청도 받지 않습니다.

[고객사 서버에 설치하는 방식입니다]

프로그램은 고객사 서버(또는 상시 구동 PC)에 설치되어 고객사 명의 API 키로 동작합니다. 저희가 고객사의 API 키를 보관하거나 저희 서버를 거쳐 중계하지 않습니다. 쿠팡 API 이용약관이 API 키의 제3자 공개를 금지하고 있기 때문이며, 동시에 고객사가 언제든 저희 없이 운영을 이어갈 수 있다는 뜻이기도 합니다.

카페24 연동 앱도 고객사 개발자센터 계정에 고객사 명의로 등록합니다. 등록 절차는 화면 공유로 함께 진행해 드립니다.

[개인정보를 저장하지 않습니다]

주문 데이터 구조에 주소, 전화번호, 우편번호 필드가 아예 없습니다. 송장 등록에 필요하지 않기 때문입니다. 저장하지 않는 데이터는 유출되지 않습니다. DB에 남는 것은 주문번호, SKU, 수량, 금액, 상태, 처리 시각뿐입니다. 이 필드들이 나중에 실수로 다시 생기지 않도록 테스트가 감시합니다.

[테스트 71개 — True를 반환했다를 세지 않습니다]

가짜 마켓 시뮬레이터를 만들어 중복 송장을 허용하도록 설정했습니다. 현실의 최악 케이스입니다. 그 상태에서 같은 실행을 5회 반복하고 송장 원장을 셉니다. 답은 마켓당 1건입니다.

· 같은 실행 5회 반복 시 송장 1건

· 로컬 DB를 전부 지워도 마켓 재조회로 중복 차단

· 송장번호가 바뀌면 다시 등록

· 백오프가 실측 1.16초, 2.01초, 4.28초, 8.45초로 증가하고 Retry-After: 7은 그대로 존중

· 한 마켓이 영구실패해도 나머지 마켓 처리 완료

· 종료 기록 없는 실행을 다음 실행이 잡아냄

· 정상 실행에는 알림 없음

이 로그는 상담 시 파일로 보내 드립니다. 생성 스크립트도 함께 드리므로 직접 돌려 보실 수 있습니다.

[설치가 가볍습니다]

Python 3.10 이상만 있으면 됩니다. 표준 라이브러리만 씁니다. pip install을 요구하지 않습니다. 사내 서버에서 외부 패키지 설치 승인을 받아야 하는 환경을 위한 선택입니다. API 키 없이도 전체 동작을 시연할 수 있습니다(mock 모드). 계약 전에 실제로 돌아가는 것을 보여드릴 수 있다는 뜻입니다.

[판매 범위 — 검증된 것과 안 된 것을 구분해서 씁니다]

· 쿠팡: 포함. 인증 서명은 첫 설치 시 실제 키로 검증하는 절차가 인수 조건에 있습니다.

· 카페24: 포함. 주문 및 물류 API 확인 완료.

· 스마트스토어: 기본 범위 제외, 별도 옵션.

스마트스토어 어댑터는 코드가 있지만 인증 방식과 API 경로가 추정값입니다. 그래서 검증 전에는 실서버 모드를 프로그램이 거부합니다. 설정에서 미검증을 감수한다를 명시적으로 켜지 않으면 시작하지 않고 멈춥니다. 검증 안 된 코드가 조용히 실서버에 붙어 고객 주문에서 첫 실패가 나는 것보다, 시작할 때 멈추는 게 낫습니다.

[자주 묻는 질문]

Q. API 키를 넘겨야 합니까?

아닙니다. 개발 자체는 키 없이 완료됩니다(mock 모드). 설치 단계에서 고객사 서버에 고객사가 직접 키를 입력합니다. 쿠팡 API 약관이 키의 제3자 공개를 금지하고 있어 저희가 보관하지 않는 것이 원칙입니다.

Q. 쿠팡 API 키가 180일마다 만료된다고 들었습니다.

맞습니다. 쿠팡은 만료 14일 전부터 재발급 버튼이 활성화되고 2주 전과 1주 전에 안내 메일이 갑니다. 이 프로그램은 인증 실패를 일시 오류와 구분해 즉시 알리므로, 갱신 시점을 놓쳐도 조용히 멈춘 채 방치되지 않습니다. 갱신 절차는 인수 문서에 적어 드립니다.

Q. 카페24 앱은 누구 명의로 등록합니까?

고객사 명의입니다. 카페24는 하나의 앱으로 여러 쇼핑몰에 서비스하도록 규정하고 있어, 개발사 계정에 고객사별로 앱을 여러 개 만드는 방식은 쓸 수 없습니다. 고객사 개발자센터 계정에서 등록하는 절차를 화면 공유로 함께 진행합니다.

Q. 마켓을 나중에 추가할 수 있습니까?

마켓별 차이는 어댑터 한 곳에만 있습니다. 추가 시 손대는 파일이 한 개이고 멱등성, 재시도, 이력 로직은 건드리지 않습니다. 추가는 유상입니다.

Q. 소스코드를 줍니까?

드립니다. 표준 라이브러리만 쓰기 때문에 인수 후 직접 수정 가능합니다.

Q. 세금계산서 발행됩니까?

법인이므로 발행합니다. 표시 금액은 부가세 포함가이며, 공급가액과 부가세를 구분해 세금계산서를 발행해 드립니다.

Q. 서버가 없는데요?

사내 PC 상시 구동으로도 됩니다. 다만 그 PC가 꺼지면 멈춥니다. 그래서 실패 알림 설정을 필수로 봅니다.

Q. 이미 다른 자동화를 쓰고 있는데 중복 송장이 났습니다.

그 상황이 이 프로그램의 출발점입니다. 상담에서 현재 흐름부터 보겠습니다.

[저에 대해]

와이앤피 테크놀로지 주식회사 · 대표 이병호. 사업자등록증상 개업 2004년 5월(22년), 등록 종목에 소프트웨어개발 포함, 법인 세금계산서 발행. 경력 연수는 사업자등록증으로 확인되는 숫자만 적었습니다.

1. 상담(무료) — 어떤 마켓을 쓰시는지, 하루 몇 건인지, 지금 무엇이 문제인지 확인합니다.

2. mock 모드 시연 — 고객사 API 키 없이 전체 동작을 보여드립니다.

3. 개발 범위 확정 — 요구사항 명세서로 서면 합의합니다.

4. 견적 및 계약

5. 결제

6. 개발 및 설정 — 범위에 따라 3~10 영업일.

7. 고객사 서버 설치 — doctor 점검 통과, dry-run, 실주문 1건으로 중복 차단을 눈앞에서 확인합니다.

8. 인수 확인서 서명

9. 보증 기간 무상 대응. 보증 만료 후에는 건별 유상 대응입니다.

[수정 및 재진행 조건]

합의된 요구사항 명세서 범위 안에서의 수정은 패키지에 표기된 횟수만큼 무상입니다. 명세서에 없던 기능 추가, 연동 마켓 추가, 고객사 시스템 변경으로 인한 재작업은 별도 견적입니다. 인수 확인서 서명 후 발견된 명세서 범위 내 결함은 보증 기간 동안 무상으로 수정합니다.

[쿠팡]

· 사업자 인증이 완료된 WING 판매자 계정

· 프로그램이 돌아갈 서버의 고정 IP (쿠팡에 최대 10개까지 등록 가능합니다)

[카페24]

· 개발자센터 계정 (고객사 명의로 개설해 주셔야 합니다)

· 앱을 설치할 쇼핑몰 ID

· https로 접근 가능한 주소 1개

[공통]

· 프로그램을 상시 구동할 서버 또는 PC

· 실패 알림을 받을 Slack 또는 Discord 웹훅 주소

준비가 안 되어 있어도 괜찮습니다. 무료 상담에서 무엇이 필요한지 함께 정리해 드리고, 발급 절차는 화면 공유로 같이 진행합니다.