openydt-api-explorer

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

CRITICAL：开始前 MUST 先用 Read 工具读取
../openydt-shared/SKILL.md
（认证 / profile / 签名 / 状态码 / 限速 / 安全规则）。
openydt api
与一等命令走完全相同的签名、包络、退出码与限速逻辑，未读共享基座不要执行任何命令。

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

平台共 423 个接口，只有约 143 个被做成了域一等命令（

openydt <域> <命令>

，参数已结构化为 flag）。当你要调的接口没有专属子命令时，用本技能的通用兜底：

bash

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

api

对任意可调用（direction=callable）的业务编码 cmd 自动签名并

POST

，覆盖一等命令没点名的所有域，例如：

```
cityOperationCoupon
```
城市运营券（创建/发放城市运营券模板）
```
thirdParkForBolian
```
第三方车场缴费接入回执
```
upward
```
上行数据上报回执（如
```
asynSuccess
```
）
```
community
```
小区门禁（如
```
getAuthCommunities
```
）
```
ad
```
广告统计、
```
preferential
```
/
```
score
```
积分兑换、
```
invoice
```
发票、
```
ydtUser
```
用户认证等

这些域在

catalog.json

里

included=false

（没生成一等命令），但只要

direction=callable

就能用

api

直接调。

选择顺序：先找一等命令（
openydt <域> --help
或对应域技能），找不到再用
api
兜底。一等命令把参数拆成了 flag、自动判定读写、更不易出错；
api
是“原始 JSON 直发”，更通用但要你自己保证 body 正确。

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.

用法：openydt api

Usage: openydt api

bash

undefined

bash

undefined

1) 行内 JSON body（最常用）

1) Inline JSON body (most commonly used)

openydt api getParkFee --body '{"parkCode":"1ZS7H5PQH9","carCode":"粤EJW962"}'

2) 无参接口可省略 body

2) Omit body for parameterless interfaces

openydt api getAuthParkCodes

3) 从文件读 body

3) Read body from file

openydt api getParkOnSiteCar --body-file ./body.json

4) 从 stdin 读 body（- 表示 stdin），适合管道 / 大 body

4) Read body from stdin (- indicates stdin), suitable for pipelines / large bodies

echo '{"parkCode":"PTD2YBBZ"}' | openydt api getParkOnSiteCar --body-file -


- `<cmd>`：业务编码，**就是 catalog 里的 `cmd` 字段**（如 `getParkFee`、`createCityOperationCouponTemplate`）。注意是 cmd，不是 `dir` 路径。
- `--body` 与 `--body-file` **互斥**；二者都不给则发送空 body（`{}`），仅适合无参接口。
- body 是**原始 JSON**：CLI 会先做 JSON compact 再用于签名与发送（与一等命令一致），字符串内部空格如 `"2019-04-16 00:11:25"` 会保留。
- 参数命名与嵌套结构**完全照搬接口定义**（见下文从 catalog 查参数）；写错字段名通常返回 `status=2 / resultCode=909 请求参数错误` 或 `status=7 请求参数不完整`。

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 预览

--dry-run Preview

不确定 body 或在 prod 环境前，先用

--dry-run

只打印将发送的签名请求（URL / sign / ts / compact 后的 body），不实际发送：

bash

openydt api createCityOperationCouponTemplate --dry-run \
  --body '{"parkCodeList":["PRJ9YJ19"],"couponTemplate":{"name":"抵扣1元券","faceValue":1}}'

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}}'

写操作必须 --yes（重要：api 不自动判定读写）

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

api
命令本身不会判断 cmd 是读还是写，是否需要确认完全交给你负责：

凡是会改变平台状态的 cmd（建/改/删、发券、缴费、开闸、上报回执等），你必须显式加
--yes
，否则被安全拦截不执行。
一等命令会自己识别写操作并要求
```
--yes
```
；
```
api
```
不会替你识别，所以用
```
api
```
调写接口时务必自己确认 readwrite 并加
--yes
。
判断某 cmd 读写：查 catalog 的
```
readwrite
```
字段（
```
read
```
/
```
write
```
），见下文。

bash

undefined

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

undefined

写操作（catalog readwrite=write），必须 --yes

Write operation (catalog readwrite=write), must add --yes

openydt api createCityOperationCouponTemplate --yes
--body '{"parkCodeList":["PRJ9YJ19"],"couponTemplate":{"name":"抵扣1元券","totalNum":2,"couponType":1,"faceValue":1,"validFrom":"2019-04-28 00:00:00","validTo":"2020-04-28 00:00:00"}}'

