스탬프 생성 API

스탬프 생성 API는 고객에게 새로운 스탬프를 프로그래밍 방식으로 발급하는 기능을 제공합니다.

카드 IDX와 유효기간을 지정하면 해당 스탬프 카드에 스탬프가 발급되며, 사용자 정보와 메모를 함께 기록해 고객별 적립 이력을 체계적으로 관리할 수 있습니다.
카드 IDX는 대시보드의 “스탬프 카드” 페이지에서 확인할 수 있습니다.

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

POST

/api/stamp/v1/create 

{
    "cardIdx": 123,  // You can check the IDX value on the card management page of the dashboard.
    "domain": "https://vvd.bz",
    "strtYmd": "2025-01-01",
    "endYmd": "2025-12-31",
    "activeYn": "Y",
    "memo": "New Member Registration, IP: 211.111.222.33",
    "userId": "att78z",
    "userNm": "Brown Smith",
    "userPhnno": "+1 123-4567-8900",
    "userEml": "test@gmail.com",
    "userEtc1": "Gold rating",
    "userEtc2": ""
}

Request Parameters

cardIdx integer required
카드 IDX. 카드 IDX는 대시보드의 “스템프 카드” 페이지에서 확인할 수 있습니다.
domain string
Default:https://vvd.bz
스템프 도메인. 값이 비어있으면 기본 도메인으로 저장됩니다.
프리미엄 요금제 이상에서는, 링크 도메인 관리에서 등록한 커스텀 도메인을 지정할 수 있습니다.
strtYmd date required
스템프 유효 시작일. 예: 2025-01-01
endYmd date required
스템프 유효 만료일. 예: 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": 1347
}

Response Parameters

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

언제 이 API를 사용하나요?

스탬프 기반 이벤트나 적립 시스템을 구축할 때 사용합니다.

  • 방문 횟수 기반 리워드 이벤트
  • 오프라인 매장 스탬프 적립
  • 회원 활동 인증 시스템
  • 특정 행동(구매, 참여 등) 기록

즉, 사용자의 행동을 기록하고 보상으로 연결하는 구조에 적합합니다.

스탬프 카드와 스탬프의 관계

스탬프 카드는 적립 규칙과 디자인을 정의하는 틀이며, 스탬프는 고객에게 실제로 발급되는 단위입니다.

생성 API 호출 시 cardIdx로 어느 카드에 스탬프를 발급할지 지정합니다.

카드 IDX는 대시보드에서 확인할 수 있으며, 카드별로 적립 조건과 리워드가 다르게 설정되어 있으므로 올바른 카드를 지정하는 것이 중요합니다.

스탬프 생성 방식과 구성 요소

스탬프는 단순 데이터가 아니라 사용자 활동을 기록하는 단위입니다.

주요 구성 요소:

  • 카드 식별자 (cardIdx) : 스탬프가 속한 카드 ID
  • 적립 기간 (strtYmd, endYmd) : 스탬프 유효 기간
  • 활성 여부 (activeYn) : 스탬프 사용 가능 상태
  • 사용자 정보 (userId, userNm, userEmail 등) : 적립 대상
  • 추가 정보 (memo, userEtc1, userEtc2) : 커스텀 데이터

이를 통해 개인화된 사용자 행동 데이터 관리가 가능합니다.

사용자 정보 연동

userId는 스탬프 발급 대상자를 관리하는데 사용됩니다.

일반적으로 자사 회원 시스템의 회원 ID를 입력하며, 설정하지 않으면 시스템에 의해 자동으로 사용자 ID가 생성됩니다.

userNm, userPhnno, userEml 등의 필드로 고객 연락처와 이메일을 함께 기록해 두면 대시보드에서 고객별 스탬프 현황을 조회하고 관리하는데 활용할 수 있습니다.

활용 예시

  • 회원가입 기념 스탬프: 신규 회원 가입 완료 시 API를 호출해 웰컴 스탬프를 자동 발급
  • 구매 적립 자동화: 결제 완료 이벤트 발생 시 스탬프 생성 API를 호출해 구매 횟수에 따른 스탬프를 자동으로 적립
  • 기간 한정 이벤트: 시즌 프로모션 기간에만 유효한 스탬프를 strtYmd·endYmd로 기간을 제한해 발급
  • 이벤트 참여 기록: 특정 이벤트 참여 시 스탬프 생성 → 참여 이력 관리
  • 리워드 캠페인 운영: 스탬프 누적 수에 따라 쿠폰 또는 혜택 지급

쿠폰 API와 차이점

쿠폰 API와 스탬프 API는 모두 마케팅에 활용되지만, 목적과 사용 방식이 명확하게 다릅니다.

쿠폰 API는 할인 제공을 통해 즉시 구매를 유도하는 전환 중심 도구입니다.
반면 스탬프 API는 사용자 행동을 기록하고 반복 참여를 유도하는 리텐션 중심 도구입니다.

1. 목적의 차이

  • 쿠폰 API → 할인 제공 → 구매 유도 (Conversion)
  • 스탬프 API → 행동 기록 → 재방문 유도 (Retention)

쿠폰은 단기 매출을 올리는 데 효과적이며, 스탬프는 장기적인 사용자 유지와 반복 참여를 만드는 데 적합합니다.

2. 사용 시점의 차이

  • 쿠폰 → 결제 직전 또는 결제 시 사용
  • 스탬프 → 방문, 참여, 행동 발생 시 적립

쿠폰은 “지금 결제하게 만드는 장치”이고, 스탬프는 “다음 행동을 유도하는 장치”입니다.

3. 데이터 구조의 차이

쿠폰은 단일 이벤트 중심입니다.

  • 1회 사용 또는 제한된 횟수
  • 할인 금액 또는 비율 중심
  • 사용 시 즉시 소멸 또는 상태 변경

스탬프는 누적 데이터 중심입니다.

  • 반복 적립 가능
  • 사용자별 누적 기록 관리
  • 일정 조건 달성 시 보상 연결

즉, 쿠폰은 단발성 트리거, 스탬프는 누적형 상태 데이터입니다.

4. 마케팅 전략의 차이

쿠폰 기반 전략:

  • 신규 고객 유입
  • 구매 전환율 상승
  • 특정 상품 판매 촉진

스탬프 기반 전략:

  • 재방문 유도
  • 고객 충성도 강화
  • 장기 캠페인 운영

5. 함께 사용하는 구조

실제 서비스에서는 두 API를 함께 사용하는 경우가 많습니다.

예:

  • 스탬프 적립 (방문 10회)
  • 조건 달성 시 쿠폰 자동 발급
  • 쿠폰 사용으로 구매 유도

이 구조를 통해, 참여 → 유지 → 전환까지 하나의 흐름으로 연결할 수 있습니다.

사용 시 주의사항

  • cardIdx는 반드시 유효한 카드 ID를 사용해야 합니다.
  • 동일 사용자에 대한 중복 적립 정책을 사전에 정의해야 합니다.
  • 스탬프 기간 설정이 잘못되면 이벤트 운영에 영향을 줄 수 있습니다.