公開APIの概要

PASTA公開APIはOpenAPI 3.1準拠のRESTful APIです。すべてのエンドポイントは @hono/zod-openapi で定義されており、スキーマとドキュメントは常に同期されています。

APIリファレンス

インタラクティブなAPIリファレンス（Redoc形式）は以下のURLで公開されています：

• 本番環境：https://api.passes.me/redoc
• OpenAPIスキーマ：https://api.passes.me/openapi.json

Swagger UIも利用できます：https://api.passes.me/docs

主要エンドポイント

パスの発行

POST /v1/passes
X-Api-Key: pasta_xxxx...
Content-Type: application/json

{
  "template_id": "019xxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
  "holder_name": "山田 太郎",
  "fields": {
    "event_name": "夏フェス2026",
    "seat": "A-001"
  }
}

レスポンスには pass_id と各配布形態のURLが含まれます。

Apple Wallet 用パスのダウンロード

GET /v1/passes/{pass_id}/apple

.pkpass バンドルが返されます。保有者のiPhoneでこのURLを開くと直接ウォレットアプリに追加されます。

Google Wallet リンクの取得

GET /v1/passes/{pass_id}/google

「Save to Google Wallet」リンクのURLが返されます。

QRペイロードの取得

GET /v1/passes/{pass_id}/qr

JWS形式の署名済みQRペイロードが返されます。紙チケットの印字や独自配布に使用できます。

パスの検証・償却

POST /v1/validate
X-Api-Key: pasta_xxxx...
Content-Type: application/json

{
  "qr": "eyJhbGciOiJFUzI1NiJ9..."
}

レスポンス status	意味
redeemed	正常に償却（入場承認）
already_redeemed	すでに償却済み（二重入場）
invalid	無効なパス（署名不正・期限切れ・取消済みなど）

パスの取消

POST /v1/passes/{pass_id}/revoke
X-Api-Key: pasta_xxxx...

償却ログの取得

GET /v1/redemptions
X-Api-Key: pasta_xxxx...

エラーレスポンス

すべてのエラーは統一フォーマットで返されます：

{
  "error": {
    "code": "pass_not_found",
    "message": "指定されたパスが見つかりません"
  }
}

HTTPステータスコードと error.code を組み合わせてエラーハンドリングを実装してください。

レート制限

APIリクエストにはレート制限が適用されます。制限値は本番環境とAPIキーのスコープによって異なります。詳細は https://api.passes.me/redoc を参照してください。