undefined

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"}}'

undefined

从 catalog 查可用 cmd 及参数

Check available cmds and parameters from catalog

接口清单在

../../catalog/catalog.json

（绝对路径

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

）。顶层结构

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

，每个 interface 对象关键字段：

字段	含义
`cmd`	业务编码，直接作为 `openydt api <cmd>` 的 cmd
`domain` / `dir`	所属域 / 文档路径（仅供归类，不是 api 的入参）
`direction`	`callable` =可主动调 / `webhook` =平台主动推送（见下节，不能调）
`readwrite`	`read` / `write` ——决定调用时是否要加 `--yes`
`included`	是否已做成一等命令； `false` 表示要用 `api` 兜底
`excludeReason`	未做成一等命令的原因（ `out-of-scope-domain` / `deprecated` / `no-endpoint` / `vems-only` 等）
`params`	参数定义数组： `name` / `required` / `type` / `desc` / `group` （ `group` 非空表示该参数嵌在某个子对象里）
`sampleBody`	官方示例请求 body——构造 `--body` 的最佳起点，照抄字段名再改值
`sampleResponse`	示例响应，帮你预判返回字段

用

jq

python3

检索（不要在终端打印密钥，这里只查清单不涉及凭据）：

bash

undefined

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

undefined

按 cmd 看完整定义（params + sampleBody）

View complete definition by cmd (params + sampleBody)

jq '.interfaces[] | select(.cmd=="createCityOperationCouponTemplate")' catalog/catalog.json

列出某个未点名域所有“可调用”的 cmd 及读写

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

全量“没做成一等命令但可调用”的接口（included=false 且 callable）

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

只看某 cmd 的参数清单（含嵌套 group）

View only the parameter list of a specific cmd (including nested groups)

jq '.interfaces[] | select(.cmd=="createCityOperationCouponTemplate") | .params' catalog/catalog.json


**included=false 但 direction=callable 的接口照样能用 `api` 调**——常见于城市运营券、第三方车场接入（thirdParkForBolian）、上行回执（upward）、小区门禁（community）、广告/积分/发票/ydtUser 等“未点名域”。`included=false` 只是“没生成专属命令”，不代表“不能调”；判断能否调用看 `direction`，判断要不要 `--yes` 看 `readwrite`。

构造流程：① `jq` 取目标 cmd 的 `sampleBody` → ② 照抄字段名、按 `params` 校对必填/类型/嵌套 → ③ `--dry-run` 预览签名请求 → ④ 写操作加 `--yes` 正式发。

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.

不能调用的 webhook（平台主动推送）

Uncallable webhooks (platform active push)

catalog 中

direction=webhook

的接口（共 61 个，如

reportParkinglotChange

车位变更上报）是平台主动 POST 到你方接收端的回调，方向与 callable 相反：

CLI 不能主动调这些 cmd——它们没有“你方请求平台”的入口，
```
openydt api <webhook-cmd>
```
不是正确用法（平台不提供该方向端点）。
要接收这类推送，需你自建一个 HTTP 接收端（webhook receiver），向平台登记回调地址，由平台在事件发生时把
```
sampleBody
```
形态的数据 POST 给你；你的服务负责验签、处理并按约定返回（很多上行回执对应一个
```
upward
```
域的 callable 确认 cmd，如
```
asynSuccess
```
）。
区分方法：调用前先
```
jq '.interfaces[]|select(.cmd=="<cmd>")|.direction'
```
，是
```
webhook
```
就别用
```
api
```
调，改为自建接收端；是
```
callable
```
才用
```
api
```
。

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

查某未点名域有哪些可调 cmd（读，纯查 catalog，不发请求）：

bash

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

用 sampleBody 起手、先预览再发（写操作示例，正式发要加

--yes

）：

bash

undefined

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

undefined

1) 取示例 body

1) Get sample body

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

2) 预览签名请求，确认无误

2) Preview signed request to confirm correctness

openydt api createCityOperationCouponTemplate --dry-run --body-file ./body.json

3) 正式发（写操作，必须 --yes）

3) Official sending (write operation, must add --yes)

openydt api createCityOperationCouponTemplate --yes --body-file ./body.json


读接口直接调（无需 --yes）：

```bash
echo '{}' | openydt api getAuthCommunities --body-file -   # community 域，readwrite=read

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