openydt-api-explorer

CRITICAL: MUST use the Read tool to read
../openydt-shared/SKILL.md
before starting (authentication / profile / signature / status codes / rate limiting / security rules). The
openydt api
follows exactly the same signature, envelope, exit code and rate limiting logic as first-class commands. Do not execute any commands without reading the shared base.

When to use this skill

The platform has a total of 423 interfaces, only about 143 of which are made into first-class domain commands (

openydt <domain> <command>

, with parameters structured as flags). When the interface you want to call does not have an exclusive subcommand, use the universal fallback of this skill:

bash

openydt api <cmd> --body '{...}'

api

automatically signs and

POST

s to any callable business code cmd with direction=callable, covering all domains not included in first-class commands, such as:

```
cityOperationCoupon
```
City Operation Coupons (create/issue city operation coupon templates)
```
thirdParkForBolian
```
Third-party Parking Lot Payment Access Receipts
```
upward
```
Upward Data Reporting Receipts (e.g.,
```
asynSuccess
```
)
```
community
```
Community Access Control (e.g.,
```
getAuthCommunities
```
)
```
ad
```
Advertising Statistics,
```
preferential
```
/
```
score
```
Point Redemption,
```
invoice
```
Invoices,
```
ydtUser
```
User Authentication, etc.

These domains have

included=false

catalog.json

(no first-class commands generated), but can be directly called with

api

as long as

direction=callable

Priority order: First look for first-class commands (
openydt <domain> --help
or corresponding domain skills), use
api
as fallback if not found. First-class commands split parameters into flags, automatically determine read/write status, and are less error-prone;
api
is "raw JSON direct send", more general but requires you to ensure the body is correct.

Usage: openydt api

bash

# 1) Inline JSON body (most commonly used)
openydt api getParkFee --body '{"parkCode":"1ZS7H5PQH9","carCode":"粤EJW962"}'

# 2) Omit body for parameterless interfaces
openydt api getAuthParkCodes

# 3) Read body from file
openydt api getParkOnSiteCar --body-file ./body.json

# 4) Read body from stdin (- indicates stdin), suitable for pipelines / large bodies
echo '{"parkCode":"PTD2YBBZ"}' | openydt api getParkOnSiteCar --body-file -

```
<cmd>
```
: Business code, exactly the
cmd
field in the catalog (e.g.,
```
getParkFee
```
,
```
createCityOperationCouponTemplate
```
). Note it's the cmd, not the
```
dir
```
path.
```
--body
```
and
```
--body-file
```
are mutually exclusive; if neither is provided, an empty body (
```
{}
```
) is sent, only suitable for parameterless interfaces.
Body is raw JSON: The CLI will first compact the JSON before using it for signature and sending (consistent with first-class commands), spaces inside strings like
```
"2019-04-16 00:11:25"
```
will be preserved.
Parameter naming and nested structure follow the interface definition exactly (see checking parameters from catalog below); incorrect field names usually return
```
status=2 / resultCode=909 Request parameter error
```
or
```
status=7 Request parameter incomplete
```
.

--dry-run Preview

If you are unsure about the body or before using in prod environment, use

--dry-run

to only print the signed request to be sent (URL / sign / ts / compacted body) without actually sending:

bash

openydt api createCityOperationCouponTemplate --dry-run \
  --body '{"parkCodeList":["PRJ9YJ19"],"couponTemplate":{"name":"1-yuan Discount Coupon","faceValue":1}}'

Write operations require --yes (Important: api does not automatically determine read/write)

The
api
command itself does not determine whether a cmd is read or write; it is entirely your responsibility to confirm whether confirmation is needed:

For any cmd that changes the platform state (create/update/delete, issue coupons, pay fees, open gates, report receipts, etc.), you must explicitly add
--yes
, otherwise it will be blocked by security and not executed.
First-class commands automatically identify write operations and require
```
--yes
```
;
```
api
```
will not do this for you, so when using
```
api
```
to call write interfaces, be sure to confirm readwrite status yourself and add
--yes
.
To determine if a cmd is read or write: Check the
```
readwrite
```
field (
```
read
```
/
```
write
```
) in the catalog, see below.

bash

# Write operation (catalog readwrite=write), must add --yes
openydt api createCityOperationCouponTemplate --yes \
  --body '{"parkCodeList":["PRJ9YJ19"],"couponTemplate":{"name":"1-yuan Discount Coupon","totalNum":2,"couponType":1,"faceValue":1,"validFrom":"2019-04-28 00:00:00","validTo":"2020-04-28 00:00:00"}}'

Check available cmds and parameters from catalog

The interface list is in

../../catalog/catalog.json

(absolute path

/Users/zhoujw/develop/tmp/openydt-cli/catalog/catalog.json

). The top-level structure is

{generatedFrom, count, interfaces:[...]}

