Ghid Operațional: Sincronizarea Bidirecțională a Calendarului (Google & Outlook API v3)

Modulul de Calendar activități din Zarina CRM integrează un nucleu avansat de sincronizare bidirecțională (Inbound & Outbox) cu platformele Google Calendar și Microsoft Outlook. Prin automatizarea fluxurilor de telemetrie și maparea token-urilor OAuth2, platforma aliniază în timp real programările echipei, oferind managementului vizibilitate deplină și eliminând complet riscul suprapunerii evenimentelor (Double Booking).

1. Configurarea și Autorizarea Canalelor API

Inițializarea conexiunilor globale securizate se realizează la nivel de administrator în secțiunea Module → AUTOMATIZĂRI / API:

• Integrare Google Calendar: Necesită completarea credențialelor Google Client ID și Client Secret. Sistemul afișează automat un URL de redirect securizat (Redirect URI) ce trebuie autorizat în Google Cloud Console, permițând utilizatorilor legarea conturilor prin ecrane native de consimțământ.
• Integrare Microsoft Outlook: Se bazează pe protocolul Azure Active Directory și solicită Application (Client) ID, Tenant ID și Client Secret. Odată salvate, platforma generează URL-urile dinamice de autorizare (OAuth2 V2.0 Auth Endpoint) pentru obținerea token-urilor.
• Securitatea Credențialelor: Câmpurile destinate cheilor secrete încapsulează un strat de protecție vizuală prin blurare nativă (CSS Masking), cheile fiind vizibile în clar doar în momentul editării sau la focus direct.

2. Schimbul de Token-uri și Reîmprospătarea Automatizată (Refresh Token Engine)

Gestionarea sesiunilor API este complet automatizată, asigurând o conexiune stabilă fără deconectări accidentale:

• Sincronizare OAuth2: La întoarcerea din ecranele de autentificare publice, scripturile interceptează asincron codul de autorizare (Auth Code) și îl schimbă pe un Token de acces criptat, salvat securizat în profilul utilizatorului.
• Motor de Reîmprospătare (Refresh Loop): Deoarece token-urile de acces expiră de regulă după 60 de minute, CRM-ul verifică timestamp-ul sesiunii la fiecare interacțiune cu agenda. Dacă token-ul a expirat, sistemul folosește cheia refresh_token în fundal pentru a obține o nouă sesiune fără a întrerupe activitatea utilizatorului.
• Deconectare Sigură: Utilizatorii pot revoca manual accesul oricând, acțiune care șterge token-urile din baza de date și dezactivează instantaneu monitorizarea fluxurilor.

3. Sincronizarea Inbound prin Webhook-uri Live (Google & Graph Listener)

Oglindirea modificărilor efectuate direct în aplicațiile mobile sau web ale Google și Outlook către CRM este controlată de receptori asincroni (Listeners):

• Validarea Protocolului Microsoft Graph: La activarea contului Outlook, platforma înregistrează un subscription live pe resursa de evenimente (/me/events). Scriptul rezolvă instant handshake-ul obligatoriu cerut de Microsoft, returnând codul de validare (Validation Token) în format text/plain în mai puțin de 10 secunde.
• Protecție Anti-Spoofing: Fiecare notificare primită din serverele Microsoft este validată prin compararea cheii unice clientState utilizând funcții stricte (hash_equals) rezistente la atacuri de tip timing.
• Procesarea Modificărilor: Webhook-urile interceptează tipul de schimbare (created, updated, deleted). La ștergerea unui eveniment din Google sau Outlook, CRM-ul elimină automat programarea corelată și curăță alarmele din Remindere Inteligente.

4. Algoritmul de Control Anti-Buclă (Sync Echo Shield)

Sincronizarea bidirecțională reală prezintă riscul tehnic de a genera bucle infinite (CRM trimite la Google → Google confirmă prin Webhook → CRM rescrie și retrimite la Google). Zarina CRM rezolvă această problemă printr-un algoritm special:

• Hash Stabil de Conținut: La fiecare export sau import, sistemul compilează un hash SHA-1 unic format din combinarea elementelor de bază: Titlu, Descriere, Dată Început, Dată Sfârșit și Status (sync_content_hash).
• Fereastra de Ecou (Echo Window): Atunci când CRM modifică un eveniment, îl marchează cu originea sync_origin='crm' și salvează amprenta temporală. Dacă în următoarele 90 de secunde sosește un webhook de la Google sau Outlook cu același conținut (hash identic), platforma îl recunoaște ca fiind un ecou al propriei acțiuni și **sare** peste procesare (Skip Echo).
• Igienizarea Jurnalului: Webhook-urile redundante sau apelurile multiple generate de provideri pe ferestrele de actualizare (updatedMin) sunt deduplicate instant, salvând resursele serverului.

5. Rularea din Cron și Reînnoirea Canalelelor (Subscription Renewal)

Canalele de monitorizare live au durate de viață limitate de către provideri (max. 30 de zile pentru Google Watch și max. 3 zile pentru Microsoft Graph):

• Throttling Intern (sync-renew-runner.php): Integrat în cronul global al CRM-ului, scriptul rulează verificări de siguranță. Pentru a proteja performanța serverului, execuția reală a reînnoirii este limitată la o singură rulare la fiecare 6 ore.
• Recreare Automatizată: Scriptul scanează tabelele și detectează canalele care se apropie de expirare (mai puțin de 2 zile pentru Google sau sub 12 ore pentru Outlook). Canalele vechi sunt închise curat, fiind generate noi canale asincrone cu adrese HTTPS publice.
• Jurnalizare Tehnică: Toate acțiunile de reînnoire, erorile de rețea sau detaliile codurilor HTTP returnate sunt înregistrate în tabela locală de loguri pentru audit tehnic.

6. Workspace Management și Interfața Grafică Interactivă

Toate fluxurile API se reflectă într-o agendă comercială interactivă bazată pe biblioteca FullCalendar:

• Team Workspace (Filtrare Multi-User): Permite operatorilor vizualizarea agendei globale a întregii echipe sau izolarea programărilor unui singur agent. Dacă se accesează o programare de pe o fișă de client, CRM-ul deblochează un router inteligent care deschide automat modalul de editare corespunzător.
• Interfață Drag & Drop / Resize: Data și ora unui eveniment pot fi modificate vizual prin glisarea cardului în calendar sau prin întinderea marginilor acestuia. Modificarea asincronă salvează instant noile coordonate temporale, recalculează alarmele și împinge automat noile date în Google și Outlook (Outbound Sync).
• Sistem de Notificare S.O.S Anti No-Show: Legat direct de componenta de alertare, modulul trimite automat mesaje de notificare personalizate pe telefonul clientului (SMS / WhatsApp) înainte de începerea întâlnirii, reducând rata de absență la vizite sau apeluri programate.

Beneficiile Majore ale Sincronizării Agendei

• Automatizare Fără Efort: Echipa folosește în continuare aplicațiile preferate de calendar pe telefon (Google/Outlook), iar toate datele, modificările și clienții noi se actualizează automat în CRM.
• SLA Financiar și Operațional: Sincronizarea corectă a vizitelor comerciale și a apelurilor de suport se reflectă direct în performanța analizată în Rapoarte și statistici.
• Integritate Tehnică: Algoritmul anti-buclă și mecanismul de reînnoire din cron garantează funcționarea neîntreruptă a telemetriei, fără dublări de date sau blocaje de rețea.