---
name: ysld-open-platform
description: 接入和调用易数链动开放平台全部对外应用接口，检索各业务操作、生成请求、完成 HMAC 签名、参数预检、真实调用和结果未知恢复。适用于易数链动 API 对接、SDK 封装及接口排障；不用于内部运营管理接口或供应商直连。
---

# 易数链动开放平台 API 调用

## 找到具体接口

本技能完整收录当前发布目录中的每个对外操作。先读
[接口索引](references/index.md)，按业务或 operation 找到
`references/operations/<operation>.md`。每个文件包含字段表、请求体、预检和执行命令、
业务约束及响应处理；只读取本次任务所需的接口文件。

机器可读完整目录是 [catalog.json](references/catalog.json)，完整请求协议是
[OpenAPI](references/openapi.json)。也可运行：

```sh
node scripts/call.mjs list
node scripts/call.mjs describe caocao.cities
```

## 准备与调用

调用需要 Node.js 18+，脚本和 SDK 无第三方依赖。所有操作统一使用
`POST https://www.yishuld.com/api/v1/open/invoke`，外层为
`{"version":"1.0","operation":"操作名","params":{}}`。
`open.yishuld.com` 是文档与技能下载站，不是业务调用入口。

1. 先按接口文档确定环境、权限和前置查询结果。完整字段表不替代条件必填、
   商品可用性、业务引用和服务端授权校验。示例中的 `REPLACE_` 值须替换，
   不自行编造商品 ID、报价引用或业务状态。
2. 将参数放到 UTF-8 JSON 文件（支持 Windows 常见的 UTF-8 BOM）。读取真实凭据前先通过公开签名向量：
   `node scripts/call.mjs sign-check`。
3. 默认预检，不发送请求：
   `node scripts/call.mjs call --operation caocao.cities --params params.json`。
4. 用户已授权实际查询时，使用下列命令。真实结果保存到指定私有文件，
   终端只输出状态和 requestId，按任务需要读取结果中的字段。

```sh
node scripts/call.mjs call --operation caocao.cities --params params.json --config /private/ysld.json --execute --output /private/result.json
```

写操作还需用户对该业务动作的授权和 `--allow-write`，不要把安装技能、接口存在、
`--execute` 或应用权限当作用户授权。支付、退款、下单、分账和提现尤其要核对
原订单、金额、单位、幂等键和业务对象。脚本不自动重试。

复杂参数的内部字段、数组数量及金额单位见对应接口的“复杂参数内部字段”。
预检会校验已登记必填字段和这些复杂参数的结构、类型及约束；业务条件仍由服务端验证。
`receivers`、`guests` 是直接传数组；小腾 `details`、`divide_refund_details`
是数组编码一次后的 JSON 字符串，不能混用或重复编码。
亿奇达 `template` 的顺序和数量必须与已确认的商品模板一致，仅模板数为零时传空数组。

## 凭据与签名

[认证与恢复规范](references/authentication.md) 提供配置、七行待签串、错误处理。
配置文件含 `origin, appId, accessKey, keyId, secretKey`，由运营安全交付。
不得在聊天、源码、浏览器、命令行参数或日志中填写密钥。配置和结果文件应仅本人可读，
不提交 Git。不可用 App/H5 用户 Token、运营 Bearer 或供应商密钥代替应用 HMAC。

SDK 也可直接用于生成集成代码：
[Node.js](scripts/client.mjs) 和 [Python](scripts/ysld_open.py)，均使用完整目录，
保持目录结构。传入原始 JSON 文本可保留长整数及精确金额；不要重新序列化已签名请求体。

## 结果处理

HTTP 200、success=true 或 ACCEPTED 均不能单独证明支付、退款、下单或发券终态。
保留 `responseText` 中的原始字段、金额单位和精确数字。
出现 202、OUTCOME_UNKNOWN、超时或网络中断，先按原业务键查询；
只执行该操作明确提供的恢复接口，不更换原订单号或幂等键重下。
供应商回调与商户通知不能混用；通知协议由运营分配。

服务端仍检查应用归属、接口授权、有效期、并发、供应商配置及写入开关。
`sandboxOnly=true` 的操作仅用于明确配置的模拟环境；普通接口地址不代表模拟环境。

## 版本与覆盖范围

[接口索引](references/index.md)列出逐项覆盖范围；安装包根目录的 `manifest.json`
记录发布提交、操作总数、各业务数量和全部 operation。更新技能时用官方完整安装包
替换旧目录。公开文档：https://open.yishuld.com/#catalog 。