Aller au contenu

Principe ​

Cette partie s'adresse à l'équipe qui prépare le système cible (l'ERP, par exemple SAP) pour qu'il accepte les documents envoyés par Save2ERP.

Save2ERP ne dépend pas d'un ERP en particulier : il appelle des services REST décrits par un contrat commun, que chaque système cible implémente à sa manière. Aujourd'hui, Save2ERP sait se connecter aux systèmes SAP (voir Système cible : SAP).

Ce que le système cible doit fournir ​

ÉlémentRôle
Un serveur OAuth2 et un client déclaré pour Save2ERPConnexion de l'utilisateur, avec ses propres droits (flux « authorization code » avec PKCE).
Le service de vérification (POST /attachments/check)Indique, avant l'envoi, si un fichier du même nom est déjà joint à l'objet, et quelles actions sont permises.
Le service d'envoi (POST /attachments)Enregistre le document comme pièce jointe de l'objet.
Le service de test (GET /attachments/healthcheck)Permet à l'administrateur de vérifier la connexion depuis la page /test.
Des documents Word préparésChaque document généré porte les propriétés S2E_… qui désignent le système et l'objet (voir Préparer les documents Word).

Le contrat complet est décrit dans Contrat d'API.

Déroulement d'un envoi ​

  1. Le système cible génère un document Word, avec les propriétés S2E_SystemKey, S2E_ObjectType, S2E_ObjectKey et, facultativement, S2E_FileName.
  2. L'utilisateur l'ouvre dans Word et clique sur le bouton de sauvegarde du panneau.
  3. Le serveur Save2ERP appelle POST /attachments/check avec l'objet et le nom du fichier, pendant que Word lit le document.
  4. Si le fichier n'existe pas, le serveur appelle POST /attachments avec onNameConflict: FAIL.
  5. S'il existe, le panneau propose les actions permises (allowedActions), ou applique l'option choisie par l'utilisateur si elle est permise. Le document est alors envoyé avec onNameConflict réglé sur l'action choisie.
  6. Le système cible répond 201, avec ou sans message. S'il fournit un message, le panneau l'affiche tel quel.

Ce que fait le serveur Save2ERP ​

  • Il obtient et renouvelle le jeton OAuth2 de l'utilisateur, et l'envoie dans l'en-tête Authorization: Bearer de chaque appel.
  • Il transmet le corps des requêtes et des réponses tel quel : c'est le système cible qui valide les champs et leurs valeurs.
  • Il n'affiche jamais les détails techniques d'une erreur 5xx à l'utilisateur : il les écrit dans ses logs.
  • Il affiche le message d'une erreur fonctionnelle (4xx) tel quel : écrivez-le dans la langue de l'utilisateur.