QBO Excel Sync Web Application

A Flask-based web application for importing Excel data to QuickBooks Online.

Features

• OAuth 2.0 Authentication: Secure connection to QuickBooks Online
• Excel File Upload: Support for .xlsx and .xls files
• Field Mapping: Visual mapping of Excel columns to QBO fields
• Data Validation: Pre-import validation with error reporting
• Batch Import: Efficient batch processing with duplicate detection
• Custom Templates: Save and reuse field mapping configurations

Supported Data Types

1. Checks - Bank checks with payee, amount, memo
2. Invoices - Customer invoices with line items
3. Bills - Vendor bills with expenses
4. Customers - Customer master data
5. Vendors - Vendor master data
6. Chart of Accounts - Account setup

Project Structure

qbo_excel_sync_web/
├── app.py                  # Main Flask application
├── requirements.txt        # Python dependencies
├── src/
│   ├── api/
│   │   └── qbo_client.py   # QuickBooks API client
│   ├── config/
│   │   └── settings.py     # Configuration management
│   └── core/
│       ├── excel_parser.py      # Excel file processing
│       └── import_processor.py  # Import logic
├── static/
│   ├── css/
│   │   └── style.css       # Application styles
│   └── js/
│       └── app.js          # Shared JavaScript utilities
├── templates/
│   ├── base.html           # Base template with header/nav
│   ├── index.html          # Dashboard
│   ├── connection.html     # OAuth connection management
│   ├── import.html         # File upload and import
│   ├── templates.html      # Template management
│   ├── settings.html       # Application settings
│   ├── oauth_result.html   # OAuth callback result
│   ├── 404.html            # Not found error page
│   └── 500.html            # Server error page
├── data/                   # Config storage (auto-created)
│   ├── config.json         # Application settings
│   ├── .credentials        # OAuth tokens (secured)
│   └── templates/          # Custom mapping templates
└── uploads/                # Uploaded files (auto-created)

Installation

1. Clone or copy the project files

2. Install Python dependencies:

   pip install -r requirements.txt
   

3. Set environment variables (optional):

   export SECRET_KEY="your-secure-secret-key"
   export FLASK_DEBUG=false  # Set to false for production
   export PORT=5000          # Optional, default is 5000
   

4. Run the application:

   python app.py
   

5. Open in browser: Navigate to http://localhost:5000

QuickBooks Online Setup

Creating an App

1. Go to Intuit Developer Portal
2. Sign in or create a developer account
3. Click "My Apps" → "Create an app"
4. Select "QuickBooks Online and Payments"
5. Note your Client ID and Client Secret

Configuring OAuth

1. In your app settings, add Redirect URI:

   • Development: http://localhost:5000/oauth/callback
   • Production: https://yourdomain.com/oauth/callback

2. Select required scopes:

   • com.intuit.quickbooks.accounting

Using the Sandbox

1. In Developer Portal, go to "Dashboard" → "Sandbox"
2. Create a sandbox company for testing
3. Use "Sandbox" environment in the application

Usage Guide

1. Connect to QuickBooks

1. Navigate to Connection page
2. Enter your Client ID and Client Secret
3. Select Environment (Sandbox or Production)
4. Click Start OAuth Flow
5. Authorize in the QuickBooks popup
6. Verify connection with Test Connection

2. Import Data

1. Navigate to Import page
2. Upload your Excel file (drag & drop or browse)
3. Select the sheet to import
4. Choose the data type (Check, Invoice, etc.)
5. Configure field mappings in the Mapping tab
6. Click Validate to check for errors
7. Click Import to QuickBooks to execute

3. Create Templates

1. Navigate to Templates page
2. Click + New to create a template
3. Select data type and load default fields
4. Configure field mappings
5. Save for reuse in future imports

API Endpoints

Connection

• POST /api/credentials - Save OAuth credentials
• POST /api/oauth/start - Start OAuth flow
• GET /oauth/callback - OAuth redirect handler
• POST /api/oauth/manual - Manual token entry
• POST /api/disconnect - Revoke tokens
• GET /api/connection/test - Test connection

File Operations

• POST /api/upload - Upload Excel file
• GET /api/file/sheets - Get sheet names
• GET /api/file/columns?sheet=X - Get column names
• GET /api/file/preview?sheet=X&max_rows=20 - Preview data

Import

• POST /api/validate - Validate mapped data
• POST /api/import - Execute import

Templates

• GET /api/templates - List all templates
• GET /api/templates/default/{type} - Get default template
• POST /api/templates - Save template
• DELETE /api/templates/{name} - Delete template

Settings

• GET /api/settings - Get settings
• POST /api/settings - Update settings
• POST /api/settings/clear-credentials - Clear credentials

Configuration Options

Import Settings

Setting	Default	Description
skip_duplicates	true	Skip records matching existing QBO data
duplicate_check_fields	["DocNumber"]	Fields to check for duplicates
batch_size	50	Records per batch (1-200)
validate_before_import	true	Validate all data before import
create_missing_references	false	Auto-create missing customers/vendors
date_format	%Y-%m-%d	Expected date format
decimal_separator	.	Decimal separator for numbers
thousand_separator	,	Thousands separator

Field Mapping Reference

Check Fields

Excel Column	QBO Field	Transform
Payee	EntityRef.value	text
Bank Account	AccountRef.value	text
Date	TxnDate	date
Amount	Line.Amount	currency
Check Number	DocNumber	text
Memo	PrivateNote	text

Invoice Fields

Excel Column	QBO Field	Transform
Customer	CustomerRef.value	text
Date	TxnDate	date
Due Date	DueDate	date
Invoice Number	DocNumber	text
Item	Line.SalesItemLineDetail.ItemRef.value	text
Amount	Line.Amount	currency

Logging

Application logs are written to:

• Console output
• app.log file in application directory

Log format: timestamp - module - level - message

User actions (create, edit, delete) are automatically logged with:

• Timestamp
• User IP address
• Action type
• Details

Security Notes

1. Credentials Storage: OAuth credentials are stored in a separate .credentials file with restricted permissions
2. Session Security: Set a strong SECRET_KEY in production
3. File Uploads: Validated for extension and size (16MB max)
4. HTTPS: Use HTTPS in production for OAuth callbacks

Troubleshooting

"Not Connected" Error

• Verify credentials are saved correctly
• Check if tokens have expired (re-authenticate)
• Ensure redirect URI matches exactly

"Entity Not Found" During Import

• Enable "Auto-create missing references" in settings
• Verify customer/vendor names match exactly
• Check account names/numbers

"Duplicate Detection" Issues

• Adjust duplicate_check_fields in settings
• Clear existing records or disable skip_duplicates

License

Proprietary - Internal Use Only