/* MD / 富文本中的 .toc（含博客园搬家等嵌套结构）；.toc-box 在侧栏，不受影响 */
#content_views .toc,
/* 编辑器常在目录前后插入空 p（:empty 仍占 20px），一并去掉避免顶空隙 */
#content_views.markdown_views > p:empty:has(+ .toc),
#content_views.markdown_views > .toc + p:empty,
/* 富文本旧版目录标记 */
#content_views.htmledit_views #main-toc,
#content_views.htmledit_views #hr-toc,
#content_views.htmledit_views p[id*=\”-toc\”] {
display: none !important;
}
/* 目录去掉后，紧跟的首个标题不再多出一块上边距 */
#content_views.markdown_views > .toc + h1,
#content_views.markdown_views > .toc + h2,
#content_views.markdown_views > .toc + h3,
#content_views.markdown_views > .toc + h4,
#content_views.markdown_views > .toc + p:empty + h1,
#content_views.markdown_views > .toc + p:empty + h2,
#content_views.markdown_views > .toc + p:empty + h3,
#content_views.markdown_views > .toc + p:empty + h4 {
margin-top: 0 !important;
}
把 ERP 与电商平台或进销存系统打通时，最常被问到的场景是：单据怎么自动进云星空？
很多企业的起步方式是导 Excel，手动导入。订单量小的时候还能应付，订单一多，漏单、错单、库存对不上就全来了，月底基本都在对账。
整条链路大致是这样：
flowchart LR
A[电商与进销存系统] –> B[鉴权登录]
B –> C[查询待同步单据]
C –> D[字段映射与清洗]
D –> E[保存单据]
E –> F[提交与审核]
F –> G[结果回写]
看着简单，但每一个箭头后面都有默认值在等着你。
这一篇讲前半段：环境确认、登录鉴权、单据查询。这三步是后面所有工作的地基，也是最容易劝退人的地方。后面还有两篇：第二篇讲保存接口的原理、参数与返回结构，第三篇讲六个真实的坑、性能优化和示例代码。
一、动手写代码前，先确认三件事
这一节的顺序建议不要省。很多项目卡在第一步——代码调不通，回头查环境，才发现方向一开始就是错的。
需求文档上写的是"云星空"，机房实际部署的却是 K/3 WISE——这种情况在项目里并不罕见，而这两套系统的接口是完全对不上的。
开工第一件事：确认版本，最好截图留证。本文讲的全部基于云星空。
云星空的 WebAPI 不是部署完就能直接用的，需要先在系统里把对应的开关打开，并拿到正确的服务地址。
服务地址一般是这个格式：
http://你的服务器地址/K3Cloud/
调用时在它后面拼具体的服务路径，比如鉴权服务是 AuthService.ValidateUser.common.kdsvc，保存服务是 DynamicFormService.Save.common.kdsvc。
两点提醒：
- 地址里用 IP 还是域名，决定了后续配置文件里配 HTTP 还是 HTTPS
- 如果部署走的是 AAS 中间件，通常还会多一层路径和证书校验，最好提前让运维把调用白名单和证书准备好
acctID 是数据中心的 ID，每个数据中心有独立的一个。
获取方式：浏览器打开登录页，能看到数据中心列表，列表对应的 ID 就是 acctID。
这里有个比较隐蔽的坑：如果做过数据迁移，数据库从旧服务器搬到新服务器，acctID 可能会变。代码里如果写死了旧 ID，表现就是登录一直失败——这个问题很难第一时间想到。
二、鉴权：登录接口拿 Cookie
云星空所有接口都遵循同一个模式：一个 URL 地址 + 一个 JSON 数据包。
登录接口地址：
http://ServerIp/K3Cloud/Kingdee.BOS.WebApi.ServicesStub.AuthService.ValidateUser.common.kdsvc
请求体：
{
“acctid”: “你的数据中心ID”,
“username”: “用户名”,
“password”: “密码”,
“lcid”: 2052
}
其中 lcid 是语言 ID，2052 表示简体中文。
返回结果里，登录结果类型为 0 表示成功，其余均为失败。
关键点：登录成功后要保存 Cookie，后续所有接口调用都需要带上它。一个业务逻辑单元内登录一次即可。
补充一句：新版 Web API 已经升级为第三方应用授权形式。如果是新项目，建议直接走官方 OpenAPI 平台那条路，它提供 .NET、Java、Python 等多语言 SDK。本文讲的是通用性更好的登录鉴权方式，适合已有系统对接和自建集成。
三、读数据：executeBillQuery 分页拉取
把电商订单、进销存流水同步过来，第一步是查询。
核心参数：
参数
说明
FormId
业务对象表单 ID，如销售订单 SAL_SaleOrder
FieldKeys
需返回的字段集合，逗号分隔
FilterString
过滤条件
Limit
单次返回的最大行数
StartRow
起始行索引
TopRowCount
是否返回总行数
一个典型的请求体：
{
“FormId”: “SAL_SaleOrder”,
“FieldKeys”: “FBillNo,FDate,FDocumentStatus,FSaleOrgId.FNumber,FMaterialID.FNumber,FQty”,
“FilterString”: “FDate >= ‘2026-01-01’ and FDocumentStatus = ‘C’”,
“Limit”: 500,
“StartRow”: 0
}
三个要注意的点：
① 单据状态码要记住。 Z 暂存、A 创建、B 审核中、C 已审核、D 重新审核。多数对接只关心 C，也就是已审核。
② 分页不要无限翻页。 Limit 加 StartRow 是可行的，但数据量一大，越往后翻越慢。更稳的做法是用时间戳或自增主键做游标：每次只取增量，记录上一次同步到的最大值，下次从它之后开始查。
③ 字段名有两套写法，别混。 FStockOrgId 是内码，FStockOrgId.FNumber 是编码。对接外部系统时通常用编码，因为对方系统里存的是编码，不是内码。
到这里，"能查"这一步就算通了。下一篇继续讲怎么把数据写回去——那才是真正容易踩坑的地方。
参考资料
内容
来源
登录服务地址、Cookie 鉴权机制、请求参数结构
博客园《Kingdee 云星空 WebApi 详解系列（一）保存》
版本确认、WebAPI 开关、acctID 获取与迁移风险、AAS 中间件注意事项
CSDN《Kingdee 云星空 WebAPI 附件上传实战：从登录到挂单完整指南》
executeBillQuery 参数、Limit 分页、FDocumentStatus 状态码
Kingdee 云星空官方接口文档及 CSDN 相关技术文章
新版 Web API 第三方应用授权、OpenAPI 平台与多语言 SDK
Kingdee 云星空 OpenAPI 官方平台
说明：本文接口地址与参数整理自上述公开资料。实际对接时请以你所处的星空版本和数据中心配置为准，建议先在测试账套验证通过再上生产。
