Link Integration

Integrate the Sync2Books Link component to connect accounting systems (QuickBooks, Xero, Sage) in your application.

Overview

The Sync2Books Link is a pre-built UI component that handles the OAuth flow for connecting accounting systems. It provides:

✅ Pre-built UI - No need to build OAuth flows yourself
✅ Multi-framework support - React, Vue, Angular, Svelte
✅ Customizable branding - Use your app's logo and name
✅ Automatic token management - Handles refresh and expiration

How Link Works

┌─────────────┐
│ Your App    │
│             │
│ [Connect    │
│  QuickBooks]│
└──────┬──────┘
       │
       │ 1. User clicks "Connect"
       ▼
┌─────────────────────┐
│ Sync2Books Link     │
│ Modal/Dialog        │
│                     │
│ Select Integration  │
│ [QuickBooks] [Xero] │
└──────┬──────────────┘
       │
       │ 2. User selects QuickBooks
       ▼
┌─────────────────────┐
│ OAuth Consent       │
│ (Opens in new tab)  │
└──────┬──────────────┘
       │
       │ 3. User authorizes
       ▼
┌─────────────────────┐
│ Connection Success │
│ Returns connectionId│
└─────────────────────┘

Prerequisites

✅ API Key - Your application's API key
✅ Application ID - Your application ID
✅ Company ID - The company/user ID in your system
✅ Redirect URIs - Configured in your application settings

React Integration

Installation

npm install @sync2books/react
# or
yarn add @sync2books/react

Basic Usage

import { useSync2Books } from '@sync2books/react';

function MyComponent() {
  const { openLink, isReady } = useSync2Books({
    companyId: 'your-company-id',
    applicationId: 'your-application-id',
    applicationName: 'Your App Name',
    apiKey: 'sk_live_your_api_key',
    integrationKey: 'quickbooks',
    onSuccess: (payload) => {
      console.log('Connected!', payload);
      // payload: { connectionId: '...', integrationKey: 'quickbooks' }
    },
    onError: (error) => {
      console.error('Connection failed:', error);
    },
  });

  return (
    <div>
      <button onClick={() => openLink()} disabled={!isReady}>
        Connect QuickBooks
      </button>
    </div>
  );
}

Advanced Usage

import { useSync2Books } from '@sync2books/react';

function MyComponent() {
  const { openLink, isReady } = useSync2Books({
    companyId: 'your-company-id',
    applicationId: 'your-application-id',
    applicationName: 'Your App Name',
    apiKey: 'sk_live_your_api_key',
    integrationKey: 'quickbooks',
    embedBaseUrl: 'https://app.sync2books.com', // Optional: custom embed URL
    integrations: [
      { key: 'quickbooks', label: 'QuickBooks Online', enabled: true },
      { key: 'xero', label: 'Xero', enabled: false }, // Disabled
    ],
    onReady: () => {
      console.log('Link is ready');
    },
    onConnection: ({ connectionId, integrationKey }) => {
      console.log('Connection established:', connectionId, integrationKey);
    },
    onSuccess: (payload) => {
      console.log('Success:', payload);
    },
    onLinkError: ({ message, userRecoverable }) => {
      if (userRecoverable) {
        // Show retry button
      } else {
        // Show error message
      }
    },
    onError: (error) => {
      console.error('Error:', error);
    },
  });

  return (
    <div>
      <button onClick={() => openLink({ integrationKey: 'xero' })}>
        Connect Xero
      </button>
    </div>
  );
}

API Reference

`useSync2Books(config)`

Config Options:

Option

Type

Required

Description

companyId

string

✅

Your company/user ID

applicationId

string

✅

Your application ID

applicationName

string

✅

Your application name (shown in OAuth consent)

apiKey

string

✅

Your API key

integrationKey

'quickbooks' | 'xero' | 'sage'

✅

Default integration

embedBaseUrl

string

❌

Custom embed URL (defaults to window.location.origin)

integrations

array

❌

Custom integration list with enabled flags

onReady

function

❌

Called when Link is ready

onConnection

function

❌

Called when connection is established

onSuccess

function

❌

Called on successful connection

onLinkError

function

❌

Called on connection error

onError

function

❌

Called on any error

Returns:

openLink(args?) - Function to open the Link modal
isReady - Boolean indicating if Link is ready
isInitiated - Boolean indicating if Link has been initialized

Vue Integration

Installation

npm install @sync2books/vue
# or
yarn add @sync2books/vue

Basic Usage

