Aller au contenu

Implémenter les services ​

Cette page complète le contrat d'API avec ce que Save2ERP fait de chaque réponse, et les points à ne pas oublier.

Générer les documents Word ​

Lorsqu'il génère un document Word, le système cible doit y écrire ces propriétés personnalisées (propriétés de document, pas des champs visibles dans le texte) :

PropriétéObligatoireValeur
S2E_SystemKeyOuiNom du système, identique au nom déclaré dans la configuration du serveur Save2ERP (pour SAP : système logique, par exemple P01CLNT100).
S2E_ObjectTypeOuiType de l'objet, tel que vos services l'attendent dans objectType.
S2E_ObjectKeyOuiIdentifiant de l'objet, tel que vos services l'attendent dans objectKey.
S2E_FileNameNonNom de fichier proposé à l'utilisateur, avec ou sans extension (le panneau retire l'extension et ajoute celle du format choisi).
S2E_TemplateIdNonIdentifiant du modèle Word, tel que le service des modèles l'attend dans templateId : active le mode concepteur pour ce document.

S2E_LabelsShown est réservée à Save2ERP, qui l'écrit dans le document tant que les libellés des balises sont affichés : ne la générez jamais.

Save2ERP transmet S2E_ObjectType et S2E_ObjectKey tels quels à vos services.

Ce que Save2ERP fait de chaque réponse ​

Réponse du système cibleCe que voit l'utilisateur
201 avec messageLe message, sous le titre « Succès ».
201 sans messageLe message de réussite du panneau, dans sa langue.
409 + FILE_ALREADY_EXISTSLa vue « Doublon détecté », avec les actions de allowedActions et « Choisir un autre nom ».
Autre 4xxLe message du système cible, tel quel. Seuls code et message sont transmis au panneau.
401Save2ERP renouvelle le jeton, ou demande à l'utilisateur de se reconnecter.
5xx, ou vérification sans exists booléen« Erreur du système cible », sans détail. La réponse est écrite dans les logs du serveur.
Pas de réponse dans le délai configuré (60 s par défaut)« Le système cible est momentanément indisponible ».
404 ou 405 sans code sur la vérificationLe document est envoyé sans vérification (service absent).

Points d'attention ​

  • Messages : le message est affiché tel quel. Rédigez-le dans la langue de l'utilisateur (pour SAP : sa langue de connexion), sans détail technique.
  • Codes : ils servent au comportement du panneau, jamais à l'affichage. Seul FILE_ALREADY_EXISTS a un sens particulier ; les autres codes sont libres.
  • Actions permises : allowedActions peut dépendre du type d'objet. Renvoyez les mêmes actions à la vérification et dans un 409.
  • Comparaison des noms : la même règle pour les deux services, sinon la vérification ne détecte pas un doublon que l'envoi refuse.
  • Concurrence : un autre utilisateur peut enregistrer un fichier du même nom entre la vérification et l'envoi. L'envoi doit donc toujours contrôler lui-même le doublon et répondre 409 si besoin.
  • Droits : les services s'exécutent avec les droits de l'utilisateur connecté. Un utilisateur sans droit sur l'objet reçoit 403 avec un message explicite.
  • existingFile : facultatif, mais utile à l'utilisateur pour choisir entre remplacer et créer une version. modifiedBy est un nom lisible, pas un identifiant technique.
  • Taille : prévoyez des documents jusqu'à environ 37 Mo.

Liste de contrôle ​

  • [ ] Client OAuth2 déclaré, avec l'adresse de retour du serveur Save2ERP et le scope des services.
  • [ ] POST /attachments/check : réponse 200 avec exists et allowedActions, 422 pour un objet inconnu.
  • [ ] POST /attachments : 201, 409 + FILE_ALREADY_EXISTS + allowedActions, traitement de onNameConflict.
  • [ ] GET /attachments/healthcheck : réponse 200.
  • [ ] Aucune erreur fonctionnelle en 404 ou 405.
  • [ ] Documents générés avec les propriétés S2E_….
  • [ ] Mode concepteur, si vous le proposez : GET /attachments/permissions et POST /attachments/readTemplateXml (libellés réservés aux concepteurs, valeurs permises à tout lecteur de l'objet), et S2E_TemplateId dans les modèles.
  • [ ] Tests faits avec la page /test et un document réel (voir Tester son implémentation).