openydt CLI Shared Base
This skill is the shared basic rule for the Aike Smart Parking Open Platform CLI (
). 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.
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
), 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
- When running 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 |
|---|
| Select profile name |
| Override key |
| Override secret |
| Override environment test|dev|prod |
| 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
+
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 |
|---|
| Specify authorizer profile (defaults to current profile) |
| Specify environment (defaults to test) |
| , | Output format (defaults to json) |
| Signature version (defaults to profile setting, otherwise v2) |
| , | Confirm write operation execution |
| Only print the signed request to be sent, do not actually send it |
| , | 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
to confirm the credential/signature link is available):
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
is local time
, 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
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
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>
openydt park get-auth-park-codes
openydt parking <subcommand>
blacklist coupon data device park parking redlist ticket trade visitor
- General Fallback:
openydt api <cmd> --body '{...}'
bash
openydt api getParkFee --body '{"carCode":"粤EJW962"}'
openydt api getAuthParkCodes
echo '{"parkCode":"PTD2YBBZ"}' | openydt api getParkOnSiteCar --body-file -
- 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}
.
| 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
, check
(common business codes, from
):
| 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 : 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 to execute, avoiding misoperations.
- Preview with first: Use 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; has desensitized the secret.
- Verify in environment by default; be sure to confirm with users before switching to .
Test Parking Lots (Test Environment Only)
| parkCode | Purpose |
|---|
| Fee inquiry available, matching test license plate |
| 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"}'