<template>
  <div>
    <button @click="handleConnect" :disabled="!isReady">
      Connect QuickBooks
    </button>
  </div>
</template>

<script setup>
import { useSync2Books } from '@sync2books/vue';

const { openLink, isReady } = useSync2Books({
  companyId: 'your-company-id',
  applicationId: 'your-application-id',
  applicationName: 'Your App Name',
  apiKey: 'sk_live_your_api_key',
  integrationKey: 'quickbooks',
  onSuccess: (payload) => {
    console.log('Connected!', payload);
  },
  onError: (error) => {
    console.error('Connection failed:', error);
  },
});

function handleConnect() {
  openLink();
}
</script>

Advanced Usage

<template>
  <div>
    <button @click="connectQuickBooks">Connect QuickBooks</button>
    <button @click="connectXero">Connect Xero</button>
  </div>
</template>

<script setup>
import { ref } from 'vue';
import { useSync2Books } from '@sync2books/vue';

const connectionId = ref(null);

const { openLink, isReady } = useSync2Books({
  companyId: 'your-company-id',
  applicationId: 'your-application-id',
  applicationName: 'Your App Name',
  apiKey: 'sk_live_your_api_key',
  integrationKey: 'quickbooks',
  integrations: [
    { key: 'quickbooks', label: 'QuickBooks Online', enabled: true },
    { key: 'xero', label: 'Xero', enabled: true },
  ],
  onConnection: ({ connectionId: id, integrationKey }) => {
    connectionId.value = id;
    console.log('Connected to', integrationKey);
  },
  onLinkError: ({ message, userRecoverable }) => {
    if (userRecoverable) {
      // Show retry option
    } else {
      alert(message);
    }
  },
});

function connectQuickBooks() {
  openLink({ integrationKey: 'quickbooks' });
}

function connectXero() {
  openLink({ integrationKey: 'xero' });
}
</script>

Angular Integration

Installation

npm install @sync2books/angular

Basic Usage

import { Component } from '@angular/core';
import { useSync2Books } from '@sync2books/angular';

@Component({
  selector: 'app-connect',
  template: `
    <button (click)="connect()" [disabled]="!isReady">
      Connect QuickBooks
    </button>
  `,
})
export class ConnectComponent {
  private link = useSync2Books({
    companyId: 'your-company-id',
    applicationId: 'your-application-id',
    applicationName: 'Your App Name',
    apiKey: 'sk_live_your_api_key',
    integrationKey: 'quickbooks',
    onSuccess: (payload) => {
      console.log('Connected!', payload);
    },
    onError: (error) => {
      console.error('Connection failed:', error);
    },
  });

  get isReady() {
    return this.link.isReady;
  }

  connect() {
    this.link.openLink();
  }
}

Svelte Integration

Installation

npm install @sync2books/svelte

Basic Usage

<script>
  import { useSync2Books } from '@sync2books/svelte';

  const { openLink, isReady } = useSync2Books({
    companyId: 'your-company-id',
    applicationId: 'your-application-id',
    applicationName: 'Your App Name',
    apiKey: 'sk_live_your_api_key',
    integrationKey: 'quickbooks',
    onSuccess: (payload) => {
      console.log('Connected!', payload);
    },
    onError: (error) => {
      console.error('Connection failed:', error);
    },
  });
</script>

<button on:click={() => openLink()} disabled={!isReady}>
  Connect QuickBooks
</button>

Customization

Application Settings

Configure your application's Link appearance in the dashboard:

Go to Applications → Settings
Set Link Logo URL - Your app's logo (shown in OAuth consent)
Set Link Display Name - Your app's name (shown in OAuth consent)
Add Redirect URIs - URLs where users are redirected after OAuth

Redirect URIs

Redirect URIs must be configured in your application settings. Examples:

http://localhost:3000/callback
https://app.example.com/callback
https://app.example.com/application/{applicationId}/connect

After successful OAuth, users are redirected to the first matching URI from your configured list.

Error Handling

User Recoverable Errors

Some errors allow users to retry:

onLinkError: ({ message, userRecoverable }) => {
  if (userRecoverable) {
    // Show retry button
    setShowRetry(true);
  } else {
    // Show error message
    setErrorMessage(message);
  }
}

Common Errors

Error

Cause

Solution

No auth strategy provided

Missing apiKey or getAuthUrl

Provide API key

Connection failed

OAuth authorization failed

User needs to retry

Connection expired

OAuth token expired

Reconnect the integration

Best Practices

