本文へスキップ
walaoraWalaora

Walaora API リファレンス

POS、EC ストア、社内システムと連携できます。HTTPS 上の JSON で、連携ごとに API キーを 1 つ使用します。

顧客のデータは本人が把握している場合にのみ送信し、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

顧客を検索します（1 ページ 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

利用可能な特典を 1 つ交換します。または {"rewardId"} を送信して、スタンプ / ポイントで価格設定されたカタログ特典を交換します。

POST/cards/{serial}/sell

回数券：回数券を販売し、回数をカードに追加します（支払いはお店のレジで）。Webhook：package.sold

POST/cards/{serial}/use

回数券：1回分を使います（残りがない・期限切れの場合は拒否）。スタッフカード：1日の上限内で特典を記録します。Webhook：package.used、perk.used

GET/coupons/{code}

クーポンを使わずに確認します：オファー内容、使用できるかどうか、使用できない場合はその理由（使用済み・期限切れ・一時停止中）。

POST/coupons/{code}/redeem

クーポンを1回使用します。任意で { 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 時間以内に同じキーで再試行すると、スタンプを二重に付与せず、元のレスポンスを返します。

エラー

エラー時は JSON 本文 { error: { code, message } } と HTTP ステータスを返します：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 時間後に再試行します。

イベント

署名の検証（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 ?? ""));
}