Voucher API

Authentication

Runtime endpoints use an sop_ token. Do not send an account JWT or Bot Token to these endpoints.

API=https://api.example.com
Authorization: Bearer sop_xxxxxxxxxxxxxxxxx
Content-Type: application/json

Production services can encrypt the logical path, sop_ token, idempotency key, request body, and response body. Read the request encryption guide.

Scopes

Response envelope

The HTTP status communicates transport and business outcome. The body includes success, code, message, data, and meta.requestId for support. Error responses set success to false and include error details.

{
  "success": true,
  "code": 200,
  "message": "操作成功",
  "data": {},
  "meta": {
    "requestId": "REQUEST_ID",
    "timestamp": "2026-09-08T10:30:00.000Z",
    "duration": "12ms"
  }
}

Runtime endpoints

Template endpoints

A template ID is unique within an application. Only draft or rejected templates can be submitted, and only active templates can issue vouchers.

Template statuses

Issuance parameters

A successful response returns issuanceId and voucher. Application APIs do not expose the code or QR secret; the holder-facing client presents credentials securely.

Voucher credential

{
  "credential": {
    "type": "qr_token",
    "value": "SCANNED_VALUE"
  }
}

type accepts qr_token or redeem_code. Six-character codes ignore case, spaces, and hyphens. Verification marks an expired available voucher as expired, but does not redeem it.

Redemption parameters

Reversal

A reversal must reference a successful, unreversed redemption and use a new Idempotency-Key. The voucher returns to available if still valid, or expired otherwise.

{
  "reason": "订单退款",
  "operator_id": "manager_02"
}

Idempotency and retries

• Use separate Idempotency-Key values for issuance, redemption, and reversal.
• Retry the same business action with the original key and identical request body.
• A client timeout does not mean server failure. Retry the original request or query the redemption record instead of changing the key.
• A 409 can mean exhausted quota, per-user limit, already redeemed, not redeemable, or idempotency conflict. Classify it using message/error.

Console management endpoints

These endpoints use the signed-in account JWT and only access applications owned by that account.

GET    /api/v1/open-platform/applications
POST   /api/v1/open-platform/applications
GET    /api/v1/open-platform/applications/:id
PATCH  /api/v1/open-platform/applications/:id
GET    /api/v1/open-platform/applications/:id/tokens
POST   /api/v1/open-platform/applications/:id/tokens
DELETE /api/v1/open-platform/applications/:id/tokens/:tokenId
PUT    /api/v1/open-platform/applications/:id/bots/:botId
DELETE /api/v1/open-platform/applications/:id/bots/:botId

Allocate sender stock

Application owners use their account JWT to find senders and allocate stock. This does not create a usable voucher or redemption credential. A user voucher is created only when the recipient claims it. The existing runtime /issue endpoint still issues directly to the user who will use it.

GET  /api/v1/open-platform/applications/:id/vouchers/recipients?keyword=sender
GET  /api/v1/open-platform/applications/:id/vouchers/allocations?templateId=TEMPLATE_ID&page=1&limit=20
POST /api/v1/open-platform/applications/:id/vouchers/allocations
{
  "templateId": "TEMPLATE_ID",
  "recipientUserId": "SENDER_USER_ID",
  "quantity": 5,
  "idempotencyKey": "UNIQUE_ALLOCATION_REQUEST_ID"
}

Search accepts a username of at least two characters or a full user ID, and returns up to 20 users. Quantity must be an integer from 1 to 10,000 within available stock. Network retries must reuse the original idempotency key and body. Allocation records include id, quantity, remaining, sendingCount, claimedCount, and status.

Common status codes

• 400 A field is missing, malformed, or outside its allowed range.
• 401 The token is invalid, expired, or revoked.
• 403 The application is disabled, the feature is unavailable, or the token lacks scope.
• 404 The template, voucher, or redemption does not belong to the application.
• 409 State conflict, quota exhausted, or an idempotency key reused with a different request.
• 429 The request exceeded the endpoint rate limit.
• 5xx A temporary platform failure. Keep the requestId and retry only with the original idempotency key and body.

Common business errors