New Integration: Zoho Invoice

Description

Add Zoho Invoice integration to sync invoices, estimates, expenses, and billing activity into CORE.

Reference Implementations

Existing Integrations (use as templates)

• integrations/hubspot/ - Similar business tool integration with OAuth
• integrations/zoho-mail/ - Existing Zoho product integration (reuse OAuth patterns)
• integrations/linear/ - For reference

Required Files Structure

integrations/zoho-invoice/
├── src/
│   ├── index.ts          # Main entry, OAuth spec
│   ├── schedule.ts       # Sync logic
│   ├── utils.ts          # Zoho Invoice API utilities
│   ├── account-create.ts # OAuth setup
│   └── create-activity.ts # Activity formatting
├── package.json
├── tsup.config.ts
└── README.md

Zoho Invoice API Integration

OAuth Setup

• Use OAuth 2.0 for authentication
• Access tokens expire after a period; refresh tokens are permanent
• Base URL: https://www.zohoapis.com/invoice/v3/ (for .com domain)
• Important: 8 different domains exist for Zoho APIs; must use the correct domain for the user's organization

Key Endpoints

• GET /invoices - List invoices
• GET /invoices/{invoice_id} - Get invoice details
• POST /invoices - Create invoice
• GET /estimates - List estimates
• GET /items - List items/products
• GET /contacts - List contacts/customers
• GET /expenses - List expenses
• GET /projects - List projects
• GET /recurring-invoices - List recurring invoices
• GET /creditnotes - List credit notes

Rate Limits

• 100 requests per minute per organization
• HTTP 429 returned when rate limit exceeded

Events to Track

1. Invoices - Invoice created, sent, paid, overdue, voided
2. Estimates - Estimate created, accepted, declined
3. Payments - Payment received, refunded
4. Expenses - Expense logged, categorized
5. Recurring Invoices - Recurring invoice generated, payment received
6. Contacts - Customer created, updated

Implementation Tasks

• Set up basic integration structure following integrations/github/src/index.ts pattern
• Implement OAuth 2.0 flow in account-create.ts (reference existing integrations/zoho-mail/ for Zoho OAuth patterns)
• Create API utilities in utils.ts for v3 API with multi-domain support
• Implement sync logic in schedule.ts for invoices, estimates, and expenses
• Convert Zoho Invoice events to CORE activity format
• Add error handling and rate limiting (100 req/min/org)
• Create integration documentation
• Add to integrations/README.md

Technical Notes

• Existing integrations/zoho-mail/ can be referenced for Zoho OAuth 2.0 patterns
• REST-based API with predictable URL structure
• Must handle 8 different Zoho domains (.com, .eu, .in, .com.au, .jp, etc.)
• Rate limit: 100 requests/minute/organization
• Refresh tokens are permanent; access tokens expire and need refresh
• Postman collection available for API testing

Resources

• Zoho Invoice API Introduction
• Zoho Invoice Invoices API
• Zoho Invoice OAuth Documentation
• Zoho Invoice Items API
• Zoho Invoice API Collection (Postman)

Labels

enhancement, integration, new-feature