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

Clone or copy the project files
Install Python dependencies:
```
pip install -r requirements.txt
```

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

Run the application:
```
python app.py
```
Open in browser: Navigate to http://localhost:5000

QuickBooks Online Setup

Creating an App

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

Configuring OAuth

In your app settings, add Redirect URI:
- Development: http://localhost:5000/oauth/callback
- Production: https://yourdomain.com/oauth/callback
Select required scopes:
- com.intuit.quickbooks.accounting

Using the Sandbox

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

Usage Guide

1. Connect to QuickBooks

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

2. Import Data

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

3. Create Templates

Navigate to Templates page
Click + New to create a template
Select data type and load default fields
Configure field mappings
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

Credentials Storage: OAuth credentials are stored in a separate .credentials file with restricted permissions
Session Security: Set a strong SECRET_KEY in production
File Uploads: Validated for extension and size (16MB max)
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

Build Windows executable app command

pyinstaller .\build_exe.spec --clean --noconfirm