openydt-coupon

openydt-coupon — Electronic coupons and merchant domain (coupon)

CRITICAL: Before starting, MUST first use the Read tool to read ../openydt-shared/SKILL.md(authentication / profile / signature / status codes / rate limiting / security rules). Do not execute any command without reading the shared foundation.

When to use this skill

This skill coversElectronic coupons and merchant domain (coupon): creation and maintenance of merchants (trader), creation of electronic coupon templates, selling coupons to merchants, issuing electronic coupons to vehicles, querying coupons and merchant information, and coupon recycling. Vehicles can use electronic coupons at parking lots to deduct part or all of the parking fee.

Intent routing:

• "Create a new merchant / add a merchant / enter merchant account" → openydt coupon create-trader(write, requires --yes）。
• "Edit merchant information / freeze merchant / unfreeze / delete merchant" → openydt coupon edit-trader / frozen-trader / delete-trader(write, requires --yes）。
• "Query merchant list / view a merchant's information / verify merchant account password" → openydt coupon get-trader-list / get-trader-info-by-trader-code / validate-trader-account-and-password。
• "Create a coupon template / create discount coupon / create fixed coupon" → openydt coupon create-coupon-template / create-coupon / create-fixed-coupon(write, requires --yes）。
• "Sell coupons to merchant / sell electronic coupons" → openydt coupon sell-coupon(write, requires --yes）。
• "Issue coupon to this vehicle / issue discount coupon / issue coupon by coupon code / scan code to issue coupon" → openydt coupon send-coupon / send-coupon-by-coupon-code / sync-scan-coupon-qr-code(write, requires --yes）。
• "Query which coupons this vehicle has / issued coupons / available coupons / coupon information" → openydt coupon query-car-code-valid-coupon / query-usable-coupon / query-coupon。
• "Recycle this coupon / return coupon / lock coupon / print coupon" → openydt coupon cancel-coupon / lock-coupon / print-coupon(write, requires --yes）。

The actual fee query / payment after coupon deduction is in the trade domain (openydt trade --help); in-lot vehicle confirmation is in the parking domain (openydt parking --help）。

Available commands

Chinese name	Command	Read/Write	Key parameters
Get merchant information	openydt coupon get-trader-info-by-trader-code	Read	--trader-code required
Verify merchant user account password	openydt coupon validate-trader-account-and-password	Read	--trader-user-account required,--trader-password required
Create merchant	openydt coupon create-trader	Write	--trader-name required,--contact required,--phone required,--park-code required,--login-account required,--password required,--trader-type(0 Food/1 Hotel/2 Leisure and entertainment/3 Life services/4 Shopping/5 Other)
Edit merchant	openydt coupon edit-trader	Write	--trader-code/--trader-id(choose one of two),--trader-name required,--contact required,--phone required,--park-code required,--login-account required,--password required,--trader-type
Freeze or unfreeze merchant	openydt coupon frozen-trader	Write	--trader-code/--trader-id(choose one of two),--park-code required,--status required (0 unfreeze/1 freeze)
Delete merchant (irrecoverable)	openydt coupon delete-trader	Write	--park-code required,--trader-code/--trader-id(choose one of two)
Query merchant list	openydt coupon get-trader-list	Read	--park-code Required,--create-time-from Required,--create-time-to Required,--page-num Required,--page-size Required (max 1000)
Create electronic coupon template	openydt coupon create-coupon-template	Write	--name Required,--sell-from/--sell-to/--grant-from/--grant-to Required,--valid-minute Required,--balance-type Required,--coupon-type Required,--face-value Required,--original-price/--real-price/--use-rule-from/--use-rule-to Required
Create electronic coupons and sell them to merchants	openydt coupon create-coupon	Write	--trader-code Required,--total-count Required (≤10,000),--body(parkCodeList, couponTemplate sub-object)
Create fixed electronic coupons (one code, multiple coupons)	openydt coupon create-fixed-coupon	Write	--trader-code Required,--group-name Required,--valid-from/--valid-to Required,--max-num Required,--sell-bill-id Required,--uniq-no Required
Sell electronic coupons to merchants	openydt coupon sell-coupon	Write	--trader-coupon-template-code Required,--trader-code Required,--sell-num Required,--sell-money Required,--sell-time Required,--sell-remark、--transation-num
Issue electronic coupons to a specified vehicle	openydt coupon send-coupon	Write	--trader-code Required,--sell-bill-id Required,--car-code Required,--car-code-color、--parking-code
Issue merchant coupons based on coupon code	openydt coupon send-coupon-by-coupon-code	Write	--coupon-code Required,--car-no/--card-no(cannot both be empty),--park-code、--grant-user-id、--car-code-color、--parking-code、--is-fixed-qr-code、--origin
Sync electronic coupon QR code scan	openydt coupon sync-scan-coupon-qr-code	Write	--coupon-code Required,--grant-user-id Required
Check whether electronic coupon can be issued	openydt coupon check-coupon-whether-send-available	Read	--coupon-code Required,--fixed-status(0 non-fixed/1 fixed)
Check validity of electronic coupon QR code	openydt coupon check-coupon-qr-code-valid-status	Read	--coupon-code Required,--origin Required
Print electronic coupon (mark as issued)	openydt coupon print-coupon	Write	--trader-code Required,--coupon-sn Required
Query electronic coupon print records	openydt coupon query-coupon-print-record	Read	--coupon-code Required
Lock electronic coupon	openydt coupon lock-coupon	Write	--url Required
Recycle electronic coupon	openydt coupon cancel-coupon	Write	--trader-code Required,--coupon-sn Required
Query issued electronic coupons (by license plate/card number)	openydt coupon query-car-code-valid-coupon	Read	--park-code Required,--car-code、--card-code、--coupon-sn
Query electronic coupon information	openydt coupon query-coupon	Read	--trader-code Required,--query-type Required (0 specified/1 all/2 issuable),--page Required,--page-size Required,--coupon-code-list
Query available electronic coupons	openydt coupon query-usable-coupon	Read	--trader-code Required,--sell-bill-id Required
Query applicable parking lots based on coupon code	openydt coupon query-coupon-available-park-by-coupon-code	Read	--coupon-code Required,--fixed-status Required (0 non-fixed/1 fixed)
Query coupon template based on coupon template code	openydt coupon query-coupon-template-by-coupon-code	Read	--code Required (merchant coupon template code)
Query coupon template based on coupon code	openydt coupon query-coupon-template-by-coupon-sn	Read	--coupon-sn Required
Query merchant information by coupon code	openydt coupon query-trader-info-by-coupon-code	Read	--coupon-sn Required
Query e-coupon sale records	openydt coupon query-trader-coupon-sell-record	Read	--sell-begin-time Required,--sell-end-time Required,--page-num、--page-size、--body(parkCodeList)
Query merchant coupon issuance records	openydt coupon get-trader-coupon-grant-record-list	Read	--trader-id Required,--begin-time Required,--end-time Required,--page-num Required,--page-size Required,--body(parkCodeList)、--need-coupon-park、--need-coupon-status
Query coupon list (by license plate)	openydt coupon get-trader-coupon-list	Read	--page-size、--page-num、--body(choose one of parkCodes, carNos/carPlateList)

AllWriteCommand (create-trader / edit-trader / frozen-trader / delete-trader / create-coupon-template / create-coupon / create-fixed-coupon / sell-coupon / send-coupon / send-coupon-by-coupon-code / sync-scan-coupon-qr-code / print-coupon / lock-coupon / cancel-coupon) when executedmust add --yes confirmation, otherwise it will be intercepted.

Callable interfaces not listed in this table but belonging to the coupon domain (such as couponFlow/thirdCoupon*/syncAutoCoupon、cityOperationCoupon the entire family,getParkingPayCouponList/getUserCouponRecord), use openydt api <cmd> --body '{...}' to call (write operations --yes, first --dry-run); see [[openydt-api-explorer]] for details. For an example of creating a city operation coupon template, see that skill.

Business process

E-coupon closed loop (create merchant + create template → sell → issue coupon → query → recycle)

Execute step by step,be sure to use the fields in the previous command's response as the input parameters of subsequent commands(merchant code traderCode, coupon template code traderCouponTemplateCode, sales bill sellBillId, coupon unique number couponSn), do not construct them out of thin air:

1. Create merchant + create coupon template(write, both require --yes）：

   openydt coupon create-trader --yes \
     --trader-name <商家名> --contact <联系人> --phone <手机号> \
     --park-code <车场编号> --login-account <账号> --password <密码>
   
   openydt coupon create-coupon-template --yes \
     --name <券名> --sell-from ... --sell-to ... --grant-from ... --grant-to ... \
     --valid-minute 60 --balance-type 0 --coupon-type 1 \
     --face-value 500 --original-price 600 --real-price 500 \
     --use-rule-from 0 --use-rule-to 1000
   

   • From create-trader response getmerchant code traderCode(can also use get-trader-list to look up) → as the --trader-code；
   • From create-coupon-template response getcoupon template code(merchant coupon template code) → as step 2 sell-coupon of --trader-coupon-template-code(can also use query-coupon-template-by-coupon-code --code <模板代码> to verify).

2. Sell to merchant(write, requires --yes) — use the merchant code + template code obtained in step 1:

   openydt coupon sell-coupon --yes \
     --trader-coupon-template-code <来自 create-coupon-template> \
     --trader-code <来自 create-trader> \
     --sell-num 100 --sell-money 0.01 --sell-time "2026-06-01 09:00:00"
   

   • From sell-coupon response getsales bill sellBillId → as step 3 send-coupon of --sell-bill-id(can also use query-usable-coupon --trader-code <traderCode> --sell-bill-id <id> to verify the remaining issuable balance for this batch).

3. Issue to vehicle(write, requires --yes) — use the sellBillId obtained in step 2 + merchant code:

   openydt coupon send-coupon --yes \
     --trader-code <来自 create-trader> \
     --sell-bill-id <来自 sell-coupon> \
     --car-code <车牌> --car-code-color 1
   

   Can also issue coupon by coupon code:send-coupon-by-coupon-code --yes --coupon-code <券编码> --car-no <车牌>（--car-no and --card-no cannot both be empty). Before issuing a coupon, you can first check-coupon-whether-send-available --coupon-code <券编码> to confirm whether it can be issued.

4. Query coupon(read) — confirm the coupon has landed on the vehicle / merchant:

   openydt coupon query-car-code-valid-coupon --park-code <车场> --car-code <车牌>
   openydt coupon query-coupon --trader-code <traderCode> --query-type 1 --page 1 --page-size 10
   

   • From the query response getcoupon unique number couponSn → as step 5 cancel-coupon of --coupon-sn(to look up merchant by coupon code use query-trader-info-by-coupon-code --coupon-sn <couponSn>）。

5. Recycle(write, requires --yes) — use the couponSn obtained in step 4 + merchant code:

   openydt coupon cancel-coupon --yes --trader-code <traderCode> --coupon-sn <来自 query>
   

💰 Amount dimension：faceValue The dimension is determined by couponType : 0=free voucher, 1/2/3=amount voucher (faceValue→yuan), 4=time voucher (faceValue→minutes), 5=different pricing voucher;balanceType is the settlement type (0 sale/1 grant/2 use),does not determine voucher type。sellMoney/originalPrice/realPrice unit is yuan. 🔑 Idempotency：sell-coupon of the transationNum、create-fixed-coupon of the uniqNo is the deduplication key—retries reuse the same value and never generate a new one, avoiding duplicate voucher sales/voucher group creation. See references/write-idempotency.md in [[openydt-shared]]. Querying 0 vouchers ≠ the vehicle has no vouchers (confirm parkCode/time window are complete), see references/result-reading-sop.md in [[openydt-shared]].

Error self-healing quick reference (voucher domain)

Symptom	Meaning	Recovery action
Voucher issuance failed/status=2	merchant is frozen / voucher exceeds validity period (grantTo) / sellMoney not satisfied	First get-trader-info-by-trader-code check merchant status,check-coupon-whether-send-available confirm it can be issued
Suspected duplicate after voucher sale resend	transationNum was changed to a new value	Reuse the first transationNum;query-trader-coupon-sell-record verify

For general codes see [[openydt-shared]].

Example

The example parkCode/time are documented test values (test only); copying the catalog's historical sampleBody will hit an invalid parking lot/expired validity period. For write operations, it is recommended to first replace --yes with --dry-run preview, especially delete-trader / cancel-coupon and other irreversible operations, then after confirmation --yes。

Create merchant (write operation; first --dry-run preview, after confirmation --yes）：

openydt coupon create-trader --dry-run \
  --trader-name 测试商家 --trader-type 5 \
  --contact 联系人 --phone 13800000000 \
  --park-code 1ZS7H5PQH9 --login-account trader001 --password 123456
# 确认无误后改 --yes 实发

Sell electronic voucher to merchant (write operation, must add --yes; template code / merchant code are taken from the preceding response):

openydt coupon sell-coupon --yes \
  --trader-coupon-template-code GCSH3FI1YNDN \
  --trader-code NWTSZY49BH67 \
  --sell-num 100 --sell-money 0.01 --sell-remark 测试 \
  --sell-time "2026-06-01 09:00:00"

GCSH3FI1YNDN/NWTSZY49BH67 is a placeholder value, taken from the preceding response;transationNum is the idempotency key, retries reuse the first value.

Query issued electronic vouchers by license plate (read operation):

openydt coupon query-car-code-valid-coupon --park-code PTD2YBBZ --car-code 粤B88888