138 lines
2.9 KiB
Markdown
138 lines
2.9 KiB
Markdown
# 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
|