# 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:**
   ```bash
   pip install -r requirements.txt
   ```

3. **Set environment variables (optional):**
   ```bash
   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:**
   ```bash
   python app.py
   ```

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

## QuickBooks Online Setup

### Creating an App

1. Go to [Intuit Developer Portal](https://developer.intuit.com/)
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

## Build Windows executable app command

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