ホーム / Developers / POS連携 API
API REFERENCE v1

POS連携 API

お使いのPOSレジとPush-taroを連携させるためのAPI仕様です。
クーポンの有効性確認、消込確定、クーポン一覧の取得が可能です。

1. 認証

すべてのAPIリクエストには、HTTPヘッダにAuthorizationを含める必要があります。
APIキーは、Push-taroのPRO管理画面から発行できます。

Authorization: Bearer pt_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

APIキーの再表示はできません発行時に一度だけ表示されます。安全な場所に保管してください。漏洩した場合は、PRO管理画面から即座に失効させてください。

2. 共通ヘッダ

ヘッダ名必須説明
Authorization必須Bearer pt_live_... 形式のAPIキー
X-POS-Terminal-Id任意レジ識別子(例: register-01)。監査ログに記録されます。
Idempotency-Keyredeemのみ必須UUID形式の冪等キー。同じクーポン・同じキーの再送は、保存済みの成功結果を返します。別のクーポンに同じキーを使うと409になります。

3. クーポン一覧の取得

GET/api/pos/v1/coupons

店舗で現在有効なクーポンの一覧を取得します。POSのマスタ同期などに利用できます。 これは店舗の設定一覧で、顧客ごとの使用可否は検証APIで確認してください。期限切れは除外され、予約クーポンにはcouponIdが付きます。 連続ログイン達成クーポンはcouponTypeにstreakを指定して検証・消し込みできます。

レスポンス

{
  "coupons": [
    { "couponType": "first", "title": "初回限定 10%OFF" },
    { "couponType": "normal", "title": "会員様 5%OFF" },
    { "couponType": "loyalty", "title": "3回達成 20%OFF" },
    { "couponType": "streak", "title": "連続ログイン達成クーポン" },
    { "couponType": "scheduled", "couponId": "scheduled-123", "title": "週末特典" }
  ]
}

4. クーポンの検証(消込なし)

POST/api/pos/v1/verify

QRコードの内容を送信し、そのクーポンが有効かどうかを確認します。
消込は行わないため、会計前の確認に利用できます。 確認後に別のレジで使用される場合もあるため、会計時には消込APIの成功を必ず確認してください。

リクエストボディ

{
  "qrPayload": "{\"shopId\":\"xxx\",\"couponType\":\"first\",\"token\":\"yyy\"}"
}

レスポンス(成功)

{
  "valid": true,
  "couponTitle": "初回限定 10%OFF",
  "couponType": "first"
}

レスポンス(失敗)

{
  "valid": false,
  "error": "⚠️ この初回限定クーポンはすでに使用済みです!"
}

5. クーポンの消込確定

POST/api/pos/v1/redeem

QRコードの内容を送信し、クーポンの消込を確定します。
このエンドポイントには、Idempotency-Key ヘッダが必須です。 1回の消込操作ごとにUUIDを作り、通信切断や500エラー時の再送には同じUUIDとQRデータを使ってください。 消込・利用履歴・成功結果は一括保存されます。同じキーでの再送時はidempotent: trueが返ります。

リクエストヘッダ

Idempotency-Key: 550e8400-e29b-41d4-a716-446655440000

リクエストボディ

{
  "qrPayload": "{\"shopId\":\"xxx\",\"couponType\":\"first\",\"token\":\"yyy\"}"
}

レスポンス(成功)

{
  "success": true,
  "couponTitle": "初回限定 10%OFF",
  "redeemedAt": "2026-10-25T12:34:56.000Z"
}

6. エラーコード一覧

HTTPステータス説明
400形式不正、必須パラメータ不足、クーポン無効、未達成・未配布など
401APIキーが無効、または認証ヘッダがない
403店舗不一致、顧客の店舗登録なし、または許可されていないレジ
404店舗・顧客・予約クーポンが見つからない
409使用済み、当日併用不可、または別のQRデータで同じ冪等キーを使用(同じQRの成功再送は200)
410クーポンの有効期限切れ
500サーバー内部エラー

7. サンプルコード(Node.js)

axiosを使用した実装例です。

import axios from 'axios';
import { randomUUID } from 'crypto';

const API_KEY = 'pt_live_xxxxxxxxxxxxxxxx';
const SHOP_ID = 'shop_xxxxx';
const qrPayload = JSON.stringify({
  shopId: SHOP_ID,
  couponType: 'first',
  token: 'fcm_token_xxxxx'
});

// 1. 検証
const verify = await axios.post(
  'https://push-taro.com/api/pos/v1/verify',
  { qrPayload },
  {
    headers: { Authorization: `Bearer ${API_KEY}` },
    validateStatus: (status) => status < 500
  }
);

if (!verify.data.valid) {
  throw new Error(verify.data.error || 'クーポンが無効です');
}

// 2. 消込
// 通信失敗時は、このキーを変えずに同じリクエストを再送する。
const idempotencyKey = randomUUID();
const redeem = await axios.post(
  'https://push-taro.com/api/pos/v1/redeem',
  { qrPayload },
  {
    headers: {
      Authorization: `Bearer ${API_KEY}`,
      'Idempotency-Key': idempotencyKey,
      'X-POS-Terminal-Id': 'register-01'
    }
  }
);

console.log('消込完了:', redeem.data.couponTitle);

運用前の確認

このAPIはクーポンの確認・消込を行います。割引率・値引額の計算や会計への適用はPOS側で設定してください。 会計を確定する際に消込を行い、成功するまで特典適用を確定しないでください。 確定後の消込取消APIはありません。通信失敗時は新しいキーでやり直さず、保存した冪等キーで結果を確認してください。

本番運用前にテスト用顧客で、検証だけでは使用済みにならないこと、消込後の顧客画面・使用履歴への反映、 同じキーでの再送、別レジからの重複利用、キー失効後の401を確認してください。 顧客画面は表示中なら通常10秒ごと、または画面復帰時に使用状況を更新します。

← POS連携ガイドに戻る