Workflow: SmartCRM — Sincronizare ERP Bidirecțională

Module implicate: SmartCRM · Leads · Clients · Invoices · Projects · Tickets · Products · Warehouse
Cine îl folosește: Administrator · IT · Operațional
Durata tipică: Sync manual = minute · Sync automat = la fiecare 1/2/4/12/24 ore (configurabil)

Overview

SmartCRM este un conector bidirecțional între CRMConnect și un sistem ERP/CRM extern (ex: un ERP propriu sau alt CRM), nu un instrument AI sau de scoring. Sincronizează în ambele direcții: importă date din sistemul extern în CRM și exportă înregistrări CRM în sistemul extern.

Entități sincronizate:

Entitate	Import (extern → CRM)	Export (CRM → extern)
Produse + prețuri	✓	✗
Grupe produse	✓	✗
Clienți + contacte	✓	✓
Comenzi / Proformate	✓ (ca Sales Orders)	✗
Stocuri per depozit	✓	✗
Discount-uri per grup	✓	✗
Leads	✓	✓
Proiecte	✓	✓
Tichete	✓	✓
Facturi	✓	✓

Scoring module: modulul scoring este nefuncțional ca shipped — SQL-ul de instalare și hook-urile de activare sunt complet comentate în cod. Tabelele nu se creează la activare. Nu există calcul de scor operațional. Nu se integrează cu SmartCRM.

Diagrama fluxului

[SETUP — admin, obligatoriu înainte de primul sync]
  │
  ├── SmartCRM → Settings:
  │     ├── smartcrm_api_url (URL-ul sistemului extern + /index.php/api/)
  │     ├── smartcrm_auth_token (Bearer token pentru REST API)
  │     ├── smartcrm_client_token (token separat pentru entity sync V2 — OBLIGATORIU)
  │     ├── smartcrm_currency_mapping (JSON mapare ID monedă extern → local)
  │     └── Test Connection → verificare conectivitate
  │
  ├── Configurare cron (opțional):
  │     ├── smartcrm_cron = 'yes'
  │     └── smartcrm_interval: 1/2/4/12/24 ore
  │
  └── Batch settings:
        smartcrm_batch_size (implicit 50)
        smartcrm_api_timeout (implicit 30s)
        smartcrm_max_retries (implicit 3, cu backoff exponențial)
  │
  ↓
════════════════════════════════════
IMPORT — DATE DIN EXTERN ÎN CRM
════════════════════════════════════
  │
  ├── Manual: SmartCRM → Sync → buton per entitate
  ├── Automat (cron): toate 5 entități principale dacă interval a trecut
  │
  ├── Flux import per entitate:
  │     ├── GET /api/{entity} din sistemul extern (cu auth token)
  │     ├── Deduplicate: verifică external_id + external_channel='smartcrm'
  │     ├── INSERT sau UPDATE în tabelele CRM
  │     └── Marchează cu external_id + external_channel='smartcrm'
  │
  ├── Entități cu sync avansat (sync_entity_v2 — necesită smartcrm_client_token):
  │     ├── Unități de măsură (UM)
  │     ├── Grupe produse → tblitems_groups
  │     ├── Produse cu prețuri per depozit → tblitems
  │     ├── Clienți cu mapare județ/localitate → tblclients
  │     ├── Grupe clienți → tbldiscount_groups
  │     ├── Contacte → tblcontacts
  │     ├── Comenzi/Proformate → tblcart + tblcart_detailt
  │     ├── Monede → tblcurrencies (necesită currency_mapping)
  │     ├── Depozite → tblwarehouse
  │     ├── Stocuri → tblinventory_manage
  │     └── Grile discount → tblitem_client_group_discounts
  │
  └── Log: fiecare operație → tbl_smartcrm_logs (level, entity, records_processed/success/failed)
  │
  ↓
════════════════════════════════════
EXPORT — DATE DIN CRM ÎN EXTERN
════════════════════════════════════
  │
  ├── Identificare înregistrări noi: WHERE external_channel IS NULL OR != 'smartcrm'
  ├── Formatare payload via format_{entity}_for_smartcrm()
  ├── POST /api/{entity} în sistemul extern
  ├── La succes: mark_as_exported_to_smartcrm() → external_id + external_channel='smartcrm'
  └── La eșec: retry cu backoff exponențial (2^n secunde, max smartcrm_max_retries)
  │
  ↓
[MONITORIZARE]
  │
  ├── SmartCRM → Dashboard: statistici sync (inserted/updated/failed per entitate per zi)
  ├── SmartCRM → Logs: detalii per operație (level: DEBUG/INFO/WARNING/ERROR)
  ├── SmartCRM → Errors Overview: erori grupate
  └── reset_statistics() / cleanup_logs() — curățare manuală

[SYNC COMPLET ✓ · DATE BIDIRECȚIONALE ✓]

Pas cu pas

1. Setup inițial (admin)

Unde: /admin/smartcrm → Settings

1a. Credențiale API (obligatorii)

Opțiune	Descriere
`smartcrm_api_url`	URL-ul bazei sistemului extern (ex: `https://erp.companie.ro/`). Modulul adaugă automat `index.php/api/{entity}`
`smartcrm_auth_token`	Bearer token REST pentru autentificare la `/api/leads`, `/api/clients` etc.
`smartcrm_client_token`	Token separat folosit de sync_entity_v2 pentru entitățile avansate (produse, stocuri, grupe). Acest token nu apare în Settings UI — trebuie setat manual în `tbloptions` cu `name='smartcrm_client_token'`. Fără el, sync_entity_v2 eșuează cu „Token client lipsă".

