External Sync

Alguna’s External Sync enables bidirectional synchronization between Alguna and external systems like CRMs, ERPs, and accounting software. Keep your data in sync automatically with conflict detection and resolution.

How It Works

Supported Systems

System	Entities	Direction
Salesforce	Accounts, Contacts, Opportunities	Bidirectional
HubSpot	Companies, Contacts, Deals	Bidirectional
QuickBooks	Customers, Invoices, Payments	Bidirectional
NetSuite	Customers, Invoices, Payments	Bidirectional
Xero	Contacts, Invoices, Payments	Bidirectional

Configuration

Enable Sync

curl -X POST https://api.alguna.io/integrations/salesforce/sync-config \
  -H "Authorization: Bearer $ALGUNA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "enabled": true,
    "direction": "bidirectional",
    "entities": ["accounts", "contacts", "subscriptions"],
    "conflictResolution": "alguna_wins",
    "schedule": "*/15 * * * *"
  }'

Sync Direction Options

Direction	Description
`alguna_to_external`	Push Alguna changes to external
`external_to_alguna`	Pull external changes to Alguna
`bidirectional`	Sync both ways

Field Mapping

Map fields between systems:

await alguna.syncConfig.setFieldMappings({
  integrationId: 'int_salesforce',
  entity: 'accounts',
  mappings: [
    {
      algunaField: 'name',
      externalField: 'Name',
      direction: 'bidirectional',
    },
    {
      algunaField: 'email',
      externalField: 'Email__c',
      direction: 'bidirectional',
    },
    {
      algunaField: 'billingAddress.line1',
      externalField: 'BillingStreet',
      direction: 'alguna_to_external',
    },
    {
      algunaField: 'mrr',
      externalField: 'MRR__c',
      direction: 'alguna_to_external',
      transform: 'number_to_currency',
    },
  ],
});

Transform Functions

Transform	Description
`none`	Pass through as-is
`number_to_currency`	Format as currency
`date_to_iso`	Convert to ISO format
`boolean_to_string`	Convert true/false to Yes/No
`custom`	Use custom JavaScript function

Conflict Resolution

When the same record is modified in both systems:

Resolution Strategies

Strategy	Description
`alguna_wins`	Alguna data takes precedence
`external_wins`	External data takes precedence
`latest_wins`	Most recent modification wins
`manual`	Flag for manual review

Per-Field Resolution

await alguna.syncConfig.setConflictResolution({
  integrationId: 'int_salesforce',
  entity: 'accounts',
  default: 'latest_wins',
  perField: {
    'name': 'external_wins', // CRM is source of truth for names
    'email': 'manual', // Review email conflicts
    'mrr': 'alguna_wins', // Billing is source of truth for MRR
  },
});

Sync Triggers

Scheduled Sync

Run sync on a schedule:

{
  "schedule": "*/15 * * * *",
  "description": "Every 15 minutes"
}

Real-Time Sync

Trigger sync on changes:

{
  "triggers": {
    "onAlgunaChange": true,
    "onWebhook": true,
    "webhookUrl": "https://api.alguna.io/integrations/sync/trigger"
  }
}

Manual Sync

curl -X POST https://api.alguna.io/integrations/salesforce/sync/trigger \
  -H "Authorization: Bearer $ALGUNA_API_KEY" \
  -d '{
    "entities": ["accounts"],
    "fullSync": false
  }'

Sync Status

Check Sync State

curl https://api.alguna.io/integrations/salesforce/sync/status \
  -H "Authorization: Bearer $ALGUNA_API_KEY"

Response:

{
  "integrationId": "int_salesforce",
  "lastSync": "2024-01-20T10:15:00Z",
  "status": "healthy",
  "stats": {
    "accounts": {
      "synced": 1250,
      "created": 5,
      "updated": 23,
      "conflicts": 2,
      "errors": 0
    },
    "contacts": {
      "synced": 3400,
      "created": 12,
      "updated": 45,
      "conflicts": 0,
      "errors": 1
    }
  },
  "nextScheduledSync": "2024-01-20T10:30:00Z"
}

View Sync History

curl https://api.alguna.io/integrations/salesforce/sync/history \
  -H "Authorization: Bearer $ALGUNA_API_KEY" \
  -d '{"limit": 10}'

Handling Errors

Error Types

Error	Description	Resolution
`field_validation`	External system rejected field value	Check field mapping
`rate_limit`	External API rate limited	Automatic retry
`auth_expired`	Authentication expired	Reconnect integration
`not_found`	Record doesn’t exist	Skip or create

Error Webhooks

app.post('/webhooks/alguna', (req, res) => {
  const event = req.body;

  if (event.type === 'sync.error') {
    console.error('Sync error:', event.data);
    // Alert team, create ticket, etc.
  }

  res.sendStatus(200);
});

Retry Failed Syncs

curl -X POST https://api.alguna.io/integrations/salesforce/sync/retry \
  -H "Authorization: Bearer $ALGUNA_API_KEY" \
  -d '{
    "recordIds": ["acc_123", "acc_456"]
  }'

Entity Matching

By External ID

Link records using external IDs:

await alguna.accounts.create({
  name: 'Acme Corp',
  externalId: 'salesforce:001ABC123', // Salesforce Account ID
});

By Email/Name

Configure matching rules:

{
  "matching": {
    "accounts": {
      "fields": ["email", "name"],
      "strategy": "exact", // or "fuzzy"
      "createIfNotFound": true
    }
  }
}

Salesforce Example

Complete Setup

// 1. Connect Salesforce
const integration = await alguna.integrations.connect({
  provider: 'salesforce',
  credentials: {
    // OAuth flow handles this
  },
});

// 2. Configure sync
await alguna.syncConfig.create({
  integrationId: integration.id,
  entities: {
    accounts: {
      enabled: true,
      externalObject: 'Account',
      direction: 'bidirectional',
      mappings: [
        { alguna: 'name', external: 'Name' },
        { alguna: 'email', external: 'Email__c' },
        { alguna: 'mrr', external: 'MRR__c' },
      ],
    },
    subscriptions: {
      enabled: true,
      externalObject: 'Opportunity',
      direction: 'alguna_to_external',
      mappings: [
        { alguna: 'planId', external: 'Product__c' },
        { alguna: 'status', external: 'Stage' },
        { alguna: 'currentVersion.mrr', external: 'Amount' },
      ],
    },
  },
  schedule: '*/15 * * * *',
});

// 3. Run initial sync
await alguna.integrations.sync.trigger(integration.id, {
  fullSync: true,
});

Best Practices

Start One-Way

Begin with one-way sync, then enable bidirectional once stable.

Monitor Conflicts

Review conflicts regularly to tune resolution strategies.

Test in Sandbox

Test sync configuration in sandbox environments first.

Map Carefully

Document field mappings and transformation logic.

Webhooks

Event	Description
`sync.completed`	Sync job finished
`sync.error`	Sync encountered errors
`sync.conflict`	Conflict detected (if manual resolution)

Integrations

Accounting

CRMs

Data Ingestion

Payments

Sales Tax

Invoicing Alternatives

​External Sync

​How It Works

​Supported Systems

​Configuration

​Enable Sync

​Sync Direction Options

​Field Mapping

​Transform Functions

​Conflict Resolution

​Resolution Strategies

​Per-Field Resolution

​Sync Triggers

​Scheduled Sync

​Real-Time Sync

​Manual Sync

​Sync Status

​Check Sync State

​View Sync History

​Handling Errors

​Error Types

​Error Webhooks

​Retry Failed Syncs

​Entity Matching

​By External ID

​By Email/Name

​Salesforce Example

​Complete Setup

​Best Practices