, each interface object has key fields:

Field	Meaning
`cmd`	Business code, directly used as the cmd in `openydt api <cmd>`
`domain` / `dir`	Belonging domain / document path (for classification only, not an input parameter for api)
`direction`	`callable` =can be actively invoked / `webhook` =platform active push (see next section, cannot be invoked)
`readwrite`	`read` / `write` ——determines whether `--yes` is required when calling
`included`	Whether it has been made into a first-class command; `false` means to use `api` as fallback
`excludeReason`	Reason for not being made into a first-class command ( `out-of-scope-domain` / `deprecated` / `no-endpoint` / `vems-only` , etc.)
`params`	Parameter definition array: `name` / `required` / `type` / `desc` / `group` (non-empty `group` means the parameter is embedded in a sub-object)
`sampleBody`	Official sample request body——the best starting point for constructing `--body` , copy the field names and modify the values
`sampleResponse`	Sample response, helps you predict returned fields

Use

jq

python3

to retrieve (do not print secrets in the terminal, only check the list here without involving credentials):

bash

# View complete definition by cmd (params + sampleBody)
jq '.interfaces[] | select(.cmd=="createCityOperationCouponTemplate")' catalog/catalog.json

# List all callable cmds and their read/write status in a specific unnamed domain
jq -r '.interfaces[] | select(.domain=="cityOperationCoupon" and .direction=="callable") | "\(.cmd)\t\(.readwrite)\t\(.explain)"' catalog/catalog.json

# Full list of interfaces that are not made into first-class commands but callable (included=false and callable)
jq -r '.interfaces[] | select(.included==false and .direction=="callable") | "\(.domain)\t\(.cmd)\t\(.readwrite)"' catalog/catalog.json

# View only the parameter list of a specific cmd (including nested groups)
jq '.interfaces[] | select(.cmd=="createCityOperationCouponTemplate") | .params' catalog/catalog.json

Interfaces with included=false but direction=callable can still be invoked with
api
——common in "unnamed domains" such as city operation coupons, third-party parking lot access (thirdParkForBolian), upward receipts (upward), community access control (community), advertising/points/invoices/ydtUser, etc.

included=false

only means "no exclusive command generated", not "cannot be invoked"; check

direction

to determine if it can be invoked, check

readwrite

to determine if

--yes

is needed.

Construction process: ① Use

jq

to get the

sampleBody

of the target cmd → ② Copy the field names, verify required/type/nesting according to

params

→ ③ Preview the signed request with

--dry-run

→ ④ Add

--yes

for write operations and send officially.

Uncallable webhooks (platform active push)

Interfaces with

direction=webhook

in the catalog (61 in total, such as

reportParkinglotChange

parking space change report) are callbacks actively POSTed by the platform to your receiving end, with the opposite direction of callable:

CLI cannot actively call these cmds——they do not have an entry for "your side requests the platform", and
```
openydt api <webhook-cmd>
```
is not the correct usage (the platform does not provide an endpoint for this direction).
To receive such pushes, you need to build your own HTTP receiver (webhook receiver), register the callback address with the platform, and the platform will POST data in the form of
```
sampleBody
```
to you when an event occurs; your service is responsible for verifying the signature, processing it, and returning as agreed (many upward receipts correspond to a callable confirmation cmd in the
```
upward
```
domain, such as
```
asynSuccess
```
).
Distinction method: Before calling, run
```
jq '.interfaces[]|select(.cmd=="<cmd>")|.direction'
```
; if it is
```
webhook
```
, do not use
```
api
```
to call it, instead build a receiving end; if it is
```
callable
```
, use
```
api
```
.

Examples

Check which cmds can be invoked in an unnamed domain (read, only check catalog, no request sent):

bash

jq -r '.interfaces[] | select(.domain=="thirdParkForBolian" and .direction=="callable") | "\(.cmd)\t\(.readwrite)"' catalog/catalog.json

Start with sampleBody, preview first then send (write operation example, add

--yes

for official sending):

bash

# 1) Get sample body
jq -r '.interfaces[]|select(.cmd=="createCityOperationCouponTemplate")|.sampleBody' catalog/catalog.json

# 2) Preview signed request to confirm correctness
openydt api createCityOperationCouponTemplate --dry-run --body-file ./body.json

# 3) Official sending (write operation, must add --yes)
openydt api createCityOperationCouponTemplate --yes --body-file ./body.json

Call read interfaces directly (no --yes needed):

bash

echo '{}' | openydt api getAuthCommunities --body-file -   # community domain, readwrite=read

openydt-api-explorer

NPX Install

Tags

SKILL.md Content (Chinese)

When to use this skill

Usage: openydt api

--dry-run Preview

Write operations require --yes (Important: api does not automatically determine read/write)

Check available cmds and parameters from catalog

Uncallable webhooks (platform active push)

Examples