Integrations¶

SCOPE_ITEM: Connectivity layer for internal tools that need to read from or write to external business systems (ERP, CRM, productivity suites, email, calendar, file storage).

Architecture Pattern¶

┌─────────────┐     ┌──────────────────┐     ┌─────────────────┐
│  Internal    │────▶│  Integration     │────▶│  External       │
│  Tool (UI)   │     │  Service Layer   │     │  System API     │
└─────────────┘     │  ┌────────────┐  │     └─────────────────┘
                    │  │ Transform  │  │
                    │  │ + Cache    │  │
                    │  │ + Retry    │  │
                    │  └────────────┘  │
                    └──────────────────┘

INCLUDES: - Integration service layer (Hono API routes, server-side only). - Credential storage in environment variables or Vault. - Request/response logging for debugging. - Error handling with user-friendly messages. - Retry logic with exponential backoff (3 attempts).

CHECK: Integration credentials must NEVER be exposed to the frontend. CHECK: All external API calls must have a timeout (default: 30 seconds). CHECK: All integrations must be feature-flagged (enable/disable per client).

ERP Integration¶

Exact Online (Netherlands / Belgium)¶

SCOPE_ITEM: Integration with Exact Online REST API.

INCLUDES: - OAuth 2.0 authentication (authorization code flow). - Token refresh handling (access tokens expire in 10 minutes). - Division ID resolution (multi-division support). - Read operations: contacts, invoices, items, financial transactions, chart of accounts, cost centres. - Pagination handling (Exact uses $skiptoken, not standard OData $skip). - Rate limit compliance (60 requests/minute per division).

OPTIONAL: - Write-back: create invoices, update contacts. - Webhook receiver for Exact Online push notifications. - Bi-directional sync with conflict resolution. - Bulk data import (initial data load).

CHECK: Exact Online REST API does NOT support $expand — related entities require separate requests. Budget for N+1 query patterns. CHECK: Division ID is required for every request — store per-tenant in configuration, not hardcoded. CHECK: Payment matching has NO REST API endpoint — only possible via XML file upload in the Exact Online web interface. CHECK: Use REST API for all new integrations. XML API only for edge cases not covered by REST (e.g., reconciliation).

SAP (S/4HANA, Business One)¶

SCOPE_ITEM: Integration with SAP systems via OData or REST.

INCLUDES: - OData v2/v4 service consumption (SAP Gateway). - Authentication: Basic Auth, OAuth 2.0, or X.509 certificates. - Read operations: master data, financial postings, inventory. - Pagination, filtering, field selection ($select, $filter). - Error handling for SAP-specific error formats.

OPTIONAL: - Write-back via OData or BAPI/RFC (for transactional operations). - IDoc-based async integration for high-volume document exchange. - Real-time eventing via SAP Event Mesh. - Middleware layer (SAP Integration Suite, MuleSoft, or custom).

CHECK: Prefer asynchronous patterns for high-volume SAP operations. Synchronous RFC/BAPI calls cause locks and timeouts under load. CHECK: SAP environments vary enormously — always confirm exact system version and available OData services during scoping. CHECK: SAP connectivity often requires VPN or private network peering. Budget for infrastructure setup.

Microsoft Dynamics 365¶

SCOPE_ITEM: Integration with Dynamics 365 via Dataverse Web API.

INCLUDES: - OAuth 2.0 authentication via Azure AD (same tenant as SSO). - Dataverse Web API (OData v4) for CRUD operations. - Read operations: accounts, contacts, opportunities, invoices. - Change tracking (odata.track-changes) for incremental sync.

OPTIONAL: - Write-back operations. - Webhook registration for real-time event notification. - Power Automate integration (trigger flows from internal tool).

CRM Integration¶

Salesforce¶

SCOPE_ITEM: Integration with Salesforce REST API.

INCLUDES: - OAuth 2.0 (Web Server Flow or JWT Bearer Flow). - REST API: SOQL queries, record CRUD, describe calls. - Read operations: accounts, contacts, opportunities, tasks. - Bulk API for large data volumes (>10k records). - Rate limit compliance (API call limits per 24h rolling window).

OPTIONAL: - Write-back: create/update records, log activities. - Streaming API (push notifications on record changes). - Metadata API for custom object discovery. - Sandbox vs production environment switching.

CHECK: Salesforce API limits vary by edition — confirm with client. CHECK: Custom fields are common — attribute mapping must be configurable.

HubSpot¶

SCOPE_ITEM: Integration with HubSpot CRM API.

INCLUDES: - OAuth 2.0 or private app token authentication. - CRM API v3: contacts, companies, deals, tickets. - Search API for filtered queries. - Associations API for relationship traversal. - Rate limit compliance (100 requests/10 seconds for OAuth apps).

OPTIONAL: - Write-back: create/update records, log activities. - Webhook subscriptions for real-time updates. - Custom object support. - HubSpot Forms API integration.

Pipedrive¶

SCOPE_ITEM: Integration with Pipedrive REST API.

INCLUDES: - API token or OAuth 2.0 authentication. - Read operations: persons, organisations, deals, activities. - Pagination (cursor-based). - Webhook subscriptions for change notifications.

