Aller au contenu

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 (APIBASE dans 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, un message dé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 :

StatutSens
200 / 201Vérification faite / document enregistré.
400Requête mal formée (champ manquant ou invalide).
401Jeton absent, invalide ou expiré.
403L'utilisateur n'a pas le droit de lire ou de modifier cet objet.
409Un fichier du même nom est déjà joint à l'objet (envoi uniquement).
422L'objet (ou le modèle) n'existe pas, ou son type est inconnu.
5xxErreur 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 :

json
{
  "objectType": "BUS2000126",
  "objectKey": "0000012345",
  "fileName": "contrat.docx"
}

Réponse 200 :

json
{
  "exists": true,
  "allowedActions": ["REPLACE", "NEW_VERSION"],
  "existingFile": {
    "version": "3",
    "modifiedAt": "2026-10-12T14:35:00+02:00",
    "modifiedBy": "Marie Dupont"
  }
}
ChampObligatoireContenu
existsOuitrue si un fichier de ce nom est déjà joint à l'objet.
allowedActionsOuiActions 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.
existingFileNonInformations 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 :

json
{
  "objectType": "BUS2000126",
  "objectKey": "0000012345",
  "fileName": "contrat.docx",
  "fileContent": "<document encodé en base64>",
  "onNameConflict": "FAIL"
}
  • fileName se termine toujours par l'extension du format choisi (.docx ou .pdf), et fileContent est 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 :

onNameConflictLe fichier n'existe pasIl existe, action permiseIl existe, action non permise
FAILFichier créé409409
REPLACEFichier crééFichier existant supprimé, nouveau fichier créé409
NEW_VERSIONFichier crééNouvelle version du fichier existant409

Réponse 201, avec un message facultatif, que le panneau affiche à la place du sien :

json
{ "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) :

json
{
  "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.

json
{ "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.

json
{ "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 :

json
{
  "templateId": "OFFRE-2026",
  "content": "values",
  "objectType": "BUS2000126",
  "objectKey": "0000012345"
}
ChampObligatoireContenu
templateIdOuiIdentifiant du modèle (propriété S2E_TemplateId du document).
contentOuilabels : le libellé de chaque balise ; values : les valeurs de l'objet.
objectType, objectKeyAvec valuesL'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
<?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).
  • labels est réservé aux concepteurs de modèles : répondez 403 aux autres utilisateurs.
  • values doit 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 son code et son message.