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-Key | redeemのみ必須 | UUID形式の冪等キー。同じクーポン・同じキーの再送は、保存済みの成功結果を返します。別のクーポンに同じキーを使うと409になります。 |
3. クーポン一覧の取得
店舗で現在有効なクーポンの一覧を取得します。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. クーポンの検証(消込なし)
QRコードの内容を送信し、そのクーポンが有効かどうかを確認します。
消込は行わないため、会計前の確認に利用できます。 確認後に別のレジで使用される場合もあるため、会計時には消込APIの成功を必ず確認してください。
リクエストボディ
{
"qrPayload": "{\"shopId\":\"xxx\",\"couponType\":\"first\",\"token\":\"yyy\"}"
}レスポンス(成功)
{
"valid": true,
"couponTitle": "初回限定 10%OFF",
"couponType": "first"
}レスポンス(失敗)
{
"valid": false,
"error": "⚠️ この初回限定クーポンはすでに使用済みです!"
}5. クーポンの消込確定
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 | 形式不正、必須パラメータ不足、クーポン無効、未達成・未配布など |
401 | APIキーが無効、または認証ヘッダがない |
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秒ごと、または画面復帰時に使用状況を更新します。