Test conectivitate: butonul Test Connection → verifică accesibilitatea URL-ului + validitatea token-ului.

1b. Mapare monede (obligatoriu dacă sincronizați prețuri)

Unde: Settings → Currency Mapping

JSON cu maparea ID-urilor de monedă din sistemul extern la ID-urile locale:

{"1": 1, "2": 3, "5": 2}

(ex: ID 1 în extern = ID 1 local = RON; ID 2 în extern = ID 3 local = USD)

Fără această mapare, sincronizarea prețurilor returnează eroare.

1c. Configurare cron automat

Opțiune	Valori	Descriere
`smartcrm_cron`	`'yes'` / `'no'`	Activare sync automat
`smartcrm_interval`	`1`, `2`, `4`, `12`, `24`	Interval în ore între sync-uri

La fiecare execuție cron CRM, sync_cron_smartcrm() verifică dacă smartcrm_cron = 'yes' și dacă a trecut intervalul de la smartcrm_last_update. Dacă da, sincronizează toate 5 entități principale.

1d. Setări performanță

Opțiune	Implicit	Descriere
`smartcrm_batch_size`	50	Înregistrări per request
`smartcrm_api_timeout`	30	Timeout request în secunde
`smartcrm_max_retries`	3	Retry-uri la eșec (backoff: 2^n sec)
`smartcrm_log_level`	INFO	`DEBUG` / `INFO` / `WARNING` / `ERROR`

2. Sync manual per entitate

Unde: /admin/smartcrm → Sync tab

Butoane separate per entitate:

Sync Leads — import/export leads
Sync Clients — import/export clienți
Sync Projects — import/export proiecte
Sync Tickets — import/export tichete
Sync Invoices — import/export facturi
Sync Entity V2 (multiselect) — produse, stocuri, grupe, comenzi etc. (necesită smartcrm_client_token)
Export → SmartCRM (per entitate) — exportă înregistrările locale nemarcate

3. Mecanismul de deduplicare

Înregistrările sincronizate sunt marcate cu:

external_id — ID-ul din sistemul extern
external_channel = 'smartcrm' — identifică sursa

La re-sync, sistemul verifică existența external_id + external_channel înainte de INSERT → face UPDATE dacă există, INSERT dacă nu.

Înregistrările create local (fără external_channel) sunt eligibile pentru export.

4. Monitorizare și logs

Unde: /admin/smartcrm/dashboard + /admin/smartcrm/errors_overview

Dashboard (tbl_smartcrm_sync_stats): per zi per entitate — total/inserted/updated/failed + status (SUCCESS/FAILED/PARTIAL).

Logs (tbl_smartcrm_logs): detalii complete per operație cu records_processed, records_success, records_failed, execution_time.

Curățare:

reset_statistics() — resetează contoarele (necesită smartcrm → edit)
cleanup_logs() — șterge log-urile (necesită smartcrm → delete)

Nota despre modulul Scoring

Modulul scoring este instalat dar nefuncțional:

SQL-ul de creare tabele din install.php este complet comentat (/* ... */)
Hook-ul de activare (scoring_module_activation_hook) este comentat
Meniul și permisiunile nu sunt înregistrate
Funcția save_scoring_lead() este un stub gol
Tabelele necesare nu se creează la activarea modulului

Dacă aveți nevoie de lead scoring operațional, acest modul necesită intervenție manuală (creare tabele manual în DB + decomentare cod).

Permisiuni necesare

Permisiune	Acces
`smartcrm → view`	Acces la dashboard, logs, statistici, butoane de sync
`smartcrm → edit`	Reset statistici
`smartcrm → delete`	Cleanup logs
Settings SmartCRM	Disponibil pentru staff cu `view` (fără verificare admin suplimentară)

Gotchas

Problemă	Cauză	Soluție
Sync entity V2 eșuează cu „Token client lipsă"	`smartcrm_client_token` nesetat	Inserați manual în `tbloptions`: `INSERT INTO tbloptions (name,value,autoload) VALUES ('smartcrm_client_token','VALOARE_TOKEN',0)`
Prețurile nu se sincronizează	`smartcrm_currency_mapping` lipsă sau JSON invalid	Configurați maparea corectă în Settings
Duplicate înregistrări la re-sync	`external_id` lipsă din răspunsul extern	Verificați că API-ul extern returnează un câmp ID consistent
Cron nu sincronizează	`smartcrm_cron != 'yes'` sau interval neîndeplinit	Activați cron + verificați `smartcrm_last_update` în `tbloptions`
Retry loop lent	`max_retries=3` + backoff 2^n = 1+2+4=7 secunde extra per entitate eșuată	Reduceți `smartcrm_max_retries` la 1 pentru sync rapid sau măriți `api_timeout`

Referințe module

Leads — leads sincronizate
Clients — clienți sincronizați
Invoices — facturi sincronizate
Warehouse — stocuri sincronizate
Integrations — Merlin ERP — alt conector ERP disponibil

Tip

Rulați o sincronizare manuală pentru fiecare tip de entitate (lead-uri, clienți, facturi) și verificați rezultatele înainte de activarea sincronizării automate programate — confirmarea că mapările câmpurilor funcționează corect pe un dataset mic previne erorile de propagare în masă a datelor în ambele sisteme.

Warning

Sincronizarea bidirecțională înseamnă că o înregistrare modificată în ERP poate suprascrie o modificare făcută în CRMConnect. Decideți care sistem este masterul pentru fiecare tip de entitate înainte de activarea sincronizării — fără un sistem master clar, modificările conflictuale creează date care nu aparțin în niciun sistem.