Reimbursement system integration with Kingdee Cloud Galaxy: voucher push fields and common errors
The difficulty of connection has never been how to call the API, but rather How to transfer supplementary accounting dimensions and how to validate accounting period status— These two areas are the main sources of errors. The interface itself has standard documentation; just write according to it. What really takes time is aligning the expense control side's department, project, and employee codes with Kingdee's master data.
Required fields for voucher push
| Field | Description | Note |
|---|---|---|
| Account Books | Target ledger identifier | Multiple organizations need to be mapped by company entity |
| Voucher word | Bookkeeping vouchers / payment vouchers, etc. | Who generates it must be agreed in advance |
| Voucher date | Bookkeeping date | Determines which accounting period it falls into |
| Summary | Entry line summary | Note the length limit on the Kingdee side |
| Account code | It must be a leaf-level account | Parent account will be rejected |
| Debit-Credit Direction and Amount | Total debits and credits must be equal | |
| Supplementary accounting | Department / Project / Employee / Customer / Supplier | The dimensions required by the account must be complete |
| Source document number | Reimbursement form number | Used for traceability and idempotency duplicate checking |
Supplementary accounting is the most easily stuck step
Kingdee's accounts can be linked to multiple accounting dimensions, and Different accounts require different dimensions. Management expenses may only require a department, R&D expenditure also requires a project, and other payables require an employee.
If the expense control side does not know which dimensions each account requires, it can only transmit all or none—the former may transmit dimensions the account does not accept, while the latter will be rejected due to missing dimensions.
The correct approach is Maintain the required_dims field in the account master data on the expense control side, when vouchers are generated, they are filled and verified according to account requirements, and anything missing is reported at the draft stage.
What to do if the codes do not match
Department codes in the expense control system may not match those in Kingdee basic data, especially when expense control uses the organizational structure from OA or HR.
At this time, one is needed Code conversion comparison table: Expense control side code → Kingdee side code. This mapping table must be established and maintained during the implementation phase; do not expect the codes on both sides to be naturally consistent.
One question that must be clarified during the research phase is: whether the coding of dimension values is consistent on both sides, and whether a conversion table is needed if not.
Five common error types
| Error phenomenon | Reason | Processing |
|---|---|---|
| Account does not exist or has been deactivated | The general ledger deactivated an account, but the expense control rules were not synchronized | Periodically sync account master data; deactivated accounts are marked invalid in rules |
| Accounting period closed | The target period has been closed | Verify accounting period status before generation, intercept at the draft stage |
| Missing required auxiliary accounting dimensions | Account requires a project/cost center, but the document did not provide one | Account master data configures required_dims, validated before generation |
| Non-leaf accounts are not allowed for bookkeeping | The rule points to a parent account | Account master data is marked is_leaf, and configuration is restricted to selecting only leaf-level accounts |
| Debit-Credit Imbalance | Incorrect algorithm for amount excluding tax | Tax amount is taken from the invoice value; tax-exclusive amount is derived by subtraction |
Among these five, the first four should all Blocked before push. Waiting for Kingdee to return an error code before troubleshooting means finance sees technical information and neither knows which document has the problem nor how to fix it.
Idempotency: the same document cannot generate two vouchers
API timeouts, network jitter, and manual retries can all cause the same reimbursement form to be pushed multiple times.A unique index must be established at the database level, use "reimbursement form number + business type" as the unique key, rather than relying only on application-layer judgment—application-layer judgment fails under concurrency.
The state machine for failure retries
| Status | Meaning | Executable actions |
|---|---|---|
| Draft | Generated, validation passed, not pushed | Edit / Push / Void |
| Pushing | Interface called, waiting for return | Locked to prevent duplicate push |
| Success | The general ledger has received it and returned the voucher number | View / Reverse Invoice |
| Failed | Push rejected, reason recorded | Retry after correction / Void |
Failure reasons must be fully recorded and presented to finance in a readable way, rather than storing only an error code.
Use red-flushing for voiding, do not delete
When a reimbursement form is voided or returned, a red-letter voucher should be generated to reverse it, while the original voucher is retained. There are two reasons: the integrity requirements of accounting archives, and the fact that general ledger systems typically do not allow deletion of posted vouchers.
How is this scenario handled in Kailing Technology's expense control system?
Account master data maintenance requires auxiliary accounting dimensions. Before voucher generation, four checks are completed: leaf-level account, complete dimensions, debit-credit balance, and accounting period status, exposing problems at the draft stage. Supports code conversion mapping between the expense control side and the general ledger side. A database unique index is established based on reimbursement order number plus business type to ensure idempotency. The push state machine fully records failure reasons and supports manual retry; voiding is handled via red-letter reversal.
Learn about the Kailing Technology expense control and reimbursement system →
Common Questions
Supplementary accounting dimension transfer and accounting period validation. The interface itself is not difficult; the difficulty lies in aligning the base data codes on both sides.
Establish a code conversion cross-reference table, maintained during the implementation phase. Do not assume the codes on both sides are naturally consistent.
Create a unique index at the database layer using the reimbursement number plus business type; relying only on application-layer checks will fail under concurrency.
Generate a red-letter voucher to reverse the entry, while retaining the original voucher. The general ledger usually does not allow deletion of posted vouchers, and accounting archives require completeness.