스탬프 도장 추가 API (v2)

스탬프 도장 추가 API는 생성된 스탬프에 도장을 1개 추가하는 기능을 제공합니다.

고객이 구매, 방문, 특정 행동을 완료했을 때 이 API를 호출하면 해당 스탬프에 도장이 자동으로 적립됩니다.
단, 스탬프 카드에 설정된 최대 도장 수를 초과하면 추가 적립되지 않습니다.

이 API는 퍼스널 요금제 이상에서만 사용할 수 있습니다.

API Version

PUT

/api/stamp/v2/add

Request
Response

{
    "stampIdx": 394,
    "stamps": 1,
    "processStoreIdx": 22
}

Request Parameters

stampIdx integer required: 스탬프 IDX.
stamps integer: 적립(차감)할 도장 수. 보내지 않으면 1이며 0보다 커야 합니다.
카드 최대치를 넘거나 0 미만이 되는 분량은 서버가 잘라냅니다. 실제 변화량이 0이면 이력도 웹훅도 만들지 않습니다.
processStoreIdx integer: 이 요청이 실제로 처리되는 매장 IDX. 보내면 조직 소유·활성 상태·권한을 서버가 확인한 뒤 처리 이력에 기록합니다.
처리 지점은 요청으로 받지 않고 이 매장에서 서버가 확인합니다. 발행 매장(storeIdx)과는 다른 값입니다.

{
    "code": 0,
    "message": "",
    "result": null
}

Response Parameters

code integer: 응답 코드: 0 = 성공, 그 외 값 = 오류
message string: 응답 메시지입니다. 응답 코드가 0이 아니면, 오류 관련 메시지가 반환됩니다.
result null

숫자 파라미터 검증

숫자로 받는 파라미터에 숫자가 아닌 값이나 서버가 처리할 수 있는 범위를 넘는 숫자를 보내면 요청은 400(오류 코드 653)으로 즉시 거부됩니다.

이 경우 스탬프 정보와 적립 이력은 전혀 바뀌지 않으며, 이벤트 기록과 Webhook 전송도 발생하지 않습니다. 실패 응답을 받았다면 아무것도 저장되지 않은 상태입니다.

처리 매장 지정

파라미터	의미	설명
`processStoreIdx`	처리 매장	이 요청이 실제로 처리되는 매장입니다. 선택 항목이며, 보내면 조직 소유·활성 상태·권한을 서버가 확인한 뒤 처리 이력에 기록합니다.

처리 지점은 요청으로 받지 않습니다. 지정한 매장이 속한 지점을 서버가 확인해 기록합니다.

사용 가능 범위가 BRANCH인 경우, 확인된 처리 매장의 지점이 사용 가능 지점과 같거나 해당 지점의 현장 비밀번호로 인증해야 처리됩니다. 둘 다 없으면 거부됩니다.

사용할 수 없는 파라미터 — branchIdx(발행 지점), storeIdx(발행 매장), useScope(사용 가능 범위), useBranchIdx(사용 가능 지점)는 이미 저장된 발행 정책이라 이 API로 바꿀 수 없습니다. 함께 보내면 400(오류 코드 1227)으로 거부됩니다.

Idempotency-Key

네트워크 오류로 응답을 받지 못했을 때 안전하게 재시도하려면 Idempotency-Key 헤더에 요청마다 고유한 값을 담아 보냅니다. 본문의 requestId로도 보낼 수 있으며, 둘 다 보내고 값이 다르면 거부됩니다. 허용 형식은 영문·숫자와 . _ : - 를 조합한 8~64자입니다.

같은 key로 같은 요청을 다시 보내면 다시 처리하지 않고 최초 결과를 그대로 돌려줍니다. 중복으로 처리되지 않으며 웹훅도 다시 발송되지 않습니다.

같은 key는 같은 논리 작업의 재시도에만 사용하세요. 서로 다른 작업에는 반드시 새 key를 사용해야 합니다. 같은 key를 다른 요청 내용이나 다른 작업에 사용하면 409로 거부될 수 있습니다.

이 API가 스탬프 시스템의 핵심인 이유

스탬프 생성 API가 고객에게 적립 카드를 발급하는 역할이라면, 도장 추가 API는 고객의 실제 행동을 기록하는 역할입니다.

고객이 매장을 방문하거나 상품을 구매할 때마다 이 API를 호출하면, 별도의 포인트 시스템 없이도 고객 행동 기반의 리워드 프로그램을 완성할 수 있습니다.

결제 완료 이벤트, 상품 구매 완료, 설문 참여 등 어떤 행동이든 API 호출 하나로 도장 적립과 연결됩니다.

최대 도장 수 초과 시 처리 방법

스탬프 카드에 설정된 최대 도장 수에 도달한 상태에서 도장 추가 API를 호출하면 적립되지 않습니다.
이 시점에서의 올바른 처리 순서는 다음과 같습니다.

검증 API로 현재 stamps와 maxStamps를 확인합니다.
두 값이 같다면 도장이 모두 채워진 상태입니다.
수정 API에서 useYn을 Y로 변경해 혜택 사용 처리합니다.
쿠폰 생성 API를 연계 호출해 리워드를 자동 발급합니다.
새 스탬프를 생성해 다음 적립 사이클을 시작합니다.

적립 조건과 제한 사항

스탬프 적립은 무조건 증가하지 않습니다.

다음 조건을 만족해야 합니다.

스탬프 활성 상태 (activeYn = Y)
적립 기간 내 (strtYmd ~ endYmd)
최대 적립 수 미도달 (stamps < maxStamps)
사용 완료 상태가 아닐 것

이 조건을 통해 이벤트 정책에 맞는 정확한 적립이 보장됩니다.

활용 예시

방문 적립 이벤트: 사용자가 매장 방문 시 스탬프 1개 적립
구매 리워드 적립: 결제 완료 시 자동으로 스탬프 증가
미션 기반 이벤트: 특정 행동 완료 시 스탬프 지급
출석 체크 시스템: 매일 로그인 시 스탬프 1개 적립

운영 관점에서의 중요 포인트

스탬프 적립 API는 이벤트 품질을 좌우하는 핵심입니다.

잘못된 적립은 이벤트 신뢰도를 떨어뜨립니다
중복 호출 시 과도한 적립이 발생할 수 있습니다
사용자 경험과 직접 연결됩니다

따라서 반드시 검증 + 서버 단 로직 제어와 함께 사용해야 합니다.