Guide d'Intégration
Référence d'architecture, configuration des connecteurs ERP, spécification des flux de données de sell-out, exigences réseau et procédures de mise à jour pour les déploiements sur site.
Architecture de Déploiement Sur Site
Dans un déploiement sur site, toutes les données organisationnelles — fiches PS, journaux de visite, plans de tournée, historique de sell-out — restent exclusivement sur l'infrastructure contrôlée par le client. Seules des requêtes de calcul anonymisées et non persistantes transitent vers le moteur FieldOrchestrator.
┌─────────────────────────────────────────────────────────────┐
│ CLIENT INFRASTRUCTURE │
├─────────────────────────────────────────────────────────────┤
│ │
│ ┌──────────────────────────────────────────────────────┐ │
│ │ ERP / CRM (e.g. Sage X3, Veeva CRM) │ │
│ └──────────────────────────┬───────────────────────────┘ │
│ │ Data extraction │
│ ▼ │
│ ┌──────────────────────────────────────────────────────┐ │
│ │ FieldOrchestrator Integration Service │ │
│ │ (on-prem · scheduled sync · delta extraction) │ │
│ └──────────────────────────┬───────────────────────────┘ │
│ │ Upsert to local database │
│ ▼ │
│ ┌──────────────────────────────────────────────────────┐ │
│ │ FieldOrchestrator Database │ │
│ │ (operational data · stays on your infrastructure) │ │
│ └──────────────────────────┬───────────────────────────┘ │
│ │ Read │
│ ▼ │
│ ┌──────────────────────────────────────────────────────┐ │
│ │ FieldOrchestrator Web Interface │ │
│ │ (managers + representatives · browser / PWA) │ │
│ └──────────────────────────┬───────────────────────────┘ │
│ │ API calls (HTTPS · port 443) │
└─────────────────────────────┼───────────────────────────────┘
│ outbound only
▼
┌─────────────────────────────────────────────────────────────┐
│ FIELDORCHESTRATOR ENGINE (SymbioWave) │
│ │
│ Route optimization compute · AI pre-call intelligence │
│ Visit Impact Score scoring engine · Analytics processing │
│ │
│ Managed service · stateless · retains no customer data │
└─────────────────────────────────────────────────────────────┘Qui s'Exécute Où
Sur l'Infrastructure Client
Vos serveurs · votre réseau · vos données
- Interface web — application Next.js servie depuis votre infrastructure
- Base de données PostgreSQL — toutes les données opérationnelles (PS, visites, tournées, sell-out)
- Service d'intégration — agent de synchronisation ERP/CRM (s'exécute sur votre ordonnanceur)
- Toutes les données utilisateur et DCP — ne quittent jamais le réseau client
Moteur FieldOrchestrator
Managé par SymbioWave · sans état · propriétaire
- Calcul d'optimisation des tournées — moteur de planification multi-contraintes
- Intelligence IA pré-visite — génération des briefings de visite
- Moteur de scoring Visit Impact Score — calcul d'attribution des prescriptions
- Traitement analytique — agrégation et calcul des KPI
Le moteur FieldOrchestrator est un service managé et propriétaire — aucun code source n'est livré et aucune configuration de fournisseur côté client n'est requise. Les capacités du moteur sont accessibles via une identité de déploiement émise par SymbioWave sur un contrat HTTPS authentifié unique. Les appels à l'API du moteur sont sans état : les entrées de calcul sont traitées en mémoire et aucune donnée client n'est conservée après le retour de la réponse.
Le Modèle à Clé API Unique
Les déploiements sur site nécessitent exactement une identité de déploiement gérée par SymbioWave pour faire fonctionner les capacités de calcul avancées.
Une identité de déploiement gérée
FO_WORKLOAD_IDENTITY_FILE
Aucun compte de fournisseur cloud, aucune clé API de fournisseur d'IA, aucun identifiant de service cartographique et aucun autre compte de service externe ne sont requis sur l'infrastructure client. SymbioWave émet une identité de déploiement signée lors du bootstrap et l'utilise pour autoriser toutes les capacités du moteur via un contrat HTTPS authentifié unique.
Intégration Sage X3
FieldOrchestrator est livré avec un service d'intégration Sage X3 préconstruit qui synchronise les données maîtres des PS, les données des délégués et les enregistrements de sell-out sur une base planifiée.
Workflow de Synchronisation
Extraction
Sage X3 expose les données des PS (clients classifiés comme professionnels de santé), les données des délégués et les données de sell-out via API REST ou export CSV planifié. Les deux méthodes d'extraction sont supportées.
Synchronisation Delta
Le service d'intégration interroge Sage toutes les 6 heures et extrait uniquement les enregistrements modifiés depuis la dernière synchronisation, basé sur les horodatages de modification. Une resynchronisation complète est disponible à la demande.
Transformation
Les champs du format Sage sont mappés vers le schéma de données PS et ventes de FieldOrchestrator. Un document de mapping au niveau des champs est fourni par SymbioWave lors de l'implémentation.
Chargement
Les enregistrements sont insérés ou mis à jour (upsert) dans la base de données locale. Les enregistrements existants sont mis à jour ; les nouveaux enregistrements sont insérés. Aucun doublon n'est créé.
L'état de la synchronisation, le nombre de lignes et les détails des erreurs sont disponibles dans Administration → Intégrations → Journal de Synchronisation Sage.
Intégration Veeva CRM / Salesforce
Les données maîtres des PS et l'historique des activités terrain peuvent être synchronisés depuis Veeva CRM ou Salesforce Health Cloud via leurs API REST respectives.
Veeva CRM
Connecteur préconstruit disponibleSymbioWave fournit un connecteur Veeva CRM préconstruit. Contactez votre ingénieur d'implémentation pour le guide de configuration du connecteur et la spécification de mapping des champs.
Salesforce Health Cloud
Intégration API RESTIntégration via l'API REST Salesforce. Les fiches maîtres des PS et l'historique des activités sont synchronisés comme référence pour le registre PS de FieldOrchestrator. Contactez votre ingénieur d'implémentation pour la mise en place.
Spécification du Flux de Données de Sell-Out
Les données de sell-out peuvent être livrées sous forme de fichiers CSV ou XLSX (téléversement manuel) ou poussées via le point de terminaison API INGEST_SALES (automatisé). Les deux méthodes utilisent le même schéma de colonnes.
| Colonne | Type | Description |
|---|---|---|
hcp_code | string | Identifiant PS — doit correspondre à un code PS existant |
product_code | string | Identifiant produit du catalogue de la plateforme |
brick_code | string | Code brique géographique identifiant la zone de vente |
period | YYYY-MM | Mois de reporting au format ISO année-mois (ex. 2026-02) |
quantity | integer | Nombre d'unités vendues durant la période |
value_tnd | decimal | Chiffre d'affaires en devise locale pour la période |
Exigences Réseau
Les déploiements sur site ont une empreinte réseau minimale. Seule une connexion HTTPS sortante unique est requise.
| Direction | Destination | Port | Finalité |
|---|---|---|---|
| Sortant | engine.fieldorchestrator.symbiowave.com | 443 (HTTPS) | API du moteur FieldOrchestrator |
Aucune connexion entrante de SymbioWave n'est requise. Tout transfert de données est initié par l'installation sur site. Votre pare-feu doit uniquement autoriser le HTTPS sortant vers le nom d'hôte unique de l'API du moteur.
Exigences Matérielles
Spécifications minimales pour un déploiement sur site en production desservant jusqu'à 50 utilisateurs simultanés. Pour les déploiements plus importants, consultez HARDWARE_REQUIREMENTS.md inclus dans votre package d'installation.
vCPU
4 cores
Minimum
RAM
8 GB
Minimum
Stockage
100 GB SSD
NVMe recommandé
Utilisateurs
≤ 50
Sessions simultanées
Pour les déploiements avec plus de 50 utilisateurs, plusieurs territoires géographiques ou des imports fréquents de données de sell-out, consultez votre ingénieur d'implémentation SymbioWave pour une recommandation matérielle dimensionnée.
Procédure de Mise à Jour
Les mises à jour de FieldOrchestrator sont distribuées sous forme d'images Docker. La procédure de mise à jour est entièrement scriptée et réalise un déploiement sans interruption via un redémarrage progressif.
- 1Consultez les notes de version pour la nouvelle version (voir Notes de Version dans cette documentation).
- 2Créez une sauvegarde de la base de données : exécutez ./backup.sh depuis votre répertoire d'installation. Un dump PostgreSQL horodaté est créé.
- 3Lancez la mise à jour : exécutez ./update.sh. Le script extrait la dernière image Docker, applique les migrations de base de données et redémarre les services.
- 4Vérifiez l'état du déploiement dans Administration → Santé du Système. Tous les indicateurs de service doivent passer au vert.
./backup.shCrée un dump PostgreSQL horodaté. Planifiez via cron pour des sauvegardes automatisées.
./update.shExtrait la dernière image Docker, applique les migrations et effectue un redémarrage progressif sans interruption.
Support d'intégration
Votre ingénieur d'implémentation est disponible pendant l'intégration. Pour les problèmes après la mise en production, contactez notre équipe support.