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é | Obligatoire | Valeur |
|---|---|---|
S2E_SystemKey | Oui | Nom du système, identique au nom déclaré dans la configuration du serveur Save2ERP (pour SAP : système logique, par exemple P01CLNT100). |
S2E_ObjectType | Oui | Type de l'objet, tel que vos services l'attendent dans objectType. |
S2E_ObjectKey | Oui | Identifiant de l'objet, tel que vos services l'attendent dans objectKey. |
S2E_FileName | Non | Nom de fichier proposé à l'utilisateur, avec ou sans extension (le panneau retire l'extension et ajoute celle du format choisi). |
S2E_TemplateId | Non | Identifiant 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 cible | Ce que voit l'utilisateur |
|---|---|
201 avec message | Le message, sous le titre « Succès ». |
201 sans message | Le message de réussite du panneau, dans sa langue. |
409 + FILE_ALREADY_EXISTS | La vue « Doublon détecté », avec les actions de allowedActions et « Choisir un autre nom ». |
Autre 4xx | Le message du système cible, tel quel. Seuls code et message sont transmis au panneau. |
401 | Save2ERP 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érification | Le document est envoyé sans vérification (service absent). |
Points d'attention
- Messages : le
messageest 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_EXISTSa un sens particulier ; les autres codes sont libres. - Actions permises :
allowedActionspeut dépendre du type d'objet. Renvoyez les mêmes actions à la vérification et dans un409. - 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
409si besoin. - Droits : les services s'exécutent avec les droits de l'utilisateur connecté. Un utilisateur sans droit sur l'objet reçoit
403avec un message explicite. existingFile: facultatif, mais utile à l'utilisateur pour choisir entre remplacer et créer une version.modifiedByest 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éponse200avecexistsetallowedActions,422pour un objet inconnu. - [ ]
POST /attachments:201,409+FILE_ALREADY_EXISTS+allowedActions, traitement deonNameConflict. - [ ]
GET /attachments/healthcheck: réponse200. - [ ] Aucune erreur fonctionnelle en
404ou405. - [ ] Documents générés avec les propriétés
S2E_…. - [ ] Mode concepteur, si vous le proposez :
GET /attachments/permissionsetPOST /attachments/readTemplateXml(libellés réservés aux concepteurs, valeurs permises à tout lecteur de l'objet), etS2E_TemplateIddans les modèles. - [ ] Tests faits avec la page
/testet un document réel (voir Tester son implémentation).