# Zoho API Integration

Modular PHP integration with Zoho APIs (Projects, Desk, and more).

## Features

- **Modular Architecture**: Easy to add new Zoho services
- **OAuth2 Authentication**: Secure token management with auto-refresh
- **Multiple Export Formats**: JSON and CSV support
- **Logging**: File-based logging for monitoring
- **Cron-Ready**: Built for hourly automated exports

## Directory Structure

```
zoho-qwen/
├── config/
│   └── config.php          # Configuration settings
├── src/
│   ├── Core/
│   │   └── ZohoClient.php  # OAuth2 & HTTP client
│   ├── Interfaces/
│   │   └── ZohoServiceInterface.php
│   ├── Services/
│   │   ├── ProjectsService.php
│   │   └── DeskService.php
│   ├── Export/
│   │   └── ExportManager.php
│   └── Utils/
│       └── Logger.php
├── scripts/
│   ├── authenticate.php    # OAuth2 setup
│   └── export_projects.php # Export script
├── cron/
│   └── hourly_export.sh    # Cron wrapper
└── storage/                # Tokens, exports, logs (auto-created)
```

## Setup

### 1. Install Requirements

- PHP 8.0+
- cURL extension

### 2. Configure Environment

```bash
cp .env.example .env
# Edit .env with your Zoho credentials
```

### 3. Register Zoho Application

1. Visit [Zoho API Console](https://api-console.zoho.com/)
2. Create a new client
3. Select "Server-based Application"
4. Add your redirect URI
5. Copy Client ID and Client Secret to `.env`

### 4. Authenticate

```bash
# Generate authorization URL
php scripts/authenticate.php --service=projects

# Visit the URL, authorize, then exchange the code:
php scripts/authenticate.php --service=projects --code=YOUR_CODE
```

### 5. Run Export

```bash
# Manual export
php scripts/export_projects.php

# Include task details
php scripts/export_projects.php --include-tasks

# Export as CSV
php scripts/export_projects.php --format=csv
```

### 6. Setup Cron (Optional)

```bash
# Edit the cron script path
nano cron/hourly_export.sh

# Add to crontab (runs every hour)
crontab -e
# Add: 0 * * * * /path/to/cron/hourly_export.sh
```

## Adding New Zoho Services

1. Add service config in `config/config.php`:

```php
'desk' => [
    'enabled' => true,
    'api_base' => 'https://desk.zoho.com/api/v1',
    'scopes' => 'ZohoDesk.tickets.READ',
],
```

2. Create service class implementing `ZohoServiceInterface`:

```php
class DeskService implements ZohoServiceInterface
{
    // Implement required methods
}
```

3. Create export script for the service

## Configuration

Edit `config/config.php` to customize:

- API domains (for EU/US data centers)
- OAuth scopes
- Export formats and locations
- Log levels

## Troubleshooting

**Token expired errors**: Re-run authentication script

**401 Unauthorized**: Check OAuth scopes in config

**Export directory not writable**: `chmod 755 storage/exports`

## License

MIT