API integration for business systems: what to agree before development

Start with a single data flow

Say you want an order from your web shop to arrive in the ERP. The work also involves answers to less visible questions: is the customer already on file, may the address be changed, and would a retry create a second order? Those rules are what belong in the proposal.

Instead of a request to “connect everything”, describe one event from start to final check. That could be a confirmed order, a contact change or the completion of a work order.

For the initial scope, answer:

• Where does the record originate, and at what point is it ready to transfer?
• Which data moves, and in which direction?
• Does the other system only receive a record, or must it return a confirmation and an identifier?
• How much delay is acceptable for the business?
• Who acts if the transfer cannot be completed?

Orders and stock do not have to update at the same pace. If you define an acceptable delay for each flow, the vendor can check whether the existing interface meets it. “Real time” without that agreement leaves too much room for different expectations.

Which system is the source of truth for each field?

Decide where a value may be changed and which version applies when systems disagree. One system does not have to be the master for everything: the CRM can own the sales contact, the ERP the item code and the web shop the product display content.

Microsoft's pattern for connecting different data models explains why meanings and structures get translated between systems. For a business agreement, a field table is enough to start; a separate, complex layer of infrastructure is not automatically required.

The table below is an illustrative agreement for an imaginary web shop and ERP, not a description of a Novero integration that has been built.

For every field, check the format, whether it is required, the unit and the allowed values. “Unit” and “case”, a blank field and zero, or a date and a timestamp can carry different business meanings. The rule for an unknown value should be written down before the first import.

Do you have access to the operations you actually need?

Before any estimate, ask for current documentation, a test environment and confirmation of the available operations. Being able to read customers does not mean the API allows creating or changing them. Check whether access depends on a plan, the supplier's approval or extra configuration.

The checklist should cover the interface version, call limits, sign-in method, required fields and available statuses. If a ready-made connector covers the actions you need, compare it with custom development before ordering new work.

Permissions are a separate check. OWASP warns that access to a specific record and action must be verified. In testing, check that a user or integration account cannot retrieve someone else's data by changing an identifier.

Agree who issues and renews access credentials. Do not put live secrets or unnecessary personal data into request examples and support records.

What happens after a timeout or a repeated message?

Consider this scenario: the ERP saves the order, but the response never reaches the shop. The shop now does not know whether the submission succeeded. Blindly creating the order again can produce a duplicate.

Microsoft's guidance on retrying requests distinguishes transient difficulties from other errors and warns about repeating an action that has already run. Automatic retries should therefore be agreed according to the behaviour of the specific API.

Idempotency depends on the interface contract

An idempotent action should not produce a second identical business effect when it is repeated. One way to support this is a key the server uses to recognise a repeated request.

Stripe documents the use of idempotency keys, along with differences between its API versions. That is a concrete example, not a property you can assume for every ERP. Check whether the supplier supports a key, how long it is remembered and what happens after data changes or a partial success.

If no such support exists, agree another verifiable way to establish the previous outcome before repeating an action. When the outcome cannot be confirmed safely, flag the case for a check. Do not present uncertainty as a successful transfer.

Event notifications also need processing

A webhook is a notification one system sends to another after an event. Receiving it does not remove the need to verify the sender, handle repeated messages and manage the processing order.

For example, Stripe's webhook guidance describes signature verification, duplicates and the possibility of delivery out of the order in which events occurred. For your own integration, check what your supplier actually promises. Turn those terms into concrete tests and recovery rules.

How will you notice that a record is missing?

Error review should be part of the working process. For every unfinished transfer, agree a status, a responsible person and the next action. Retrying, manual correction and abandoning with a reason should each leave a trace others can understand.

Reconciliation means comparing expected records with the ones actually accepted. The total count of orders is not enough: the same overall number can hide both a missing record and a duplicate. Reconcile identifiers, agreed fields and final statuses.

Include at least these scenarios in your acceptance criteria:

1. The same message arrives again.
2. The destination performs the action, but the confirmation is lost.
3. One line contains an unknown code or a disallowed value.
4. Access expires, or the supplier temporarily rejects calls.
5. Part of the transfer succeeds while the rest needs intervention.

For each scenario, show where an employee sees the problem and how they continue the work. Failed or uncertain records should stay visible until they are resolved. Automatically deleting such items from a queue hides work that is not finished.

What should a proposal for an API integration specify?

The proposal should name the systems, flows and operations, the mapping rules, the tests, the rollout approach and who owns exceptions. Add the maintenance boundaries: changes to an existing API version, new features and third-party work are not the same line item.

For connecting existing systems, see the scope of business system integrations. If a whole process with user roles and approvals is missing between the systems, also assess custom business software. Keep the need for a new application separate from the data transfer itself.

For the first conversation, prepare the names and versions of the systems, a sample record without sensitive data and a description of the desired outcome. Send Novero what you want to connect so the assessment can cover available access, transfer verification and what happens when something gets stuck.

Sources

• Microsoft: anti-corruption layer pattern for different data models
• Microsoft: retry pattern
• OWASP API Security Top 10: broken object level authorization
• Stripe: idempotent requests
• Stripe: webhooks