Kingdee Cloud Integration Guide: WebAPI Authentication and Bill Read/Write

API Shape Overview

Kingdee Cloud exposes a WebAPI mounted under /K3Cloud/, invoked via HTTP POST with application/json bodies. The endpoint URL is the fully qualified service name: {server}/K3Cloud/{namespace}.{class}.{method}.common.kdsvc. The three core services are AuthService.ValidateUser (login), DynamicFormService.ExecuteBillQuery (query), and DynamicFormService.Save (write).

Step 1: ValidateUser Login

Login is the prerequisite for everything else; on success the server returns a session cookie (kdservice-sessionid) that subsequent calls must carry. Parameters are passed as a positional array: account ID (acctID — the data center's FDATACENTERID, not the account set code), username, password, and locale ID (2052 for Simplified Chinese, 1033 for English). Create a dedicated integration account with minimal permissions, rotate its password, and handle session expiry with automatic re-login. Newer versions also support AppID/AppSecret login via the Login method, useful when storing a plaintext password is not acceptable.

Step 2: ExecuteBillQuery

To query sales orders (form ID SAL_SaleOrder), pass FormId, FieldKeys, FilterString, OrderString, StartRow and Limit. Key traps: reference fields need the Fxxx.FNumber suffix to return business codes instead of internal IDs; the response is a headerless 2D array whose columns follow FieldKeys order; FilterString is SQL-style, so mind injection and date formats; and always page with StartRow + Limit (recommend no more than 2000 rows per call).

Step 3: Save

The Save payload wraps a Model that mirrors the bill's BOS structure, with entries as arrays. Set NumberSearch: true so reference fields match by FNumber — the standard for integration scenarios. Save does not audit; follow up with Submit and Audit when required. For idempotency, store the external bill number in a custom header field, query by it first, and branch to update logic when a record exists.

Stability Recommendations

Wrap login/query/write in a retrying client for transient failures; pull increments by FModifyDate with windows matched to the schedule; parse Result.ResponseStatus on write failures and log Kingdee's business error verbatim; and keep sanitized request/response payloads — they are your strongest evidence when reconciling with Kingdee consultants.