Show loading state - Disable buttons until isReady is true
Handle errors gracefully - Show user-friendly error messages
Store connection ID - Save connectionId after successful connection
Test redirect URIs - Ensure redirect URIs are correctly configured
Use production API keys - Use sk_live_... keys in production

Link UI Preview

The Link component shows a modal/dialog with the following steps:

Step 1: Integration Selection

The user sees a searchable list of available integrations:

┌─────────────────────────────────────┐
│  Connect to Accounting System       │
├─────────────────────────────────────┤
│  [Search integrations...]            │
│                                      │
│  ┌──────────────────────────────┐  │
│  │ 🧾 QuickBooks Online         │  │
│  │    Intuit                    │  │
│  │    [Connect]                 │  │
│  └──────────────────────────────┘  │
│                                      │
│  ┌──────────────────────────────┐  │
│  │ 📊 Xero                      │  │
│  │    Xero                     │  │
│  │    [Connect] (Coming Soon)  │  │
│  └──────────────────────────────┘  │
│                                      │
│  ┌──────────────────────────────┐  │
│  │ 📈 Sage                      │  │
│  │    Sage                     │  │
│  │    [Connect] (Coming Soon)  │  │
│  └──────────────────────────────┘  │
└─────────────────────────────────────┘

After selecting an integration, a new tab/window opens with the accounting system's OAuth consent page (e.g., QuickBooks). The modal shows:

┌─────────────────────────────────────┐
│  ⏳ Waiting for QuickBooks          │
│     connection...                  │
├─────────────────────────────────────┤
│  🔵 [Spinner]                      │
│                                      │
│  Enter your account details and     │
│  log in to QuickBooks in the tab   │
│  we opened to establish a data      │
│  connection with Your App Name.     │
│                                      │
│  ┌──────────────────────────────┐  │
│  │ QuickBooks didn't open?      │  │
│  │ [Open QuickBooks]            │  │
│  └──────────────────────────────┘  │
└─────────────────────────────────────┘

Step 3: Success

After successful OAuth, the modal shows:

┌─────────────────────────────────────┐
│  ✅ Connection created successfully │
├─────────────────────────────────────┤
│  Your App Name is now connected to   │
│  QuickBooks Online.                 │
│                                      │
│  ┌──────────────────────────────┐  │
│  │ What's next?                 │  │
│  │ You can now configure        │  │
│  │ mappings and start syncing    │  │
│  │ data.                         │  │
│  └──────────────────────────────┘  │
│                                      │
│  [Complete]                          │
└─────────────────────────────────────┘

Customization

The Link component can be customized via your application settings:

Logo - Set linkLogoUrl to show your app's logo in the OAuth consent screen
Display Name - Set linkDisplayName to show your app's name (e.g., "Your App Name")
Redirect URIs - Configure where users are redirected after OAuth completes

Next Steps

Getting Started - Set up your API key
Expense Management - Create and sync expenses
Sync & Monitoring - Track sync status

PreviousAttachments NextAPI Reference

Last updated 1 month ago

Good night

hashtagOverview

hashtagHow Link Works

hashtagPrerequisites

hashtagReact Integration

hashtagInstallation

hashtagBasic Usage

hashtagAdvanced Usage

hashtagAPI Reference

hashtaguseSync2Books(config)

hashtagVue Integration

hashtagInstallation

hashtagBasic Usage

hashtagAdvanced Usage

hashtagAngular Integration

hashtagInstallation

hashtagBasic Usage

hashtagSvelte Integration

hashtagInstallation

hashtagBasic Usage

hashtagCustomization

hashtagApplication Settings

hashtagRedirect URIs

hashtagError Handling

hashtagUser Recoverable Errors

hashtagCommon Errors

hashtagBest Practices

hashtagLink UI Preview

hashtagStep 1: Integration Selection

hashtagStep 2: OAuth Consent

hashtagStep 3: Success

hashtagCustomization

hashtagNext Steps

Overview

How Link Works

Prerequisites

React Integration

Installation

Basic Usage

Advanced Usage

API Reference

`useSync2Books(config)`

Vue Integration

Installation

Basic Usage

Advanced Usage

Angular Integration

Installation

Basic Usage

Svelte Integration

Installation

Basic Usage

Customization

Application Settings

Redirect URIs

Error Handling

User Recoverable Errors

Common Errors

Best Practices

Link UI Preview

Step 1: Integration Selection

Step 2: OAuth Consent

Step 3: Success

Customization

Next Steps