06 · Development · Write-back
Kingdee showed two identical drafts
The integration engineer guarantees write-back posts only once. If a retry uses a new document number, the outside system will honestly record two. Local stock transactions are not his.
| Case | Local | External |
|---|---|---|
| Not yet sent | Pending write-back | No document |
| Timeout, result unknown | Stay pending write-back, query with original idempotency key | If present, accept it; if not, resend the same key |
| Clear success | Record the external document number | One draft |
| Clear reject | Pending human, stop auto-retry | Do not keep stacking drafts |
The integration engineer matches fields, and also matches “post once”
The solution stated keep and write. The integration engineer turns write into a sync that can be run again: field mapping, direction, idempotency key, failure class. The job’s mark is not treating timeout as failure and immediately creating a new one. Timeout means you do not know whether the other side recorded it. Insert again, and you get two drafts. He uses the business document number or a dedicated idempotency key as the unique key of the external document. If the other side returns already exists, bind the existing number. Do not error out and let a person re-enter.
The mapping table must state who is master for master data. When item codes follow Kingdee, a code missing locally fails immediately. It is not created on the fly in the integration layer. On-the-fly create bypasses the data steward. Precision and nulls for amount, tax rate, and warehouse code must also be written. If an empty warehouse maps to a default main warehouse, goods go to the wrong place and the interface looks successful.
People and the queue
Auto-retry is only for unknown result and the other side temporarily unavailable. A business reject, for example the period already closed or the item deactivated, enters the human queue, notifies finance, and stops retry. After human handling, continue with the same idempotency key. Do not start another document. The integration engineer provides a query page: local document number, external document number, last error text, retry count. Without this page, implementation can only query the database.
How duplicate drafts appeared
Completion-to-stock write-back to Kingdee. The first request timed out. The task was marked failed and immediately resent with a new number. Kingdee actually accepted both drafts. Finance nearly approved one of them. The integration engineer changed it: timeout does not change the number. Query by idempotency key first. If found, bind. If not found, send the same key. Already-created duplicate drafts were listed. Finance voided one. Local bound the one that remained. Period-close errors no longer retry.
After that, he tested once with a pulled cable and once with a period-closed item. Both behaviors must match the two rows in the table before integration is delivered. When the other side’s API upgrades, the integration engineer first runs one completion-to-stock and one timeout retry on staging. A missing field must fail obviously. A missing tax rate cannot be treated as zero. Once a zero-tax draft is approved, it is a wrong voucher. If the other side’s success is only acceptance, it does not mean a draft was created. He must separate the acceptance number from the business document number. Bind waits for the business document number. Treating the acceptance number as the business document number, finance will not find that document in Kingdee. Before the first write-back each day, he looks at the age of the oldest item in the queue and the last clearly successful document number. If age suddenly grows, stop auto-retry first and check whether the other side closed the period or the network dropped. Letting the queue blindly resend will only pile up acceptance numbers.
After recovery, confirm one by one under the original idempotency key. Confirm one, bind one. Until the bind exists, local must not change state to written-back. State first, bind later, and finance will find no complete evidence on either side.
Mapping changes also go through versions. When finance moved the tax-rate field, the integration engineer first compared one completion document on staging, confirmed the draft tax amount, then switched production. Changing mapping directly in production would write wrong tax into every write-back that night. Once a wrong-tax draft is approved, it can only be reversed with a red-ink voucher. Calling the API again will not cover it.