The systems are named, but there is no description of their API and no statement of who will provide it
What it leads to. The contractor sets the price and timeline blind, based on assumptions about methods, formats and the authentication approach. After the contract is signed, it turns out that no documentation exists and the owner of the second system is under no obligation to provide it. Work stalls, the deadline slips, and the contract names no one as responsible.
How to write it right. Add a section called "Source data for integration": for each system, the version, the interface type, and a link to the current documentation or an appendix to the specification. State on a separate line who hands over access to the documentation and by when after the contract is signed, and what counts as a delay caused by the customer.
Behavior during an exchange failure is not described
What it leads to. A payment went through but is not reflected in the accounting records. A request was sent but no response came back. If the specification does not say what the system does in such cases, the contractor chooses on their own, and at acceptance the customer discovers that duplicates, lost records or silent failures are not acceptable to them. There is nothing to argue from: the requirement did not exist.
How to write it right. Describe failure scenarios explicitly: the other side being unavailable, a timeout, an error response, the same message being sent again. For each one, state what the system does: retries the request, puts it in a queue, flags the record, notifies someone responsible, and exactly whom. Separately, require protection against duplicates on retries.
The other side has no test environment, and this is not addressed anywhere
What it leads to. The integration has to be tested on the live system or not tested at all. In the first case, real data and payments are at risk; in the second, errors surface after launch. Acceptance testing formally passes against stubs, and real exchange happens for the first time on launch day.
How to write it right. In the specification, state which systems need a test environment, who provides it, and by when. If a party has no test environment, write down the alternative: an emulator, an agreed set of test data, or a testing window on the live system with its limitations described. Tie acceptance testing to that environment.
Responsibility for data at the junction between systems is not allocated
What it leads to. When the amount or status in one system differs from the other, each side considers the other's data to be wrong. The contractor says they passed on what they received. The owner of the source system says it is working normally. The customer is left without an answer as to who corrects the data and who is accountable for it.
How to write it right. Include a section on data ownership: for each exchanged object, which system is the source of truth, who is responsible for the quality of the source data, and who is responsible for transformation during transfer. Define the procedure for handling discrepancies: who records them, who fixes them, and within what time.
There is no requirement for an exchange log
What it leads to. A dispute about whether a message was sent, what it contained and what response came back cannot be resolved without records. Without a log, incident analysis turns into comparing participants' recollections, and claims against the contractor or the owner of the neighboring system remain unproven.
How to write it right. Require an exchange log as a separate clause: what is recorded (time, direction, operation identifier, status, error code), how long it is kept, who has access to view it, and how personal and payment data in the records are protected. State that the log serves as the basis for resolving disputes.
Acceptance is described in general terms: "the integration works"
What it leads to. Without verifiable criteria, the acceptance certificate can be left unsigned indefinitely or signed without anything substantial having been checked. Both sides end up in a position where any assessment of the result is subjective.
How to write it right. For each exchange scenario, draw up a list of checks: input data, expected result, testing environment. Include in acceptance the negative scenarios from the failure section and a check of the log. Formulate the condition for signing the certificate as passing these checks.