Iconus Tech/Documentation

OAuth Integration

Connect your accounting platform to automatically sync check data with Iconus Tech.

Overview

OAuth integration allows you to connect QuickBooks, Xero, Zoho Books, or FreshBooks to automatically import and sync check data.

Supported Platforms:

  • QuickBooks Online
  • Xero
  • Zoho Books
  • FreshBooks

OAuth Flow

1. Initiate OAuth

Redirect users to the OAuth authorization URL:

Initiate OAuth
curl "https://api.iconustech.com/v1/oauth/authorize?platform=quickbooks&partnerId=partner_abc123"

Query Parameters:

| Parameter | Required | Description | |-----------|----------|-------------| | platform | Yes | Platform name (quickbooks, xero, zoho, freshbooks) | | partnerId | Yes | Your partner ID | | redirectUri | No | Custom redirect URI |

2. User Authorizes

User is redirected to the platform's authorization page where they grant permissions.

3. Callback

After authorization, user is redirected back with an authorization code:

https://yourapp.com/oauth/callback?code=AUTH_CODE&state=STATE

4. Exchange Code for Tokens

Exchange Code
curl -X POST https://api.iconustech.com/v1/oauth/token \
-H "Content-Type: application/json" \
-H "x-api-key: YOUR_API_KEY" \
-d '{
  "code": "AUTH_CODE",
  "platform": "quickbooks",
  "partnerId": "partner_abc123"
}'

Response:

json
{
"success": true,
"data": {
  "accessToken": "eyJhbGciOiJIUzI1NiIs...",
  "refreshToken": "refresh_token_here",
  "expiresIn": 3600,
  "platform": "quickbooks",
  "companyId": "company_123",
  "companyName": "Acme Corporation"
}
}

JavaScript Implementation

oauth-integration.js
class OAuthIntegration {
constructor(apiKey, partnerId) {
  this.apiKey = apiKey;
  this.partnerId = partnerId;
  this.baseUrl = 'https://api.iconustech.com/v1';
}
 
// Step 1: Get authorization URL
getAuthUrl(platform, redirectUri) {
  const params = new URLSearchParams({
    platform,
    partnerId: this.partnerId,
    redirectUri: redirectUri || `${window.location.origin}/oauth/callback`,
  });
  
  return `${this.baseUrl}/oauth/authorize?${params}`;
}
 
// Step 2: Exchange code for tokens
async exchangeCode(code, platform) {
  const response = await fetch(`${this.baseUrl}/oauth/token`, {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json',
      'x-api-key': this.apiKey,
    },
    body: JSON.stringify({
      code,
      platform,
      partnerId: this.partnerId,
    }),
  });
  
  return response.json();
}
 
// Step 3: Sync checks from platform
async syncChecks(platform) {
  const response = await fetch(
    `${this.baseUrl}/oauth/${platform}/sync`,
    {
      method: 'POST',
      headers: {
        'x-api-key': this.apiKey,
      },
    }
  );
  
  return response.json();
}
}
 
// Usage
const oauth = new OAuthIntegration(
process.env.ICONUS_API_KEY,
'partner_abc123'
);
 
// Redirect to QuickBooks
window.location.href = oauth.getAuthUrl('quickbooks');
 
// Handle callback
const urlParams = new URLSearchParams(window.location.search);
const code = urlParams.get('code');
 
if (code) {
const tokens = await oauth.exchangeCode(code, 'quickbooks');
console.log('Connected:', tokens.data.companyName);
 
// Sync checks
const result = await oauth.syncChecks('quickbooks');
console.log(`Synced ${result.data.checksImported} checks`);
}

Platform-Specific Guides

QuickBooks Online

quickbooks-integration.js
// Connect to QuickBooks
async function connectQuickBooks() {
const authUrl = `https://api.iconustech.com/v1/oauth/authorize?platform=quickbooks&partnerId=${partnerId}`;
 
// Open popup or redirect
window.open(authUrl, 'QuickBooks Auth', 'width=600,height=700');
}
 
// Sync checks from QuickBooks
async function syncQuickBooksChecks() {
const response = await fetch(
  'https://api.iconustech.com/v1/oauth/quickbooks/sync',
  {
    method: 'POST',
    headers: {
      'x-api-key': process.env.ICONUS_API_KEY,
    },
  }
);
 
const result = await response.json();
 
console.log('Sync Results:');
console.log(`- Checks Imported: ${result.data.checksImported}`);
console.log(`- Checks Updated: ${result.data.checksUpdated}`);
console.log(`- Errors: ${result.data.errors}`);
 
return result.data;
}

Xero

xero-integration.js
// Connect to Xero
async function connectXero() {
const authUrl = `https://api.iconustech.com/v1/oauth/authorize?platform=xero&partnerId=${partnerId}`;
window.location.href = authUrl;
}
 
// Import invoices as checks
async function importXeroInvoices() {
const response = await fetch(
  'https://api.iconustech.com/v1/oauth/xero/import-invoices',
  {
    method: 'POST',
    headers: {
      'x-api-key': process.env.ICONUS_API_KEY,
    },
  }
);
 
return response.json();
}

Webhook Events

Subscribe to OAuth events:

json
{
"event": "oauth.connected",
"data": {
  "platform": "quickbooks",
  "partnerId": "partner_abc123",
  "companyId": "company_123",
  "companyName": "Acme Corporation",
  "timestamp": "2025-11-12T10:30:00Z"
}
}
json
{
"event": "oauth.sync_completed",
"data": {
  "platform": "quickbooks",
  "partnerId": "partner_abc123",
  "checksImported": 45,
  "checksUpdated": 12,
  "errors": 0,
  "timestamp": "2025-11-12T10:35:00Z"
}
}

Next Steps

Support