OPTIONAL: - Write-back operations. - Custom field mapping.

Office 365 Integration¶

SCOPE_ITEM: Integration with Microsoft 365 services via Microsoft Graph API.

Microsoft Graph API¶

INCLUDES: - OAuth 2.0 via Microsoft Entra ID (same registration as SSO). - Delegated permissions (act on behalf of signed-in user). - Application permissions (background sync, no user context).

Email (Outlook)¶

SCOPE_ITEM: Send transactional email via Microsoft Graph.

INCLUDES: - Send email on behalf of shared mailbox or service account. - Email template rendering (MJML or React Email). - Delivery status tracking.

OPTIONAL: - Email-to-record ingestion (poll shared mailbox, parse, create records). - Attachment handling (save to file storage, link to record).

CHECK: Sending email via Graph requires Mail.Send permission. CHECK: Shared mailbox sending requires Mail.Send.Shared or application permission with mail-enabled security group.

Calendar (Outlook)¶

OPTIONAL: SCOPE_ITEM: Calendar read/write via Microsoft Graph.

INCLUDES: - Read user availability (free/busy lookup). - Create calendar events (meeting invitations). - Room/resource booking (if Exchange rooms configured).

OneDrive / SharePoint¶

OPTIONAL: SCOPE_ITEM: File storage integration via Microsoft Graph.

INCLUDES: - Browse SharePoint document libraries. - Upload/download files to/from SharePoint. - Direct link generation for file sharing.

Google Workspace Integration¶

SCOPE_ITEM: Integration with Google Workspace APIs.

Gmail¶

OPTIONAL: SCOPE_ITEM: Send email via Gmail API.

INCLUDES: - OAuth 2.0 (same credentials as OIDC SSO). - Send email on behalf of service account (domain-wide delegation). - Email template rendering.

CHECK: Domain-wide delegation requires Google Workspace admin approval.

Google Calendar¶

OPTIONAL: SCOPE_ITEM: Calendar integration via Google Calendar API.

INCLUDES: - Read user availability (freebusy query). - Create calendar events. - Service account access for shared calendars.

Google Drive¶

OPTIONAL: SCOPE_ITEM: File storage via Google Drive API.

INCLUDES: - Shared Drive access (team drives). - File upload/download. - Permission management.

File Storage Integration¶

SCOPE_ITEM: S3-compatible object storage for file management.

INCLUDES: - EU-hosted S3-compatible storage (AWS S3 eu-west-1, or Scaleway/OVH for EU-only requirement). - Presigned URLs for secure upload/download (15-minute expiry). - Virus scanning on upload (ClamAV or VirusTotal API). - File type validation (whitelist allowed MIME types). - Storage quota per tenant.

CHECK: Files must be stored in EU region (GDPR Article 44). CHECK: Presigned URLs must be short-lived (15 minutes max). CHECK: Virus scanning must complete before file is accessible.

Sync Patterns¶

One-Way Read (Simplest)¶

SCOPE_ITEM: Read reference data from external system.

INCLUDES: - Scheduled sync (BullMQ repeatable job, e.g., every 15 minutes). - Incremental sync (last-modified timestamp or change tracking). - Full sync fallback (weekly reconciliation). - Sync status dashboard (last run, records synced, errors).

Bi-Directional Sync¶

OPTIONAL: SCOPE_ITEM: Read and write data to external system.

INCLUDES: - Conflict resolution strategy (last-write-wins or manual resolution). - Sync direction per field (some fields master in tool, others in ERP). - Sync queue with retry (failed operations retried with backoff). - Sync audit log (every sync action recorded).

CHECK: Bi-directional sync is significantly more complex than one-way. Confirm with client that write-back is truly needed before committing.

Event-Driven (Real-Time)¶

OPTIONAL: SCOPE_ITEM: React to external system changes in real-time.

INCLUDES: - Webhook receiver endpoint (verified, idempotent). - Event processing queue (BullMQ, deduplicated by event ID). - Fallback polling for missed webhooks (reconciliation job).

CHECK: Webhook endpoints must validate signatures (HMAC). CHECK: Webhook processing must be idempotent (same event processed safely multiple times).

Error Handling¶

INCLUDES: - Retry with exponential backoff (1s, 4s, 16s — 3 attempts max). - Circuit breaker (disable integration after 5 consecutive failures, auto-retry after 5 minutes). - User-facing error messages (not raw API errors). - Integration health status visible in admin panel. - Alert on repeated failures (email to admin after 10 failures/hour).

CHECK: Never expose external API error details to end users. CHECK: Never log full request/response bodies (may contain PII). Log: endpoint, status code, error code, request duration.

Scoping Questions¶

CHECK: Which external systems does the client use? (ERP, CRM, email, calendar) CHECK: Is the integration read-only or bi-directional? CHECK: What data entities need to be synchronised? CHECK: What is the acceptable sync latency (real-time, 15 min, daily)? CHECK: Does the client have API access / licences for the external system? CHECK: Are there VPN or network restrictions for on-premises systems? CHECK: Who manages the external system credentials? (client IT vs GE) CHECK: What is the data volume (records per sync, events per day)?