协会易开放接口 — 集成指南（总览）
面向龙虾机器人等对话式自动化：如何用同一套 HTTP 约定拉栏目、建表单、建问卷、推新闻、读待办与简易审批、为项目申报绑定表单、检索/维护会员、按分组名称快速创建议事表决事项。具体路径、请求体、字段含义在同目录 reference-*.md 中按任务打开。
能力一览
| 主题 | URL 前缀（接在 {BASE} 后） |
典型用途 | 展开文档 |
|---|---|---|---|
| 表单 | open/ai/form/ |
创建表单 | reference-form.md |
| 问卷 / 信息收集 | open/ai/questionnaire/ |
新建问卷、绑定表单 | reference-questionnaire.md |
| 项目申报 | open/ai/declare/ |
绑定申报主表、绑定评审节点表单 | reference-declare.md |
| 新闻 | open/ai/article/ |
栏目、去重、推送、编辑已推送文 | reference-article.md |
| 流程待办 | open/ai/process/ |
待办、摘要、审批 | reference-process.md |
| 会员 | open/ai/member/ |
搜索（DB姓名/单位名模糊匹配）、详情、updateMember |
reference-member.md |
| 会员/会费数据与分析 | open/ai/stat/ |
会员数据（明细 + 全部表单答案，敏感字段脱敏）、会费数据（已生效缴费记录）、年度快照 | reference-stat.md |
| 职业技能认定 | open/ai/skillExam/ |
拉取认定批次列表、绑定打分表单到认定批次考卷 | reference-skillExam.md |
| 议事表决 | open/ai/vote/ |
按已确定的分组名称批量创建普通议事事项（读名单后确认再调） | reference-vote.md |
通用约定
{BASE}：请求地址，https://www.shanghuiyi.com。- 鉴权：接口通常把
appKey放在 Query（?appKey=...）；密钥无效时请求失败，不要把完整密钥复述进聊天记录。 - 成功与否：只看
errno === 0；否则视为失败，用errmsg向用户说明，不得假定已创建成功。 - 调用方式：请求数据包含中文时，尽量使用python脚本，curl会存在编码问题，系统编码均为utf-8。
- POST JSON：
Content-Type: application/json，body 为 UTF-8 JSON；GET 一般无 body。 - 拼 URL：
{BASE}与路径段之间一条斜杠即可，例如{BASE}/open/ai/form/addForm?appKey=...，避免重复//。 - 绑定用
formId：凡 问卷bindingForm、项目申报bindingForm/bindingExpertCommonForm等需要formId的调用，只能使用①addForm成功时响应的data，或②addForm因同名表单已存在而失败时，errmsg中给出的已有formId（均由服务端返回）。禁止用户口述、手填或外部猜测的编号；禁止在「名称重复」时改formName再addForm规避（见 reference-form「表单名称重复」）。无可用formId则不调绑定。 addForm前必须与人确认结构：解析/拼装出待提交的表单 JSON 后，须按 JSON 做可读渲染（分级列表、按 Tab 的表格等），经用户确认无误后再调addForm；未对齐结构不得调用（见 reference-form「创建前与用户确认」）。
龙虾机器人执行要点
- 多步要把上一步的返回值记下来：例如
addForm→data为formId；创建问卷 →data为问卷id；问卷侧open/ai/questionnaire/bindingForm需要问卷id+formId（见 reference-questionnaire）。项目申报侧另有open/ai/declare/bindingForm，参数是decTitle+formId，不要把问卷的bindingForm与申报的混用（见 reference-declare）。中途丢了 id 只能让用户重试或去后台查。 - 按文档常用类型造表单：
paramType须为协会易认可的类型代码（reference-form 已汇总），优先仅用「常用类型」；禁止自造code；不再提供GET supportFieldType。表结构须先与用户确认并渲染预览后再addForm。addForm若报表单名称已存在：从errmsg取已有formId继续绑定；不要改formName再建一张新表。 - 推新闻前先拉栏目：用
categories里的id填categoryIds，不要猜数字（见 reference-article）。pushArticle的content须完整正文，禁止为省 token 或图方便截取、只发摘要（见 reference-article「正文完整性」）。修正已推送稿件时调updateArticle：body 里带pushArticle成功响应data中的文章id+ 完整content（及需改的标题、栏目等），须同一appKey对应账号创建该文（见 reference-article「updateArticle」）。 - 待办话术：列表短标题只用
applySubject；展开详情再拼formAnswer/extra（见 reference-process）。不要默认替用户点审批；用户明确说「通过/驳回」且业务允许时，再调audit。 - 项目申报绑定：
decTitle、nodeName须与后台配置一致（见 reference-declare）；评审节点绑定需要流程里已有对应名称的专家评审类节点。formId规则见上文「绑定用 formId」，不接受用户当字段输入。 - 会员：先按
keyword调search（返回MemberExpireInfo列表，含 memberId、username、companyName、mobile 等），再用memberId调detail看详情；仅当需要改信息时再updateMember（参数从detail取，见 reference-member）。 - 网络与合规：抓网页、下附件、解析 PDF 等须满足许可与用户授权；说不清时先问用户，不要硬抓。
- 职业技能认定：先
addForm（useTo: 3打分表单）拿formId，再skillExam/list拿批次id（examId），最后bindingForm绑定（见 reference-skillExam）。formId规则见上文「绑定用 formId」；examId只能来自list返回的id；重绑会覆盖原考卷表单，先确认。 - 议事表决：龙虾自己读名单，抽出姓名（没有则单位）当标题；分组名从名单识别或用户告知。把事项清单和分组名称给用户确认后再
POST addVotes。名单过长时自行分批调用，不要对用户说接口条数上限（见 reference-vote）。禁止向用户展示本协会分组列表。失败时读懂本次errmsg再据实告知，禁止编造成功或臆造原因。 - 会员/会费数据与分析（见 reference-stat）：接口只给原始数据，分析由你自己做。先看
total再分页拉取（单页 ≤1000），不得把分页子集当全量；会员数据含全部表单答案（多选值以「、」连接，分组计数之和可大于人数），敏感字段已脱敏（maskedFields标出），回答中不得复述手机号/证件号/邮箱/地址/证件照；会费数据只含已生效记录（不含处理中/退款），其汇总不要声称与后台会费统计页一致；年度会员数用memberYearStat的年末快照（不是"当年新增"）。
使用这些文档的方式
- 按用户意图对上表打开对应 reference 全文，再组请求与解析 JSON。
- 问卷 + 自建表：顺序见 reference-questionnaire「推荐流程」（可先表单后问卷再绑定，顺序不要颠倒）。
- 项目申报 + 自建表：主表或专家评审表绑定见 reference-declare；
formId仍来自表单 API。 - 表单：材料来自 Excel / Word / PDF / 合规网络提取时，按 reference-form「常见来源」「是否打分表」定
useTo，paramType优先常用类型、须合法；解析完成后先渲染给用户确认再addForm。 - 流程：按 reference-process 的类型表理解摘要；回复用户时按该文档「连成可读」的顺序组织话术。
- 会员：按 reference-member 的步骤与参数表调接口；不支持新增会员，仅
search/detail/updateMember。 - 会员/会费数据：按 reference-stat 走 —— ①
memberData/feeData看total再分页拉取（≤1000/页）→ ② 自己在 agent 侧清洗、分组、汇总（answers[].fieldName即维度）→ ③ 回复里写明数据条数、范围、时间口径与脱敏说明；敏感字段不得复述；会费只含已生效记录；年度趋势用memberYearStat。 - 议事表决：按 reference-vote 读名单、确认分组名称与事项后再
addVotes；过长自行分批；不要拉取或展示分组目录；失败按本次errmsg据实说，禁止编造。
集成时注意
- 表单：注意材料体积与超时；
paramType优先 reference-form「常用类型」，且须为该文档/对接方确认的合法code；未与用户确认结构不调addForm；解析后宜做可读渲染再请用户拍板（见 reference-form）；名称重复时勿换名重试addForm，按 reference-form 使用errmsg中的formId。 - 问卷：
title必填；open/ai/questionnaire/bindingForm仅传 Query（appKey、问卷id、formId），无 JSON body；其中formId须来自表单 API 返回值，见上文「绑定用 formId」。 - 项目申报：
open/ai/declare/bindingForm/bindingExpertCommonForm仅传 Query，无 JSON body；与问卷bindingForm路径与参数均不同；formId同上，不可由用户直输，见 reference-declare。 - 新闻：
publishTime格式见 reference-article；content必须完整、不可截取；体量大时预留超时或采用合规的分段/技术方案，不得用不完整正文代替。改稿用updateArticle，id取自pushArticle的data，详见 reference-article。 - 流程：摘要可能含隐私；开放接口不含完整审批轨迹；审批不可逆，操作前先向用户确认。
- 会员：
detail为简易表单结构；updateMember须带answerId（来自pages[]..id）与fieldId。失败看errmsg。 - 议事表决：只调
addVotes；分组名必须用户已确认；禁止展示分组列表；名单过长时自行分批、不要对用户说条数上限；投票人与时间仍回 Console 补。失败必须按本次errmsg据实说明，禁止编造（「一次最多创建200条」自行拆批，见 reference-vote）。
