FieldOrchestrator

DocumentationRéférenceRéférence API

Référence API

Référence complète pour l'API REST FieldOrchestrator : authentification, périmètres, points de terminaison, limites de débit, codes d'erreur et politique de versionnement.

Vue d'ensemble

URL de Base

/api/v1/

Tous les points de terminaison versionnés sont préfixés par /api/v1/

Format

JSON

Tous les corps de requête et de réponse utilisent application/json

Auth

Clé API

Transmettez votre clé dans l'en-tête de requête x-api-key

L'API REST FieldOrchestrator est conçue pour les intégrations système à système — connectant les systèmes ERP, les agents de synchronisation mobile et les plateformes de conformité à la couche de données FieldOrchestrator. Tous les points de terminaison nécessitent une authentification par clé API. L'API utilise des corps de requête et de réponse JSON cohérents pour toutes les ressources.

Authentification

Incluez votre clé API dans l'en-tête de requête x-api-key à chaque requête. Il n'y a pas de session ni de flux OAuth — chaque requête est authentifiée indépendamment.

En-tête de Requête Exemple

x-api-key: sk_live_xxxxxxxxxxxxxxxxxxxxxxxx

Les clés API sont limitées — chaque clé est autorisée pour exactement un ensemble d'opérations. L'utilisation d'une clé sur un point de terminaison hors de son périmètre retourne HTTP 403 SCOPE_UNAUTHORIZED. Créez des clés séparées pour chaque intégration afin de respecter le principe du moindre privilège.

Périmètres des Clés API

Trois périmètres sont disponibles. Chaque périmètre accorde un accès en écriture ou en lecture à un domaine de données spécifique. Les clés sont créées et gérées dans Paramètres → Clés API (rôle ADMIN requis).

Périmètre	Opérations Autorisées	Cas d'Usage Typique
`INGEST_SALES`	Importer des enregistrements de données de sell-out	Pipeline de données ERP ou pharmacie
`SYNC_VISITS`	Téléverser des enregistrements de visite depuis la file d'attente hors-ligne mobile	Agent de synchronisation en arrière-plan de l'application mobile
`WORKFLOW_LOG`	Écrire des évènements d'audit de workflow	Systèmes de conformité ou d'automatisation externes

Points de Terminaison

Données de Sell-Out

POST/api/v1/sales-dataINGEST_SALES

Importer des enregistrements de sell-out

Import en masse des enregistrements de sell-out. Corps de la requête : tableau d'objets de vente (voir Guide d'Intégration pour le schéma). Retourne un résumé d'import incluant le nombre de lignes insérées, mises à jour et rejetées.

Synchronisation des Visites

POST/api/v1/sync/visitsSYNC_VISITS

Téléverser en masse des enregistrements de visites hors-ligne

Téléverser un tableau d'objets de journal de visite depuis la file d'attente hors-ligne mobile. Ce point de terminaison est idempotent — les enregistrements en doublon avec le même identifiant de visite sont ignorés sans erreur.

Professionnels de Santé

GET/api/v1/hcps

Lister les PS

Retourne une liste paginée de fiches PS. Paramètres de requête supportés : territory (filtre par ID de territoire), tier (A, B ou C), search (correspondance partielle de nom), page et limit (maximum 100 par page).

GET/api/v1/hcps/:id

Obtenir une fiche PS

Retourne la fiche PS complète pour l'identifiant donné, incluant le tier, le territoire, la date de dernière visite et les métriques d'engagement.

Plans de Tournée

GET/api/v1/routes

Obtenir les plans de tournée d'un délégué à une date donnée

Retourne le plan de tournée approuvé pour un délégué à la date spécifiée. Paramètres de requête requis : date (YYYY-MM-DD) et rep (ID du délégué). Retourne les arrêts dans l'ordre de visite optimisé avec les fenêtres horaires et les détails des PS.

Santé

GET/api/health

Vérification de disponibilité du service

Retourne une réponse de disponibilité légère depuis le processus applicatif sans sonder les dépendances externes. Aucune authentification requise. Adapté aux sondes d'équilibrage de charge et d'uptime.

GET/api/health/db

Vérification de disponibilité de la base

Retourne l'état courant de connectivité à la base de données. Aucune authentification requise. À utiliser pour les sondes de readiness et le diagnostic opérateur, pas pour les sondes publiques à haute fréquence.

Limites de Débit

Les requêtes API sont limitées en débit par clé. Dépasser la limite retourne HTTP 429 avec un en-tête Retry-After indiquant le nombre de secondes à attendre avant de réessayer.

Périmètre	Limite
`INGEST_SALES`	1 000 enregistrements / minute
`SYNC_VISITS`	500 enregistrements / minute
`WORKFLOW_LOG`	200 évènements / minute

Réponse en Cas de Limite Dépassée

HTTP/1.1 429 Too Many Requests
Retry-After: 30
Content-Type: application/json

{
  "error": "RATE_LIMITED",
  "message": "Rate limit exceeded. Retry after 30 seconds.",
  "statusCode": 429
}

Réponses d'Erreur

Toutes les réponses d'erreur utilisent un format d'enveloppe JSON cohérent. Les codes d'erreur lisibles par machine permettent aux intégrations de gérer les erreurs de manière programmatique.

Format de la Réponse d'Erreur

{
  "error": "string  // machine-readable error code",
  "message": "string  // human-readable description",
  "statusCode": 400
}

Code d'Erreur	HTTP	Description
`INVALID_API_KEY`	401	La clé API est manquante, malformée ou a été révoquée.
`SCOPE_UNAUTHORIZED`	403	La clé n'a pas la permission pour le point de terminaison demandé.
`VALIDATION_ERROR`	400	Le corps de la requête ou les paramètres de requête ont échoué à la validation du schéma. Le champ message décrit les champs invalides.
`RATE_LIMITED`	429	La limite de débit par clé a été dépassée. Réessayez après la durée indiquée dans l'en-tête Retry-After.
`NOT_FOUND`	404	La ressource demandée n'existe pas.

Politique de Versionnement

Version Actuelle

/api/v1/

Stable et rétrocompatible. Aucun changement cassant ne sera introduit.

Changements Cassants

Nouvelle version majeure uniquement

Les changements cassants ne sont introduits que dans une nouvelle version majeure (ex. /api/v2/).

Préavis de Dépréciation

12 mois

Les versions dépréciées reçoivent un préavis de 12 mois avant leur retrait.

Le contrat /api/v1/ est stable. Vous pouvez construire des intégrations contre celui-ci sans craindre des changements cassants silencieux. Les avis de dépréciation de version sont annoncés par e-mail à l'adresse de contact de votre compte SymbioWave et dans les Notes de Version de la plateforme.

Support d'intégration API

Questions sur l'API, les intégrations personnalisées ou les exigences en matière de webhooks ? Contactez notre équipe.

support@symbiowave.com