스템프 수정 API

스탬프 수정 API는 이미 발급된 스탬프의 정보를 변경하는 기능을 제공합니다.

단순한 정보 수정을 넘어 도장 수 증감, 혜택 사용 처리, PIN 초기화까지 고객의 적립 상태를 직접 제어할 수 있습니다.

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

PUT

/api/stamp/v1/update 

{
    "stampIdx": 1457,
    "cardIdx": 172,
    "stamps": 7,
    "resetPinYn": "Y",
    "userEml": "example@gmail.com"
}

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: 아직 혜택을 사용하지 않은 상태입니다.
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
추가 내부 관리용 필드. 
{
    "code": 0,
    "message": "",
    "result": null
}

Response Parameters

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

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

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

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

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

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

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

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

PIN 초기화가 필요한 상황

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

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

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

활용 예시

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

사용 시 주의사항

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