openydt CLI Shared Base

This skill is the shared basic rule for the Aike Smart Parking Open Platform CLI (

openydt

). All openydt domain skills (park / parking / trade / coupon / ticket / device / blacklist / visitor / data, etc.) should read this document first before executing specific tasks to unify configuration, signature, status code, rate limiting and security handling.

openydt

encapsulates the open platform interfaces into command-line commands: it automatically handles signature authentication (v2/v3), multi-authorizer profiles, multi-environments (test/dev/prod), and has built-in retry and backoff mechanisms.

Configure Profiles and Credentials

Credentials are managed by "authorizer profiles", each profile contains key/secret/env/sign. The configuration file is located at

~/.config/openydt-cli/config.json

(respects

XDG_CONFIG_HOME

), with permission 0600.

bash

# Add or update an authorizer profile (start here for first-time use)
openydt config set --profile demo --key test --secret 123456 --env test --sign v2

# List all profiles (secret is desensitized), the one with * is the current profile
openydt config list

# Switch current profile
openydt config use demo

# Print configuration file path
openydt config path

--profile / --key / --secret

are required for

config set

;

--env

defaults to

test

--sign

defaults to

v2

When running
```
config set
```
for the first time, if there is no current profile, it will automatically set the new profile as the current one.

Environment Variable Override (Suitable for CI)

The following environment variables have higher priority than values in profiles, allowing temporary override without modifying the configuration file:

Variable	Description
`OPENYDT_PROFILE`	Select profile name
`OPENYDT_KEY`	Override key
`OPENYDT_SECRET`	Override secret
`OPENYDT_ENV`	Override environment test\|dev\|prod
`OPENYDT_SIGN`	Override signature version v2\|v3

Priority (from lowest to highest): Built-in default < profile < environment variable < explicit command-line flag. Empty values are ignored. As long as

OPENYDT_KEY

OPENYDT_SECRET

are set, you can directly call the interface even if there is no profile with the same name.

Global Flags

Common to all commands:

Flag	Description
`--profile <name>`	Specify authorizer profile (defaults to current profile)
`--env test\|dev\|prod`	Specify environment (defaults to test)
`--output` , `-o json\|table`	Output format (defaults to json)
`--sign v2\|v3`	Signature version (defaults to profile setting, otherwise v2)
`--yes` , `-y`	Confirm write operation execution
`--dry-run`	Only print the signed request to be sent, do not actually send it
`--verbose` , `-v`	Output debug information to stderr

Base URLs for each environment:

test →
```
https://openapi-test.yidianting.com.cn
```
dev →
```
https://openapi-dev.yidianting.xin
```
prod →
```
https://open.yidianting.xin
```

Authentication Verification

After configuration, perform a smoke test (internally calls

getAuthParkCodes

to confirm the credential/signature link is available):

bash

openydt auth test

Success outputs

✓ Authentication passed (status=1)

and lists authorized parking lots; failure prints status/message/resultCode and returns with the corresponding exit code.

Signature

Request path is in the form

POST {base}/openydt/api/v3/{cmd}?sign={sign}

, with the

Authorization: base64(key:ts)

header. Timestamp

ts

is local time

yyyyMMddHHmmss

, valid for 10 minutes.

Version	Algorithm	Description
v2(default)	`lower(md5(key:ts:secret))`	Does not include body; available by default in test environment
v3	`lower(md5(key:ts:body:secret))`	Includes compacted body

Important: Test keys only accept v2 in practice; using v3 to call test keys will return "signature error" (status=4) unless the platform has specifically enabled v3 for that key. Keep v2 by default, only use

--sign v3

after the platform explicitly enables v3 for the key.

The body used for signature must be byte-consistent with the actual sent body: the CLI will first compact the JSON and use it for both signature and sending (internal spaces in strings like

"2019-04-16 00:11:25"

are retained).

Three-tier Command Model

There are three paths to call any interface, selected by priority:

Domain First-class Command(Preferred):

openydt <domain> <command>

, parameters are structured as flags, most user-friendly. For example

openydt park get-auth-park-codes

openydt parking <subcommand>

. Currently built-in domains:

blacklist coupon data device park parking redlist ticket trade visitor

General Fallback:

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

, automatically signs and POSTs for any business code cmd, covering any callable interface.

bash

openydt api getParkFee --body '{"carCode":"粤EJW962"}'
openydt api getAuthParkCodes
echo '{"parkCode":"PTD2YBBZ"}' | openydt api getParkOnSiteCar --body-file -

--body

and

--body-file

are mutually exclusive;

--body-file -

reads from stdin.

Schema Exploration(if available): Used to discover interfaces and fields, then return to ① or ②.

Response Envelope and Status Codes

The platform uses a unified envelope:

{"data":..., "message":"...", "resultCode":N, "status":N}

Meaning of

status

status	Meaning
1	Business success
2	Business failure (check resultCode)
3	System exception
4	Signature error
5	Key error
6	Unauthorized
7	Incomplete request parameters

When

status == 2

, check

resultCode

(common business codes, from

internal/client/codes.go

resultCode	Meaning
901	System exception occurred
902	Remote server did not respond
903	Operator does not exist
904	Parking lot does not exist
905	No on-site vehicle found
906	Bill does not exist
907	Bill has been synchronized
908	Other errors
909	Request parameter error
910	No parking lot found under the authorizer
911	No permission to operate this parking lot
912	Fee inquiry timed out, please retry
1801	Specified vehicle not found

Process Exit Codes

Exit Code	Meaning
0	Success(status=1)
1	Business failure(status=2 or other non-success status)
2	Parameter error(usage error)
4	Authentication failure(status=4 signature /5 key /6 unauthorized)
5	Network/transmission failure

Rate Limiting and Retry

Authorizers with fewer than 60 authorized parking lots: rate limit 300 times/minute. Throttle batch calls to avoid triggering 429.
The client has built-in retry + exponential backoff(starts at about 400ms, with jitter, maximum 3 retries by default).
Automatically retries on occasional gateway 404, connection reset, 429/502/503/504; does not retry non-envelope HTML error pages.
"Fee inquiry timed out(resultCode 912)" is a business state, need to retry as prompted, not within network retry scope.

Security Rules

Write operations require
--yes
: Any operation that changes the platform state, such as payment, gate opening, coupon issuance, monthly pass activation, adding/removing from blacklist, etc., must explicitly include
```
--yes
```
to execute, avoiding misoperations.
Preview with
--dry-run
first: Use
```
--dry-run
```
for dangerous or uncertain requests to view the signed request to be sent(URL/sign/ts/body), then remove it after confirmation.
Do not output keys in plain text: Do not print key/secret to the terminal or logs;
```
config list
```
has desensitized the secret.
Verify in
```
test
```
environment by default; be sure to confirm with users before switching to
```
prod
```
.

Test Parking Lots (Test Environment Only)

parkCode	Purpose
`1ZS7H5PQH9`	Fee inquiry available, matching test license plate `粤EJW962`
`PTD2YBBZ`	Has historical data, suitable for querying records / on-site vehicles

Examples:

bash

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

openydt-shared

NPX Install

Tags

SKILL.md Content (Chinese)

openydt CLI Shared Base

Configure Profiles and Credentials

Environment Variable Override (Suitable for CI)

Global Flags

Authentication Verification

Signature

Three-tier Command Model

Response Envelope and Status Codes

Process Exit Codes

Rate Limiting and Retry

Security Rules

Test Parking Lots (Test Environment Only)