Kingdee Cloud Galaxy connector (金蝶云星空): ERP answers in chat, orders saved only after approval

This page is for IT staff and Kingdee implementers who connect a Kingdee Cloud Galaxy (金蝶云·星空, K/3 Cloud, standard or enterprise edition) data center to OrgRelay. It lists the form IDs and fields each tool queries, the third-party login authorization (第三方系统登录授权) you need, and what happens when a sales order is approved.

#What staff can ask

Sales assistants, warehouse staff and finance clerks can ask in Chinese or English. Typical requests:

• "上周给华东五金的销售订单有哪些？还有没审核的吗？" ("Which sales orders went to Huadong Hardware last week, and are any still unaudited?") calls orders.search with customer, date_from, date_to, and optionally status: B (审核中, under review).
• "物料 3.01.0021 各仓库还有多少？" ("How much of material 3.01.0021 is in each warehouse?") calls inventory.list with keyword: 3.01.0021. It returns one row per material and warehouse.
• "Show this month's receivables for Huadong Hardware." calls finance.receivables with the customer and dates.
• "What is the customer number for 华东五金?" calls customers.search.
• "按客户 CUST0035 下一张销售订单，物料 3.01.0021 共 500 件，含税单价 12.8。" ("Save a sales order for CUST0035: 500 of 3.01.0021 at 12.8 including tax.") calls orders.create_draft and waits for approval.

#Tools

Outputs are mapped to the field names in the connector spec. All reads go through DynamicFormService.ExecuteBillQuery with FieldKeys, a FilterString and paging by StartRow and Limit. limit defaults to 20 and is capped at 100. The cursor is the next StartRow. Document status values follow Kingdee's codes: A 创建 (created), B 审核中 (under review), C 已审核 (audited), D 重新审核 (re-audit). Name filters use like '%…%', so partial Chinese names match.

ExecuteBillQuery returns one row per entry line. A sales order with three lines comes back as three rows, and the connector keeps the first row per FID. A page can therefore hold fewer orders than limit while more pages still exist. The tool names follow OrgRelay's standard tools, so an English-speaking manager can ask the same question of Kingdee and of Odoo.

#Credentials and scopes

The connection form fields, in the order Kingdee admins usually collect them:

OrgRelay logs in with AuthService.LoginByAppSecret, sending acctid, user name, AppID, AppSecret and lcid: 2052 (Simplified Chinese). Kingdee returns a KDSVCSessionId, which the connector sends as the kdservice-sessionid cookie together with the ASP.NET session cookie. Sessions are reused while calls keep coming. After 15 minutes without a call, or when Kingdee reports an expired session, OrgRelay logs in again automatically. There is no OAuth flow and no refresh token to manage.

Kingdee has no API scopes. Access is the integration user's functional permissions (功能权限) and data permissions (数据权限). Grant view (查看) on 销售订单, 即时库存, 应收单 and 客户. Add new and save (新增 / 保存) on 销售订单 only if orders.create_draft should be able to succeed. Keep the integration user out of administrator roles. OrgRelay's catalogue lists these as SAL_SaleOrder:view, STK_Inventory:view, AR_receivable:view, BD_Customer:view and SAL_SaleOrder:save. The auth guide explains how OrgRelay keeps such credentials separate from staff logins.

#Which actions need approval and what the approver sees

orders.create_draft is the only write. It becomes an approval request that shows the customer number, each material number with quantity and optional tax-inclusive price, the order date (today if blank), the settlement currency (PRE001, 人民币, if blank) and any note.

On approval the connector calls DynamicFormService.Save for form SAL_SaleOrder with:

• bill type XSDD01_SYS (标准销售订单, standard sales order),
• FSaleOrgId set to the sales organization number from the connection settings,
• IsAutoSubmitAndAudit: false.

The order is saved in status A (创建). Your staff then review, submit and audit it in Kingdee as usual. When tax_price is missing, pricing is left to Kingdee's own defaults, and tax follows the material and customer settings. The result returns the new bill number (单据编号) so the approver can open it in Kingdee straight away. If Kingdee rejects the save, for example because of an unknown customer or material number, its field-level error message comes back unchanged.

