Walaora API 레퍼런스

POS, 온라인 스토어 또는 내부 시스템을 연결하세요. HTTPS 기반 JSON, 연동마다 API 키 하나를 사용합니다.

고객이 알고 있는 경우에만 고객 데이터를 보내고, 고객이 명시적으로 동의한 경우에만 marketingConsent를 true로 설정하세요.

인증

대시보드 → API 및 Webhooks에서 키를 생성하세요(비즈니스 또는 엔터프라이즈 요금제). 모든 요청에 키를 함께 보내세요. 키는 한 번만 표시되며, 노출된 경우 폐기하세요. 제한: 키당 분당 120회 요청.

Authorization: Bearer wl_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

엔드포인트

Base URL: https://walaora.com/api/v1

GET	`/programs` 멤버십 프로그램 목록을 조회합니다.
GET	`/customers?phone=0551234567&tag=vip` 고객을 검색합니다(페이지당 50명, ?page=2…). ?tag=vip는 해당 태그가 있는 고객을 나열하며, 각 고객에 태그가 포함됩니다.
POST	`/customers` 고객을 프로그램에 가입시킵니다. 본문: { programId, name, phone, email?, marketingConsent?, locale? }. 새로 생성되면 201, 이미 가입되어 있으면 200을 반환합니다.
GET	`/cards/{serial}` 고객 카드 / QR에 있는 코드로 카드를 조회합니다.
POST	`/cards/{serial}/earn` 스탬프 프로그램: { stamps?: 1–10 }. 포인트 프로그램: 워크스페이스 통화 기준 { amount }. 선택 사항 { branchId }. 멀티 스탬프 카드: 카드 세트 중 하나의 setId를 보내세요.
POST	`/cards/{serial}/redeem` 사용 가능한 리워드 하나를 사용하거나, {"rewardId"}를 보내 스탬프/포인트로 가격이 매겨진 카탈로그 리워드를 사용합니다.
POST	`/cards/{serial}/sell` 선불 패키지: 패키지를 판매하고 횟수를 카드에 추가해요(결제는 매장 카운터에서). Webhook: package.sold.
POST	`/cards/{serial}/use` 선불 패키지: 1회를 차감해요(남은 횟수가 없거나 만료되면 거부). 직원 카드: 하루 한도 안에서 혜택을 기록해요. Webhooks: package.used, perk.used.
GET	`/coupons/{code}` 쿠폰을 사용하지 않고 확인해요: 오퍼, 사용 가능 여부, 사용할 수 없다면 그 이유(사용됨, 만료, 일시 중지).
POST	`/coupons/{code}/redeem` 쿠폰을 한 번 사용해요. 선택 사항으로 { amount }(판매 금액, 워크스페이스 통화)와 { branchId }. 이미 사용되었거나 오퍼가 종료되면 409. Webhook: coupon.redeemed.
GET	`/coupon-offers` 쿠폰 오퍼 목록: 값, 종료일, 지금 코드를 만들 수 있는지(usable).
POST	`/coupon-offers/{id}/coupons` 오퍼의 코드를 만듭니다. { customerId }는 해당 고객에게 코드 1개를 줍니다(고객의 카드 페이지에 표시). 또는 { count: 1–500 }으로 인쇄하거나 공유할 고객 미지정 코드를 만듭니다. 코드와 함께 201, 오퍼가 일시 중지되었거나 종료되면 409.

curl -X POST https://walaora.com/api/v1/cards/ABCDE23456/earn \
  -H "Authorization: Bearer wl_live_…" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: receipt-10045" \
  -d '{"stamps": 1}'

재시도 및 멱등성

POST 요청에는 Idempotency-Key 헤더(영수증 번호 등 고유한 문자열)를 보내세요. 24시간 이내에 같은 키로 재시도하면 스탬프가 두 번 적립되지 않고 원래 응답이 반환됩니다.

오류

오류는 HTTP 상태 코드와 함께 JSON 본문 { error: { code, message } }을 반환합니다: 401 잘못된 키 · 403 plan_required · 404 찾을 수 없음 · 409 cooldown / no_reward / program_inactive · 422 유효성 검사 실패 · 429 요청 한도 초과.

Webhooks

대시보드에서 HTTPS 엔드포인트를 추가하고 이벤트를 선택하세요. 각 전송은 JSON { id, type, createdAt, data }을 담은 POST 요청이며 Walaora-Event, Walaora-Delivery, Walaora-Signature 헤더가 포함됩니다. 10초 이내에 2xx로 응답하세요. 실패한 전송은 1분, 5분, 30분, 2시간, 12시간 후에 재시도됩니다.

이벤트

customer.enrolled
card.earned
reward.unlocked
reward.redeemed
card.adjusted
customer.deleted
feedback.received
package.sold
package.used
perk.used
coupon.redeemed

서명 검증(Node.js)

import crypto from "node:crypto";

// rawBody: the exact request body string; header: req.headers["walaora-signature"]
export function verifyWalaora(rawBody, header, secret) {
  const parts = Object.fromEntries(header.split(",").map((p) => p.split("=")));
  const t = Number(parts.t);
  if (!t || Math.abs(Date.now() / 1000 - t) > 300) return false; // replay window
  const expected = crypto.createHmac("sha256", secret).update(`${t}.${rawBody}`).digest("hex");
  return crypto.timingSafeEqual(Buffer.from(expected), Buffer.from(parts.v1 ?? ""));
}