QingERP API 接入说明

QingERP API 的设计目标是提供面向业务用例的 HTTP 接口。外部契约使用 /api/v1，这一版本号与底层 Odoo 运行版本不同。

以当前实例的契约为准

本文介绍接入原则。接口是否可用、支持哪些业务对象及字段，取决于实例安装的 qing_api 与业务接口模块。请向管理员获取该实例的 OpenAPI 文档，不要把设计示例视为已部署接口。

接入准备

1. 确认系统地址、版本和已安装的业务接口模块。
2. 获取当前实例导出的 OpenAPI 契约及其访问要求。
3. 创建专用集成用户，限定公司与记录权限。
4. 按实例说明创建密钥，并保存到受控的密钥管理位置。
5. 先在测试环境完成只读调用，再验证写入和异常路径。

认证与权限

接口设计采用 Bearer API Key。鉴权通过后仍需遵守业务对象访问权限、记录规则和公司范围，不应通过提升为超级用户规避权限校验。

Authorization: Bearer <YOUR_API_KEY>

此处为请求头格式，不包含可直接调用的业务端点。具体 HTTP 方法、路径、参数和响应以当前实例契约为准。

写入与重试

对支持幂等键的写入接口，按契约生成和保存幂等标识。请求超时或外部结果不明确时，先查询原请求结果，避免重复创建业务单据。

联调检查表

检查项	需要确认
网络	HTTPS、域名和证书正常
认证	密钥有效，所属用户正确
授权	公司、对象及记录权限正确
契约	参数、字段和响应符合实例文档
异常	状态码、错误信息与请求标识可追踪
业务结果	真实业务对象及关联关系符合预期

网络连通、认证成功、业务成功应分别记录。