ricardoalejandro/kommo-integration

Kommo CRM Integration — Clarin CRM

Architecture

Kommo integration is a one-way sync (Kommo → Clarin) using the Kommo REST API v4.

backend/internal/kommo/
  client.go     → Rate-limited HTTP client for Kommo API
  sync.go       → SyncService: background worker (5s polling)

Sync Flow

1. SyncService.Start() launches a goroutine that polls every 5 seconds
2. Fetches leads, contacts, tags from Kommo API
3. Upserts into PostgreSQL via repository.go
4. Broadcasts lead_update via WebSocket after sync

Key Components

client.go — Kommo API Client

• Rate-limited (respects Kommo's API limits)
• GetLeads() — Fetches leads with pagination
• GetContacts() — Fetches contacts with pagination
• GetTags() — Fetches ALL tags with full pagination (fixed: was only page 1)
• Auth via Bearer token from environment variable

sync.go — Sync Service

• SyncService struct with client, repo, db, hub
• upsertLead() → creates/updates lead, calls syncLeadTags()
• upsertContact() → creates/updates contact, calls syncContactTags()
• syncLeadTags() → populates lead_tags junction table
• syncContactTags() → populates contact_tags junction table
• NormalizePhone() → Exported function for phone normalization

Phone Normalization

// Peru (51) is the only country supported
// 9-digit numbers starting with 9 get "51" prefix automatically
normalized := kommo.NormalizePhone("987654321")  // → "51987654321"
normalized := kommo.NormalizePhone("51987654321") // → "51987654321" (unchanged)

ALWAYS use kommo.NormalizePhone() when handling phone numbers in:

• api/server.go → handleCreateLead()
• service/service.go → CreateNewChat()
• kommo/sync.go → all sync operations

Adding New Synced Fields

1. Add field to Kommo API response struct
2. Add field to domain entity in domain/entities.go
3. Add migration in database.go
4. Update upsertLead() or upsertContact() in sync.go
5. Update repository queries
6. Build, deploy, verify sync in logs