Define business meaning before mapping fields
A common integration mistake is to map every field named date or amount directly between systems. A value such as 2026-10-27 09:00 might mean Taipei local time, UTC, the browser's time zone, or a wall-clock schedule with no universal instant. Likewise, 1000 might be TWD, USD, a tax-inclusive price, a net amount, or a reporting value already converted using a particular exchange rate. Matching field names do not guarantee matching semantics.
Create a data contract for each field before implementing the transformation. Document its business definition, source format, time zone or currency, precision, null behavior, and failure policy. System owners and business users should approve these definitions together. Code alone cannot determine whether an order date means creation, payment, fulfillment, or accounting recognition.
- Time fields: distinguish event instants, calendar dates, and local recurring schedules.
- Money fields: carry the numeric value, ISO currency code, tax meaning, and precision.
- Conversion evidence: record the time zone, rate source, effective date, and rounding rule.
- Source evidence: retain the original value and source system for replay and audit.
Treat instants differently from calendar dates
Values representing real events, such as payment completion, an API request, or an equipment alarm, should normally be normalized to UTC at the integration boundary. Exchange them in an ISO 8601 representation that includes Z or an explicit offset. Store the UTC instant and convert it for display using the user's or operating site's time zone. Do not store everything as Taiwan time or assume every participating system uses UTC+8; overseas operations, cloud platforms, and third-party SaaS products quickly invalidate that assumption.
Birthdays, invoice dates, accounting periods, and contract expiration dates are usually calendar values rather than instants. Forcing them through a midnight UTC conversion can make another region display the previous day. A schedule such as every day at 09:00 is different again: store the local time together with an IANA zone such as Asia/Taipei. A fixed offset cannot represent historical and future daylight-saving rules in regions that observe them.
- Input policy: reject ambiguous event timestamps that contain neither an offset nor a declared source zone.
- Parsing: allow documented formats only; never let the runtime guess whether a numeric date is month-first or day-first.
- Daylight saving: define what happens when a local time is missing or occurs twice: reject it, shift it, or select a documented offset.
- Clock discipline: synchronize server clocks, but never substitute ingestion time for the source event time.
Make currency conversion reproducible
Represent money with a decimal type or an integer count of minor units, not binary floating point. The base record should contain the original amount and currency code. When a converted value is created, also retain the target currency, applied rate, rate timestamp or business date, provider, and rule version. Historical invoices and reports can then be reproduced even after the rate service publishes newer data.
Rate selection is a business policy rather than a technical convenience. A payment service may use the transaction-time rate, an ERP may use the posting-date or month-end rate, and management reporting may use a fixed budget rate. The integration layer should not apply the latest available rate to every use case. Rounding must also be explicit: rounding each line, the tax subtotal, the order total, or the final ledger entry can produce different results. Any method may be valid in the right context, but mixing them prevents reliable reconciliation.
- Precision: keep sufficient precision during intermediate calculations and round only at an agreed business boundary.
- Currency metadata: do not assume every currency has two decimal places; drive scale rules from maintained metadata.
- Refunds and credits: decide whether to reuse the original rate, apply the refund-date rate, or let finance recognize an exchange difference.
- Missing rates: block processing, queue the item for review, or apply an approved fallback with a visible warning.
Design for validation, traceability, and replay
Keep normalization at a clearly owned integration boundary instead of reimplementing it independently in the UI, API, ETL pipeline, and reports. Use versioned conversion functions and test month-end, year-end, daylight-saving transitions, leap days, negative values, unusually large amounts, nulls, and unsupported currencies. In addition to unit tests, run contract tests with representative examples approved by both source and destination system owners.
Production records should expose the source value, normalized value, rule version, and processing time, while allowing messages to be replayed idempotently. Monitoring should cover more than HTTP success: track unparseable dates, unknown zones, missing currency codes, stale rates, and reconciliation differences. When a legacy system supplies ambiguous data, marking its quality and routing it to an exception workflow is safer than silently guessing. A dependable integration is not one that forces every input to succeed; it is one where every conversion has a clear, testable, and auditable basis.