Google Play에서 모바일 앱을 설치하면 더 편리하게 비볼디를 이용할 수 있습니다.

스탬프 수정 API (v1)

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

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

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

v1(레거시) 문서입니다.

신규 연동에는 최신 버전인 v2 사용을 권장합니다.
v1는 기존 연동을 유지하기 위한 버전으로, 신규 기능이나 개선 사항은 제공되지 않습니다.

PUT

/api/stamp/v1/update 

{
    "stampIdx": 1457,
    "cardIdx": 172,
    "stamps": 7,
    "useYn": "Y",
    "onsitePwd": "12345",
    "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: 아직 혜택을 사용하지 않은 상태입니다.
N에서 Y로 변경할 때는 저장된 도장 수가 카드의 최대 도장 수에 도달해 있어야 하며, 현장 적립용 비밀번호가 설정된 스탬프라면 onsitePwd를 함께 보내야 합니다.
onsitePwd string
현장 적립용 스탬프에서 사용되는 직원 인증 비밀번호입니다.
useYn을 N에서 Y로 변경해 혜택 사용으로 처리할 때, 스탬프가 onsiteYn = Y로 설정돼 있으면 필수입니다. 혜택 사용 API(Redeem)와 동일한 검증 규칙입니다.
도장 수만 변경하거나 비밀번호가 설정되지 않은 스탬프라면 생략할 수 있습니다.
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

숫자 파라미터 검증

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

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

동작 변경 안내. 이전 v1은 이 검증에 걸려도 요청을 그대로 다음 단계까지 진행했습니다. 그래서 다른 파라미터의 오류 메시지로 덮이거나, 응답은 오류인데 스탬프 정보 일부가 실제로 저장되는 경우가 있었습니다. 현재는 최신 버전과 동일하게 처리 전에 400으로 끊습니다.

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

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

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

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

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

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

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

혜택 사용 시 현장 비밀번호

useYn을 N에서 Y로 변경해 혜택을 사용 처리하는 경우, 해당 스탬프에 현장 적립용 비밀번호(onsiteYn = Y)가 설정되어 있으면 onsitePwd를 함께 전송해야 합니다.

이 규칙은 혜택 사용 API(Redeem)와 동일하게 적용됩니다. 수정 API를 통해 비밀번호 확인 없이 혜택이 사용 처리되는 것을 방지하기 위한 정책입니다.

전송할 비밀번호는 검증 API(Validate) 응답의 onsitePwd 값을 확인하세요. 현장 비밀번호가 설정되지 않은 스탬프는 onsitePwd를 생략할 수 있습니다.

도장 수만 변경하거나 이미 사용 완료된 스탬프를 수정하는 경우에는 onsitePwd가 필요하지 않습니다.

PIN 초기화가 필요한 상황

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

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

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

활용 예시

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

사용 시 주의사항

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