Documentation

Google Workspace

Compte de service, synchro Agenda, dossiers Drive et envoi Gmail avec suivi.

Fonctionnement

BillBoy utilise un seul compte de service Google avec délégation à l’échelle du domaine. Pour chaque appel d’API, il signe un JWT avec le google_workspace_email de l’utilisateur du CRM comme sujet, de sorte que Google voit l’action comme celle de cet utilisateur : les événements vont dans son agenda, les fichiers dans son Drive, les courriels partent de son Gmail. Pas de OAuth par utilisateur, pas de SDK — du simple HTTP.

La délégation à l’échelle du domaine exige un Google Workspace payant et un accès administrateur. Elle ne fonctionne pas avec des comptes Gmail personnels.

Configuration

Dans Google Cloud, créez un projet, activez les API Calendar, Drive et Gmail, et créez un compte de service. Téléchargez sa clé JSON.
Dans la console d’administration Workspace (Sécurité → Contrôles des API → Délégation à l’échelle du domaine), autorisez l’identifiant client du compte de service avec les portées :
```
https://www.googleapis.com/auth/calendar
https://www.googleapis.com/auth/drive
https://www.googleapis.com/auth/gmail.send
https://www.googleapis.com/auth/gmail.readonly
```
Placez la clé JSON hors de la racine web et pointez GOOGLE_SA_JSON vers elle dans .admin/.env.
Pour chaque utilisateur du CRM, remplissez Courriel Google Workspace (et, au besoin, un identifiant d’agenda autre que primary).
Gardez le cron actif : il vide la file de tâches chaque minute et interroge les agendas toutes les cinq minutes.

Agenda

CRM → Agenda liste les événements avec un État de synchro (Local, Synchronisé, SuppriméÀDistance, Conflit). Créer un événement dans BillBoy le pousse vers Google; les changements faits dans Google Agenda sont rapatriés par jetons de synchro incrémentaux. Les événements peuvent être liés à un contact et une activité, et le champ Événement Google de l’activité l’ouvre dans Google Agenda.

Drive

Chaque contact obtient un dossier {Entreprise}/{Contact}/ sous la racine Drive de l’utilisateur, créé au premier besoin. Les fichiers téléversés depuis l’onglet Fichiers du contact ou l’explorateur Drive vont directement dans Google Drive; le CRM conserve l’identifiant, le lien web, le nom, le type et la taille. Les PDF de soumission et de facture sont enregistrés dans la même arborescence. Utilisez Partager / Copier le lien sur un fichier pour le rendre public.

Gmail

Depuis l’onglet Courriels d’un contact, ou à l’envoi d’une soumission ou facture, composez à partir d’un gabarit. Le message est envoyé par le Gmail de l’utilisateur (il apparaît donc dans ses messages envoyés) et enregistré avec ses identifiants de message et de fil Gmail. Un pixel de suivi et des liens réécrits enregistrent ouvertures, clics et rebonds comme événements; une réponse crée un suivi dans le fil. Le courrier entrant peut aussi être associé aux activités du contact.

Dépannage

401 / unauthorized_client : l’identifiant client n’est pas autorisé pour cette portée dans la console d’administration, ou le courriel Workspace de l’utilisateur est erroné.
Rien ne se synchronise : vérifiez que le cron tourne et consultez Paramètres → File de tâches pour les lignes Échec — la dernière erreur est conservée sur chaque tâche.
Conflits : un événement modifié des deux côtés entre deux interrogations affiche Conflit; ouvrez-le et choisissez la version à conserver.