Contrat d'API
Le contrat de référence est un fichier OpenAPI 3.1, en anglais, version 2.1.0 : télécharger attachments-openapi.yaml. Il peut être ouvert dans tout éditeur OpenAPI (Swagger Editor, Postman…). Cette page en résume l'essentiel.
Règles communes
- Adresses : les chemins ci-dessous s'ajoutent à l'adresse de base de l'API REST du système cible (
APIBASEdans la configuration de Save2ERP). Ce sont les chemins par défaut : chacun peut être changé dans la configuration (voir Configurer le serveur). - Authentification : jeton d'accès OAuth2 de l'utilisateur, dans
Authorization: Bearer. Un en-tête de clé d'API supplémentaire peut être configuré si une passerelle l'exige. - SAP uniquement : le serveur ajoute le paramètre
sap-client(mandant) à chaque appel. - Toute erreur fonctionnelle porte un
code(lettres majuscules, chiffres et_, 50 caractères au plus) et, facultativement, unmessagedéjà rédigé dans la langue de l'utilisateur. - Même nom de fichier : la règle de comparaison (par exemple sans tenir compte des majuscules) est celle du système cible, et doit être la même pour la vérification et l'envoi.
Statuts HTTP
Chaque statut a un seul sens :
| Statut | Sens |
|---|---|
200 / 201 | Vérification faite / document enregistré. |
400 | Requête mal formée (champ manquant ou invalide). |
401 | Jeton absent, invalide ou expiré. |
403 | L'utilisateur n'a pas le droit de lire ou de modifier cet objet. |
409 | Un fichier du même nom est déjà joint à l'objet (envoi uniquement). |
422 | L'objet (ou le modèle) n'existe pas, ou son type est inconnu. |
5xx | Erreur technique du système cible (aucun détail n'est montré à l'utilisateur). |
Jamais 404 ou 405 pour une erreur fonctionnelle
Une réponse 404 ou 405 sans code à la vérification signifie que le service n'existe pas : Save2ERP envoie alors le document sans vérifier. Sur les services du mode concepteur, elle signifie que le mode concepteur n'est pas disponible. Un objet introuvable répond donc 422, jamais 404.
Vérification avant l'envoi
POST /attachments/check : en lecture seule, rien n'est enregistré ni modifié. C'est un POST pour que le nom du fichier et l'identifiant de l'objet n'apparaissent jamais dans les adresses, et donc dans les logs.
Requête :
{
"objectType": "BUS2000126",
"objectKey": "0000012345",
"fileName": "contrat.docx"
}Réponse 200 :
{
"exists": true,
"allowedActions": ["REPLACE", "NEW_VERSION"],
"existingFile": {
"version": "3",
"modifiedAt": "2026-10-12T14:35:00+02:00",
"modifiedBy": "Marie Dupont"
}
}| Champ | Obligatoire | Contenu |
|---|---|---|
exists | Oui | true si un fichier de ce nom est déjà joint à l'objet. |
allowedActions | Oui | Actions que l'envoi accepterait pour cet objet : REPLACE, NEW_VERSION, les deux, ou aucune (liste vide : seul un autre nom est possible). Toujours vide si exists est false. |
existingFile | Non | Informations sur le fichier existant, affichées à l'utilisateur : version (50 caractères au plus), modifiedAt (date ISO 8601 avec fuseau), modifiedBy (nom de la personne, pas un identifiant technique). Chacune est facultative. |
Envoi du document
POST /attachments :
{
"objectType": "BUS2000126",
"objectKey": "0000012345",
"fileName": "contrat.docx",
"fileContent": "<document encodé en base64>",
"onNameConflict": "FAIL"
}fileNamese termine toujours par l'extension du format choisi (.docxou.pdf), etfileContentest un document de ce format : le système cible en déduit le type du fichier.- La requête est limitée à 50 Mo par Save2ERP, soit environ 37 Mo de document une fois encodé en base64.
onNameConflict (facultatif, FAIL par défaut) indique quoi faire si un fichier du même nom existe :
onNameConflict | Le fichier n'existe pas | Il existe, action permise | Il existe, action non permise |
|---|---|---|---|
FAIL | Fichier créé | 409 | 409 |
REPLACE | Fichier créé | Fichier existant supprimé, nouveau fichier créé | 409 |
NEW_VERSION | Fichier créé | Nouvelle version du fichier existant | 409 |
Réponse 201, avec un message facultatif, que le panneau affiche à la place du sien :
{ "code": "FILE_STORED", "message": "Le fichier contrat.docx a été joint à l'objet 0000012345." }Réponse 409, avec les actions permises pour un nouvel envoi (absentes ou vides : seul un autre nom est possible) :
{
"code": "FILE_ALREADY_EXISTS",
"message": "Un fichier nommé contrat.docx est déjà joint à l'objet 0000012345.",
"allowedActions": ["REPLACE", "NEW_VERSION"]
}Test de connexion
GET /attachments/healthcheck : utilisé par la page de test /test de l'administrateur, pour vérifier la connexion, le jeton et la configuration. Le contenu de la réponse 200 est libre : il est affiché tel quel à l'administrateur.
{ "RESULT": "OK", "SYSTEM": "D01" }Mode concepteur (facultatif)
Le mode concepteur permet au concepteur d'un modèle Word d'afficher le libellé de chaque balise à la place des valeurs de l'objet. Il repose sur deux services facultatifs : un système cible qui ne les fournit pas ne propose jamais le mode concepteur.
Droits de l'utilisateur
GET /attachments/permissions : appelé une seule fois, à la connexion. Save2ERP garde les droits pour toute la session.
{ "templateDesigner": true }Seule la valeur true accorde le droit. Si le service n'existe pas, répond par une erreur ou ne répond pas dans les 5 secondes, l'utilisateur n'a aucun droit et la connexion se poursuit normalement.
XML d'un modèle
POST /attachments/readTemplateXml : en lecture seule, comme la vérification, et pour la même raison : l'identifiant de l'objet n'apparaît jamais dans les adresses, et donc dans les logs.
Requête :
{
"templateId": "OFFRE-2026",
"content": "values",
"objectType": "BUS2000126",
"objectKey": "0000012345"
}| Champ | Obligatoire | Contenu |
|---|---|---|
templateId | Oui | Identifiant du modèle (propriété S2E_TemplateId du document). |
content | Oui | labels : le libellé de chaque balise ; values : les valeurs de l'objet. |
objectType, objectKey | Avec values | L'objet du document (propriétés S2E_ObjectType et S2E_ObjectKey). Absents avec labels. |
Réponse 200 : le XML complet de la partie personnalisée du modèle (application/xml), tel que le système l'écrit dans le document lorsqu'il le génère. Sa racine porte l'espace de noms de cette partie : le panneau s'en sert pour retrouver la partie dans le document.
<?xml version="1.0" encoding="UTF-8"?>
<Document xmlns="urn:exemple:offre">
<Customer><Company>Raison sociale du client</Company><City>Localité</City></Customer>
<Lines><Line><Description>Description de la prestation</Description><Amount>Montant</Amount></Line></Lines>
</Document>- Le panneau remplace chaque élément situé sous la racine par l'élément du même nom reçu : un élément reçu absent du document est ignoré, un élément du document absent du XML reçu reste tel quel. Une section répétée suit le nombre d'éléments reçus (en général un seul pour les libellés).
labelsest réservé aux concepteurs de modèles : répondez403aux autres utilisateurs.valuesdoit rester permis à tout utilisateur qui peut lire l'objet : un document resté sur les libellés doit toujours pouvoir retrouver ses valeurs.- Un modèle inconnu répond
422, avec soncodeet sonmessage.