Approvers are typically sales supervisors, and the human-in-the-loop page explains how to name them. The manufacturing solution page shows how a factory splits approvals between sales and planning. Every approved call carries orgrelay-approval-<approval id> and is written to the audit log.

#Set it up

1. In Kingdee, create a dedicated integration user (for example orgrelay) and grant the permissions above.
2. As administrator, open 系统管理 → 第三方系统登录授权 (in some versions under 系统管理 → 授权). Click 新增, choose the integration user, click 获取应用 ID, and record the AppID and AppSecret.
3. Find the data center ID. It appears in the data center list of the management center and in the WebAPI settings page.
4. Note the server URL your users log in with. Private deployments can use an internal address, as long as the OrgRelay Mac mini can reach it.
5. In OrgRelay, go to Admin → Business systems → App directory, choose 金蝶云星空 / Kingdee Cloud Galaxy, fill in the fields, and click Connect. OrgRelay logs in and shows the data center name and user name. The quickstart shows the same bind-and-test pattern for in-house systems.
6. Grant the connection to roles and keep orders.create_draft with the sales team. A test data center (测试账套) is the safest place for the first approved order, because Kingdee has no public sandbox.

#Limits and things it deliberately does not do

• Edition. The connector is for Kingdee Cloud Galaxy on K/3 Cloud (金蝶云星空 标准版 / 企业版), public cloud or private deployment, and speaks the K/3 Cloud WebAPI (Kingdee.BOS.WebApi.ServicesStub.*.common.kdsvc endpoints) described on Kingdee's Cloud Galaxy open platform. The Flagship edition built on Kingdee's Cosmic platform (金蝶云·苍穹 星空旗舰版) uses a different API family and is outside this connector. If it publishes an OpenAPI description of the endpoints you need, connect it through OpenAPI import instead.
• Rate limits. The connector sends one query per tool call and reads at most 100 rows. OrgRelay caps a connection at 120 calls per minute and pauses for 60 seconds after three consecutive failures. For public cloud quotas, follow Kingdee's open platform documentation.
• Result size. The AI sees about 12,000 characters of each result, so ask for one customer or one week at a time.
• Not exposed: submit, audit, unaudit or delete; purchase, production, cost and general ledger forms; outbound and inbound stock documents; customer creation. Reads cover whatever the integration user's data permissions allow; there is no separate organisation filter. Other Kingdee forms can be described in a small connector of your own; the examples are a starting point.
• Language. Field names and messages come back in Simplified Chinese because the login uses locale 2052. The AI translates when staff ask in English.

#Official MCP server and OrgRelay

Kingdee's open platform documentation for Cloud Galaxy does not describe a first-party MCP server. Community projects exist, for example a Python kingdee-k3cloud-mcp package that wraps the same WebAPI and offers stdio, SSE and streamable-http modes. OrgRelay can attach such a server as a third-party MCP connection when it runs in streamable-http mode (see MCP transports) and accepts a bearer token. Its stdio mode cannot be connected directly. Check what it exposes before granting it, because some community servers include write modes without approval.

The difference with OrgRelay is in the controls around the tools, not the API underneath. Tools are granted per role and department, every save waits for an approver, Kingdee calls share one audit log with systems like LingXing or Shopify, and everything runs on the company's own machine inside its network. That last point matters for private Kingdee deployments that never face the internet. The enterprise patterns and official servers pages go further, and the MCP overview explains the protocol itself.

#Common questions

Does the connector submit or audit sales orders in Kingdee? No. orders.create_draft calls Save with IsAutoSubmitAndAudit set to false, so the order is stored in Created status (创建, document status A). Submitting and auditing stay with your staff in Kingdee.

Does it work with a private (on-premise) Kingdee deployment? Yes, as long as the OrgRelay machine can reach the server URL. Enter the internal address ending in /k3cloud. Public cloud tenants use their ik3cloud.com address.

Why does the AI ask for a customer number instead of a customer name when creating an order? Kingdee's Save API resolves base data by number (FNumber). The connector passes the customer number and material numbers straight through, so the AI usually runs customers.search first to look up the number.

#Related

• All connectors
• Connector spec
• Human-in-the-loop approvals
• Security
• Kingdee community article on LoginByAppSecret