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ément | Rôle |
|---|---|
| Un serveur OAuth2 et un client déclaré pour Save2ERP | Connexion 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és | Chaque 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
- Le système cible génère un document Word, avec les propriétés
S2E_SystemKey,S2E_ObjectType,S2E_ObjectKeyet, facultativement,S2E_FileName. - L'utilisateur l'ouvre dans Word et clique sur le bouton de sauvegarde du panneau.
- Le serveur Save2ERP appelle
POST /attachments/checkavec l'objet et le nom du fichier, pendant que Word lit le document. - Si le fichier n'existe pas, le serveur appelle
POST /attachmentsaveconNameConflict: FAIL. - 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é aveconNameConflictréglé sur l'action choisie. - 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: Bearerde 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
messaged'une erreur fonctionnelle (4xx) tel quel : écrivez-le dans la langue de l'utilisateur.