# Zoho CRM Integration Setup Guide

## Overview
This integration syncs WordPress Events Calendar data with Zoho CRM, mapping:
- Events → Campaigns
- Users/Trainers → Contacts  
- Ticket Purchases → Invoices

## Setup Steps

### 1. Create Zoho OAuth Application

1. Go to [Zoho API Console](https://api-console.zoho.com/)
2. Click "CREATE NEW CLIENT"
3. Choose "Server-based Applications"
4. Fill in details:
   - **Client Name**: HVAC Community Events Integration
   - **Homepage URL**: Your WordPress site URL
   - **Authorized Redirect URIs**: 
     - For setup script: `http://localhost:8080/callback`
     - For WordPress admin: `https://your-site.com/wp-admin/edit.php?post_type=tribe_events&page=hvac-zoho-crm`
5. Click "CREATE" and save your Client ID and Client Secret

### 2. Generate Credentials Using Setup Script

The easiest way to set up credentials:

```bash
cd wp-content/plugins/hvac-community-events/includes/zoho
php setup-helper.php
```

Follow the prompts to:
1. Enter your Client ID and Client Secret
2. Open the authorization URL in your browser
3. Grant permissions and copy the authorization code
4. The script will automatically:
   - Exchange the code for tokens
   - Get your organization ID
   - Create the `zoho-config.php` file

### 3. Alternative: Manual Setup

If you prefer manual setup:

1. Create `zoho-config.php` from the template:
   ```bash
   cp zoho-config-template.php zoho-config.php
   ```

2. Generate authorization URL:
   ```
   https://accounts.zoho.com/oauth/v2/auth?
   scope=ZohoCRM.settings.all,ZohoCRM.modules.all,ZohoCRM.users.all&
   client_id=YOUR_CLIENT_ID&
   response_type=code&
   access_type=offline&
   redirect_uri=http://localhost:8080/callback
   ```

3. Exchange code for tokens using cURL:
   ```bash
   curl -X POST https://accounts.zoho.com/oauth/v2/token \
     -d "grant_type=authorization_code" \
     -d "client_id=YOUR_CLIENT_ID" \
     -d "client_secret=YOUR_CLIENT_SECRET" \
     -d "redirect_uri=http://localhost:8080/callback" \
     -d "code=YOUR_AUTH_CODE"
   ```

4. Get organization ID:
   ```bash
   curl -X GET https://www.zohoapis.com/crm/v2/org \
     -H "Authorization: Zoho-oauthtoken YOUR_ACCESS_TOKEN"
   ```

5. Update `zoho-config.php` with your credentials

### 4. WordPress Admin Setup

After creating the config file:

1. Go to WordPress Admin → Events → Zoho CRM
2. The integration will automatically detect your configuration
3. Click "Test Connection" to verify
4. Click "Create Custom Fields" to set up required fields in Zoho

## Required Permissions

The integration needs these Zoho CRM scopes:
- `ZohoCRM.settings.all` - For creating custom fields
- `ZohoCRM.modules.all` - For reading/writing records
- `ZohoCRM.users.all` - For user information
- `ZohoCRM.org.all` - For organization details (optional)

## Security Notes

- **NEVER** commit `zoho-config.php` to version control
- Keep your refresh token secure
- The integration automatically handles token refresh
- All API calls are logged for debugging (disable in production)

## Troubleshooting

### Common Issues

1. **"Invalid Client" Error**
   - Verify Client ID and Secret are correct
   - Ensure redirect URI matches exactly

2. **"Invalid Code" Error**  
   - Authorization codes expire quickly (< 1 minute)
   - Generate and use immediately

3. **"No Refresh Token" Error**
   - Make sure `access_type=offline` in auth URL
   - Include `prompt=consent` to force new refresh token

### Debug Mode

Enable debug logging in `zoho-config.php`:
```php
define('ZOHO_DEBUG_MODE', true);
define('ZOHO_LOG_FILE', WP_CONTENT_DIR . '/zoho-crm-debug.log');
```

Check the log file for detailed API responses.

## Support

For issues or questions:
1. Check the debug log
2. Verify credentials in Zoho API Console
3. Ensure all required modules are enabled in Zoho CRM