온라인 스탬프 수정 API

API Version

PUT

/api/stamp/v2/update

Request
Response

{
    "stampIdx": 1457,
    "cardIdx": 172,
    "stamps": 7,
    "useYn": "Y",
    "onsiteToken": "QsBkV0ryiCkxiV4KUNJBSWQcR8MzSlvez4ntLh2Tt2M",
    "resetPinYn": "Y",
    "userEml": "example@gmail.com",
    "branchIdx": 11,
    "storeIdx": 22,
    "useScope": "BRANCH",
    "useBranchIdx": 11
}

Request Parameters

stampIdx integer required: 스탬프 IDX.
cardIdx integer: 카드 IDX. 카드 IDX는 대시보드의 “스탬프 카드” 페이지에서 확인할 수 있습니다.
stamps integer: 스탬프에 적립된 도장 개수를 지정합니다.
현재 고객이 모은 도장의 총 개수를 나타냅니다. 값을 변경하면 스탬프 적립 현황이 갱신되며, 증가·감소 모두 가능합니다.
모든 도장을 채운 경우(stamps = 카드에 설정된 최대 도장 수)에는 useYn을 Y로 변경하여 혜택 사용 상태로 처리해야 합니다.
resetPinYn string
Default:N
Enum: YN: 스탬프를 사용하는 고객의 PIN 번호를 초기화할지 여부를 지정합니다.
Y: 고객이 설정한 PIN 번호를 초기화합니다. 초기화 후, 고객은 스탬프 페이지 접속 시 새 PIN 번호를 다시 설정해야 합니다.
N: 기존 PIN 번호를 유지합니다.
useYn string
Default:N
Enum: YN: 스탬프의 혜택 사용 여부를 지정합니다.
Y: 고객이 모든 도장을 채우고 혜택(예: 무료 음료, 할인 등)을 사용한 상태입니다. 혜택 사용 후에는 해당 스탬프가 비활성화되며, 새 스탬프를 발급해야 합니다.
N: 아직 혜택을 사용하지 않은 상태입니다.
N에서 Y로 변경할 때는 저장된 도장 수가 카드의 최대 도장 수에 도달해 있어야 하며, 현장 적립용 비밀번호가 설정된 스탬프라면 onsiteToken를 함께 보내야 합니다.
onsiteToken string: 현장 처리용 단기 교환 증표. v2는 비밀번호 평문(onsitePwd)을 받지 않습니다.
스탬프에 onsiteYn = Y가 설정돼 있으면, 검증 API(Validate) 응답의 onsiteToken을 그대로 보내세요.
증표를 쓰는 요청에는 Idempotency-Key가 필수입니다. 같은 key의 재시도는 최초 결과를 그대로 재생하고, 다른 key로 같은 증표를 다시 쓰면 400(오류 코드 1228)으로 거부됩니다.
검증에서 처리 매장을 지정했다면 이 요청의 처리 매장도 같아야 합니다. 매장 없이 검증한 증표에 매장을 새로 붙일 수도 없습니다.
domain string
Default:https://vvd.bz: 스탬프 도메인. 값이 비어있으면 기본 도메인으로 저장됩니다.
프리미엄 요금제 이상에서는, 링크 도메인 관리에서 등록한 커스텀 도메인을 지정할 수 있습니다.
strtYmd date: 스탬프 유효 시작일. 예: 2025-01-01
endYmd date: 스탬프 유효 만료일. 예: 2025-12-31
만료일은 오늘로 부터 최대 5년까지 설정할 수 있습니다.
activeYn string
Default:Y
Enum: YN: 스탬프 활성화 여부. 비활성화되면 고객이 스탬프를 사용할 수 없습니다.
memo string: 내부 참고용 메모.
userId string: 사용자 ID. 스탬프 발급 대상자를 관리하는데 사용됩니다.
일반적으로 웹사이트 회원의 로그인 ID를 입력합니다.
설정되지 않으면 시스템에 의해 자동으로 사용자 ID가 생성됩니다.
userNm string: 사용자 이름. 내부 관리용.
userPhnno string: 사용자 연락처. 내부 관리용.
userEml string: 사용자 이메일. 내부 관리용.
userEtc1 string: 추가 내부 관리용 필드.
userEtc2 string: 추가 내부 관리용 필드.
branchIdx integer: 발행 지점 IDX. 보내지 않으면 본사 발행이며, 0을 보내면 본사로 비웁니다.
비즈니스 요금제 이상에서만 사용할 수 있습니다.
storeIdx integer: 발행 매장 IDX. 지정하면 그 매장이 속한 지점이 발행 지점이 됩니다. 다른 지점을 함께 보내면 오류입니다.
useScope string: 사용 가능 범위. ALL(모든 매장) 또는 BRANCH(특정 지점)만 허용됩니다. 보내지 않으면 ALL입니다.
useBranchIdx integer: 사용 가능 지점 IDX. useScope = BRANCH일 때만 필요하며, ALL이면 항상 비어 있습니다.

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

Response Parameters

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

숫자 파라미터 검증

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

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

발행 지점·매장과 사용 가능 범위

여기서 지정하는 값은 발행 시점에 저장되는 정책입니다. "어디에서 발행됐는가"(발행 지점·발행 매장)와 "고객이 어디에서 쓸 수 있는가"(사용 가능 범위·사용 가능 지점)는 서로 다른 개념이므로 파라미터도 나뉘어 있습니다.

