集成使用 API

密钥管理

在个人资料页面创建和注销 API 密钥（需要 Business plan）。密钥仅在创建时完整显示一次；后续所有接口调用均须在 X-API-Key 请求头中携带。

当前开放的端点

API 密钥驱动与 Web 界面相同的核心服务端点。当前文档重点说明两类自动化流程：/api/v1/axis 下的坐标转换服务，以及 /api/v1/quality-analysis 下的质量分析服务。计划限制（每日任务数、文件体积）与网页控制台保持一致。

坐标转换接口

向 POST /api/v1/axis/transform 发送源与目标 CRS、坐标点集及 X-API-Key 头。接口响应返回与 Axis 工作区相同的数据结构，包含完整的转换路径信息。CRS 检索与参考框架查询亦在同一路径前缀下提供。

质量分析完整流程

1. 上传观测文件：发起 POST /api/v1/quality-analysis/upload（multipart/form-data 格式，字段名为 files，每次最多 20 个文件），并附加 X-API-Key 头。响应中将返回每个文件的对应记录。
2. 创建分析任务：发起 POST /api/v1/quality-analysis/tasks，传入 JSON {"config": {"tool": "<mode id>"}, "files": [<步骤 1 返回的文件记录>]}。模式标识包含："fast" 对应 Fast Mode，"flash" 对应 Flash Mode，"full" 对应 Full Mode，"teqc" 对应 TEQC Mode。
3. 轮询 GET /api/v1/quality-analysis/tasks/{taskId} 直到状态变为 completed；完成后的响应将包含完整的综合质量结果对象。
4. 导出 PDF 报告：通过 GET /api/v1/quality-analysis/tasks/{taskId}/report.pdf 获取专业质量分析报告文档。

Webhooks 异步通知

无需反复轮询，注册 Webhook 后 PosFlow 会在任务处理完毕时主动发送通知。在 /api/v1/webhooks 端点下管理 Webhooks: POST 创建（请求体包含 url、events，以及可选的 secret 与 description），GET 查看列表，DELETE /api/v1/webhooks/{id} 删除，POST /api/v1/webhooks/{id}/test 发送模拟测试通知。接收地址必须为公网可访问的 https 协议；私有和内部 IP 地址将被系统拒绝。

Webhook 事件与载荷格式

当前支持三类事件：质量分析或处理任务成功结束时触发 "analysis.completed"；格式转换任务终结时分别触发 "processing.completed" 或 "processing.failed"。每次推送均为 JSON POST 请求，包含 event、timestamp、全局唯一 id 与携带任务详情的 data 对象。事件名称同时在 X-Webhook-Event 头中注明。

签名验证与可靠性保障

若配置了 secret 密钥，每次回调推送均会在 X-POSFLOW-Signature 请求头中提供请求体的原始 HMAC-SHA256 签名（格式为 "sha256=<hex>"；X-Webhook-Signature 则携带纯十六进制字符）。接收端使用预留 secret 计算哈希后比对校验。投递失败将以指数退避算法自动重试最多 3 次；连续失败超过 10 次的 Webhook 将被自动停用，因此请确保接收服务器快速返回 2xx 状态并进行异步业务处理。

调用频率规范

所有请求均根据套餐计划受速率限制。推荐合理使用批量接口，在遇到错误时引入退避重试；在进行持续性大批量解算前，请提前联络技术支持以便合理协调计算资源。