CRM — contacts, timeline, pipeline & scoring

Le CRM du Hub a été refondu autour d'un party model : la fiche « client » devient un contact — personne ou organisation — porteur de rôles multiples (client, prospect, fournisseur…), de coordonnées structurées, de relations entre fiches et de champs personnalisés. S'y ajoutent une timeline unifiée, des tâches de relance, un pipeline commercial (opportunités) et un score de santé.

• Base URL — prod : https://api.puwapi.com · dev : http://localhost:5200
• Auth : JWT. Le CRM fait partie du cœur du hub : accessible à tous les plans (pas de gating).

Contacts¶

Base : /api/customers

Méthode	Route	Rôle
GET	/api/customers?role=&kind=	Lister (filtres rôle / type)
GET	/api/customers/{id}	Détail (avec relations)
POST · PATCH · DELETE	/api/customers[/{id}]	Créer / modifier / supprimer

Le contact porte : kind (Person | Organization), roles[] (défaut ["client"]), emails[] / phones[] / addresses[] structurés (les scalaires email / phone reflètent la première entrée), website, vatNumber, ownerUserId, customFields (objet libre validé par les définitions du tenant), notes.

Relations entre fiches (dirigées : employee_of, manager_of, parent_of, subsidiary_of, billing_contact, partner_of, other) :

Méthode	Route
POST · DELETE	/api/customers/{id}/relations[/{relationId}]

Champs personnalisés (définis par organisation, types alignés sur Forms) :

Méthode	Route
GET · PUT · DELETE	/api/customers/fields[/{key}]

Timeline & activités¶

La timeline d'un contact est composée en lecture : activités CRM + factures émises + rendez-vous, fusionnés et triés du plus récent au plus ancien.

Méthode	Route	Rôle
GET	/api/customers/{id}/timeline	Timeline unifiée
POST	/api/customers/{id}/activities	Ajouter (note, appel, email, réunion, tâche)
PATCH · DELETE	/api/customers/activities/{id}	Compléter ({completed}) / supprimer
GET	/api/customers/tasks	Relances à faire (tâches ouvertes, tri échéance)
GET	/api/customers/{id}/score	Score de santé (voir plus bas)

Une activité porte une source (manual | system) : les entrées automatiques (ex. e-mails journalisés) sont marquées « Auto » dans l'interface.

Pipeline commercial (opportunités)¶

Chaque établissement a un pipeline aux étapes personnalisables ([{key, label, probability}] ; défaut : prospection 10 % → qualifié 25 % → proposition 50 % → négociation 75 %). Les deals s'y déplacent par glisser-déposer (position flottante, même mécanique que le Kanban de Work).

Méthode	Route	Rôle
GET	/api/pipelines · /api/pipelines/{id}/board	Pipelines · board (deals ouverts par étape + prévision pondérée Σ valeur×probabilité)
POST · PATCH · DELETE	/api/pipelines[/{id}]	CRUD (suppression refusée s'il reste des deals)
GET · POST · PATCH · DELETE	/api/deals[/{id}] (?customerId= sur la liste)	CRUD des opportunités
POST	/api/deals/{id}/move	Déplacer {stageKey, position?}
POST	/api/deals/{id}/win · /lose · /reopen	Gagné / perdu ({reason?}) / rouvert — idempotents

Un deal est lié à un contact (customerId) : ses opportunités apparaissent sur sa fiche.

Score de santé¶

GET /api/customers/{id}/score → {score 0-100, risk low|medium|high, lastInteractionAt, signals[]}. Calculé à la volée depuis les données déjà en base (récence d'interaction, factures en retard / CA encaissé, opportunités ouvertes/gagnées/perdues sur 90 j, rendez-vous à venir / non honorés, relances en retard) — aucun appel cross-service.

Surfaces machine-à-machine¶

• Intégration par clé API Hub (phk_live_…, en-tête X-Server-API-Key) — api/public/hub : GET customers, POST customers/bulk, POST deals/bulk (imports). C'est la surface qu'utilise le serveur MCP Puwapi — voir Importer des données avec le serveur MCP Puwapi.
• Interne : POST /api/customers/internal/log-email (X-Internal-Secret, fail-closed) journalise un e-mail comme activité system sur le contact résolu par adresse — le hook d'auto-log utilisé par la messagerie.