CRM-ERP-Integration

CRM/ERP Integrations

When to Use

Use when integrating an application with external CRM or ERP systems, designing data synchronization pipelines, handling webhooks/polling, or resolving cross-system sync conflicts.

1. Explicit System-of-Record (Data Owner) Per Entity & Field

Never build a "bidirectional sync" without defining which system owns the truth for each entity and field (Gregor Hohpe's integration discipline):

• Document an explicit Ownership & Survivorship Matrix:
  • Example: CRM owns Lead, Opportunity, Activity, and front-office Account contact details; ERP owns Product SKU, Inventory Available, Tax ID, Credit Limit, Confirmed SalesOrder, Fulfillment, and Invoice Status.
• Never allow an incoming sync from a non-authoritative system to overwrite local authoritative edits silently.

2. Anti-Corruption Layer (ACL) & External ID Mapping

Different CRM/ERP providers use incompatible domain models (e.g., HubSpot Deal + Company associations vs. Salesforce Opportunity + Account vs. Odoo res.partner unifying companies and contacts):

• Never Leak External Provider Schemas into Core Domain Tables:
  • Translate provider payloads through an isolated Adapter / Anti-Corruption Layer.
• Dedicated External Identity Mapping Table (external_entity_mappings):
  • Store (tenant_id, integration_id, entity_type, internal_id, external_id, external_version_or_etag, last_synced_at, sync_hash).
  • Enforce UNIQUE (tenant_id, integration_id, entity_type, external_id) so retried webhooks or polling runs never create duplicate internal records.

3. Idempotent Sync, Loop Prevention & Conflict Resolution

• Echo / Sync-Loop Prevention:
  • In bidirectional syncs, when System A receives an update from System B, do not re-emit that change back to System B! Compare content hashes (sync_hash), origin markers (source_system), or updated_at / version vectors before enqueueing outbound sync jobs.
• Ordering & Out-of-Order Webhook Protection:
  • External webhooks (deal.updated) often arrive out of order or before deal.created finishes processing. Compare upstream updated_at / revision numbers before applying updates, and handle missing parent references via dependency-ordered retry queues or lazy fetch.
• Rate Limits, Bulk APIs & Dead-Letter Visibility:
  • Respect provider API quotas (Salesforce daily API limits, HubSpot burst limits, ERP SOAP/REST throttling) using batched/bulk endpoints and exponential backoff.
  • Record failed sync items in a visible, replayable Sync Error Queue with actionable business error messages (e.g., "Order #108 sync failed: Customer Tax ID missing in ERP").