Initial Codes

2026-02-13 10:38:45 -05:00
parent 0dd81218e0
commit 40a151787f
24 changed files with 7627 additions and 1 deletions
@@ -1 +1,244 @@
-# QB-Import-from-Excel
+# 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