파라미터	의미	설명
`branchIdx`	발행 지점	보내지 않으면 본사 발행입니다. `0`을 보내면 본사로 비웁니다.
`storeIdx`	발행 매장	지정하면 그 매장이 속한 지점이 발행 지점이 됩니다. 다른 지점을 함께 보내면 거부됩니다.
`useScope`	사용 가능 범위	`ALL`(모든 매장) 또는 `BRANCH`(특정 지점). 보내지 않으면 `ALL`입니다.
`useBranchIdx`	사용 가능 지점	`useScope=BRANCH`일 때만 필요합니다. `ALL`이면 항상 비어 있습니다.

사용할 수 없는 파라미터 — processStoreIdx(처리 매장)는 검증·사용·적립·차감이 실제로 일어난 매장을 가리키는 값이라 이 API에서는 쓸 수 없습니다. 함께 보내면 400(오류 코드 1227)으로 거부됩니다.

지점·매장 기능은 비즈니스 요금제 이상에서만 사용할 수 있습니다.

Idempotency-Key

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

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

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

도장 수를 직접 제어해야 하는 이유

스탬프 시스템을 운영하다 보면 단순 적립 외에 도장 수를 직접 조정해야 하는 상황이 생깁니다.

고객 오적립 수정, 이벤트 보너스 지급, 관리자 수동 조정이 대표적인 경우입니다.

stamps 파라미터에 원하는 도장 수를 입력하면 현재 값을 덮어쓰지 않고 증가·감소 방향으로 변경할 수 있습니다.
단, 모든 도장을 채운 경우(stamps 값이 카드에 설정된 최대 도장 수에 도달)에는 useYn을 Y로 함께 변경해 혜택 사용 처리를 해야 합니다.

혜택 사용 처리와 스탬프 재발급 흐름

useYn을 Y로 설정하면 해당 스탬프가 혜택 사용 완료 상태로 전환됩니다.

혜택 사용 후 새 스탬프를 다시 시작하려면 스탬프 생성 API로 새 스탬프를 발급해야 합니다.
이 흐름이 스탬프 기반 리워드 프로그램의 핵심 사이클입니다.
혜택 사용 → 신규 발급 → 재적립으로 이어지는 구조를 API로 자동화하면 고객이 매장을 재방문할 동기를 지속적으로 만들 수 있습니다.

현장 인증 토큰 (onsiteToken)

v2는 현장 비밀번호 평문(onsitePwd)을 받지 않습니다. 검증 API(Validate)가 반환한 onsiteToken을 그대로 전송하세요. onsitePwd만 보내거나 onsiteToken과 함께 보내면 400(오류 코드 1227)으로 거부됩니다.

토큰을 사용하는 요청에는 Idempotency-Key가 필수입니다. 동일한 Idempotency-Key로 재시도하면 최초 처리 결과를 그대로 반환합니다. 같은 토큰을 다른 Idempotency-Key로 다시 사용하면 400(오류 코드 1228)으로 거부됩니다.

검증한 매장과 실제 처리 매장이 같아야 합니다. 검증 시 processStoreIdx를 지정했다면 이 요청에서도 같은 매장을 사용해야 합니다. 매장을 지정하지 않고 검증한 토큰에는 이후 매장을 새로 지정할 수 없습니다.

만료, 변조, 이미 사용된 토큰, 바인딩 불일치는 모두 1228로 응답합니다. 원인을 구분해 노출하면 제3자가 다른 토큰을 이용해 내부 상태를 추측할 수 있기 때문입니다.

현장 인증을 사용하지 않는 리소스(onsiteYn = N)에는 토큰이 필요하지 않습니다. v1은 기존과 동일하게 onsitePwd 평문을 받습니다.

이 API에서는 실제로 혜택 사용 전환(N → Y)이 발생할 때만 토큰을 사용합니다. 메모, 기간, 활성 상태만 변경하는 일반 수정 요청에 토큰을 보내면 400(오류 코드 1227)으로 거부됩니다. 요청에 useYn = Y가 포함되어 있어도 실제 N → Y 전환이 발생하지 않으면 (예: 이미 혜택 사용이 완료된 스탬프) 토큰은 소비되지 않습니다.

이 API는 처리 매장 파라미터(processStoreIdx)를 받지 않습니다. 혜택 사용이 처리되면 처리 위치는 요청값이 아니라 검증 시 토큰에 바인딩된 매장에서 복원해 이벤트와 Webhook에 기록합니다. 일반 수정에는 이 처리 위치를 적용하지 않습니다.

같은 토큰을 혜택 사용 API(Redeem)에도 사용할 수 있지만, 두 API 중 한 곳에서 한 번만 사용할 수 있습니다. 한쪽에서 이미 소비된 토큰을 다른 API에서 다시 사용하면 거부됩니다.

PIN 초기화가 필요한 상황

resetPinYn을 Y로 설정하면 고객의 PIN 번호가 초기화됩니다.

고객이 PIN을 분실했거나 기기를 변경한 경우, 또는 보안상 PIN 재설정이 필요한 경우에 활용합니다.

초기화 후 고객이 스탬프 페이지에 접속하면 새 PIN 번호를 다시 설정하게 됩니다. N으로 설정하거나 파라미터를 제외하면 기존 PIN이 유지됩니다.

활용 예시

적립 오류 보정: 잘못 적립된 스탬프 수를 수동으로 수정
이벤트 조건 변경 대응: 진행 중 이벤트의 적립 기준 변경 시 데이터 반영
기사용자 재인증 처리: PIN 초기화를 통해 오프라인 인증 재설정
비활성 처리: 이벤트 종료 시 스탬프를 비활성 상태로 전환

사용 시 주의사항

stamps 값 변경 시 기존 적립 이력과 충돌하지 않도록 주의해야 합니다
사용 처리(useYn) 후에는 되돌릴 수 없는 구조로 설계하는 것이 안전합니다
운영 로그 및 변경 이력을 함께 관리하는 것이 좋습니다

스탬프 수정 API (v2)