REST API 概览与身份验证

REST 访问要求 Enterprise 或 Manufacturer 订阅，且状态为 active 或 trialing。服务器在每次请求时检查密钥所有者的当前订阅；降级或失去有效状态后，旧密钥不能保留访问权限。

REST 使用 /api/v1 和以 exk_ 开头的 API 密钥。MCP 是独立的 Streamable HTTP 接口，地址为 /api/mcp，仅供 Manufacturer 使用，并要求手动配置专用 Bearer 令牌。两种凭据不能互换。这些 REST 路由没有实现 OAuth 授权流程。

以下路由提供六种翅片盘管计算引擎和制冷剂列表，不提供 REST 项目增删改查、Shell & Tube、制造文件或 CAD/PDF 导出。REST 密钥上的 projects:read 权限不会产生项目端点。制造详图仍仅限 Manufacturer；本指南不代表 REST 提供制造权限。

• API 密钥管理
• 文档目录

使用 API 实际部署的 ExCoil 环境的源地址，再加上 /api/v1。生产域名的基础 URL 为 https://excoil.net/api/v1。预览属于不同环境；预览中存在的代码不表示已发布到生产域名。

在 API 密钥页面生成密钥，并立即保存完整值：它只显示一次。所有请求都必须发送 Authorization: Bearer 加 REST 密钥，包括 GET /health 和 GET /refrigerants。请保留 Bearer 的大写首字母及后面的空格。浏览器登录 Cookie 本身不能验证这些路由。

计算 POST 请求应发送 Content-Type: application/json。密钥应保存在服务端安全存储中，不要放入浏览器代码包、URL、提示词、代码仓库或共享日志。密钥遗失或泄露时应撤销并更换；降级后仍可管理旧密钥。

BASE_URL='https://excoil.net/api/v1'
EXCOIL_API_KEY='exk_REPLACE_WITH_YOUR_REST_KEY'
curl --include "$BASE_URL/health" \
  -H "Authorization: Bearer $EXCOIL_API_KEY"

表中所有路径均相对于 /api/v1，且都要求身份验证和有效订阅。计算 POST 路由及 /refrigerants 还要求 calc:read。/health 不额外检查该权限。

普通计算路由直接接收引擎输入对象，不使用 data 或 inputs 包装。冷水和热水输入包含 air、water、coil、hydraulic、calib；蒸汽包含 air、steam、coil、hydraulic、calib；干冷器使用自己的 fluid、air、coil、hydraulic、calib 字段。DX 使用 air、coil、ref、calib。各引擎的必填字段不同，不要直接复制网页表单的显示对象，也不要跨模块复用请求体。

DX 蒸发器的 balanced 路由是例外：发送包含 inputs 和可选 options 的对象。inputs 中放置完整的 DX 蒸发器引擎输入。DX 冷凝器的 balanced 路由则直接接收冷凝器输入，不使用蒸发器的 inputs/options 包装。

DX 请求应在 ref.fluid 中使用 /refrigerants 返回的准确标识符。路由在选择物性表时也识别旧字段 ref.refrigerant 或顶层 refrigerant，但引擎的规范字段仍是 ref.fluid。成功匹配物性表并不能替代 ref 中其他必填字段。

REST 包装层只对请求体和制冷剂做有限检查，不执行全面的结构验证。它不会自动转换界面单位，也不会补齐所有缺失的引擎字段。发送前应在集成端验证必填值、物理范围、几何和校准参数。

• 各计算器的输入和结果详情

API 使用引擎字段名和单位，不受网页显示单位设置影响。JSON 数值必须提前转换；不要在数值字段中发送本地化数字字符串或单位标签。

计算成功时返回 {"success":true,"data":...}，data 为引擎结果对象。GET /refrigerants 使用相同包装，data 为标识符数组。GET /health 不同：直接返回 status、version 和 timestamp，没有 success 或 data。

HTTP 200 和 success:true 表示求解器返回了结果，不代表所有工程标准均已满足。应检查模块的 flags、收敛状态、notes 和可用性能诊断。请将警告与输入快照及结果一起保存，不要静默忽略不收敛或不可行标记。

平衡端点在 data 中返回各自的求解结果。应查看具体结果契约，不能假设所有端点都具有相同的 perf 或 flags 路径。较小的能量平衡误差只是数值诊断，不是独立验证、认证或制造许可。

{
  "status": "ok",
  "version": "1.0.0",
  "timestamp": "<ISO-8601 时间戳>"
}

限流以 REST 密钥和服务器进程为单位。它使用密钥配置的 rateLimit；缺失或为零时回退为每分钟 100 次请求。60 秒窗口从首次获准请求开始，不应假定在每个整分钟重置。

通过身份验证和订阅检查后，请求会在路由权限检查或计算之前消耗额度。因此健康检查、制冷剂列表、权限失败和计算错误都可能消耗额度。身份验证和订阅失败发生在此限流器之前。

读取 X-RateLimit-Limit、X-RateLimit-Remaining 和 X-RateLimit-Reset。Reset 是以秒为单位的 Unix 时间戳，不是毫秒或持续时间。429 响应包含这些响应头和 rate_limit_exceeded；此中间件不设置 Retry-After。等待重置，考虑时钟差异并限制重试次数，不要紧密循环。

限流器保存在内存中，进程重启后重置，也不是跨副本共享的全局配额。它不保证吞吐量、并发量或响应时间。此 REST 路由器没有实现逐请求截止时间，也不提供异步任务和状态轮询端点。

路由器生成的错误返回 error 和 message，不包含 success:false。检查 HTTP 状态和错误代码，并保留脱敏消息用于排查。解析器、代理或基础设施错误可能使用其他响应格式；不要在检查内容类型之前假定响应一定是 JSON。

{
  "error": "unauthorized",
  "message": "Invalid API key."
}

1. 确认目标环境、有效订阅及专用 REST 密钥。安全保存完整密钥，常规诊断仅记录前缀。
2. 用经过身份验证的 /health 检查连接；DX 计算还需查询 /refrigerants。将这两类请求计入请求预算。
3. 选择准确路由和引擎输入契约，明确转换单位并在发送前验证必填字段。各模块详情参见计算器指南。
4. 计算 POST 中添加 Authorization 和 Content-Type，并序列化完整输入。仅在平衡 DX 蒸发器中使用 inputs/options 包装。
5. 检查状态、响应格式、限流响应头和工程诊断。保存提交的输入、返回的引擎版本及全部警告。
6. 先纠正 400/401/403/422 的原因，不要盲目重试；遇到 429 应等待。撤销泄露密钥，并在选型、采购或制造前进行工程审核。

• 计算端点
• API 密钥生命周期