Editorial draft available to read. Factual and language review is pending. Examples are illustrative.
Decision and scope
Integration documentation should let another team implement and operate the exchange without hidden verbal knowledge. Include business objects, field definitions, authentication, permission scope, examples, error handling and operating limits. Identify the contract version, its owner and the process for communicating a future breaking change.
Illustrative example
Illustrative example: another team submits requests with a unique external reference. The guide shows a valid request, a rejected request and the result of submitting the same request again. It explains which acknowledgement means merely received and which confirms that the business change was actually applied.
Acceptance check
Ask someone outside the implementation team to follow the example in a separate environment. Correct implicit steps and differences between the document and observed behavior. Accept the guide when the receiving team can test success, failure and recovery using the written instructions.
Key takeaways
- Accept the guide when the receiving team can test success, failure and recovery using the written instructions.