Designing useful events for equipment integration

A practical starting point for connecting return equipment to an operator system.

Name the event precisely

Distinguish a visitor starting a session, recognition, physical acceptance, rejection and collection. Each event needs a device identity, time, unique ID and clear state. A recognition event alone should never create a reward or confirmed material record.

Expect imperfect networks

Agree retry, deduplication and offline replay behavior. Test a repeated event, delayed arrival and lost acknowledgement. The receiving system needs an idempotency rule before it updates a ledger.

Close the ownership gap

Document which side owns the device, interface, user account and incident response. Put a compatibility matrix and acceptance examples next to the API documentation so both teams can test the same behavior.

Specify the event at the business boundary

An accepted event needs an unambiguous physical meaning; a recognition candidate is not equivalent. Include a stable ID, source device, event time, format decision and schema version. Document what the receiving service acknowledges, how it treats a duplicate and who investigates a permanently rejected message. Then test a timeout after the receiver has processed the event: that is the case most likely to produce a second credit if deduplication is missing.

Follow one return across the boundary

Choose a representative container and write down the order of events the equipment can actually emit. For each step, ask whether a receiving system needs it to make a decision or whether it is diagnostic context. The reward or deposit system may need only a verified acceptance and a stable identifier; an operations dashboard may also need rejection reasons and full-storage alerts. Sending every internal event to every system creates noise and makes ownership harder to explain.

Use a short example record in the interface contract, but mark it as a test fixture. It should show the event ID, device and site, physical state, event time, schema version and the intended acknowledgement. Name the system that owns any participant or account identifier; do not assume the equipment has or should store it.

Test the awkward ordering

Send the same event twice, send two events out of order and lose the acknowledgement after the receiver has processed a message. Confirm that the receiver’s state stays correct and that both teams can trace what happened. Then disconnect a test device, allow it to produce whatever events the approved configuration supports, and check replay after reconnection. Record which conditions pause acceptance rather than guessing that every workflow continues offline.

The final handover should include the schema, compatibility versions, sample payloads, retry policy, monitoring owner and a procedure for a permanently failed message. An API endpoint alone does not make a return programme operable.

Bring an existing API specification or sample event and the responsible system owners to an integration discussion. The offline recovery guide covers replay and queue behavior in more depth.