Aller au contenu

Médias des objets Sage

En bref

Six objets Sage portent des médias (photos, PDF, pièces justificatives) : articles, tiers, en-têtes de document, écritures comptables, comptes analytiques et immobilisations. Le connecteur les lit, en ajoute, les modifie et les supprime. Il peut aussi ranger les fichiers, que Sage dépose tous à la racine du dossier Multimedia, dans des sous-dossiers par objet.

Où Sage range les médias

Sage enregistre chaque média dans le dossier Multimedia placé à côté du fichier comptable du dossier Sage, et note son chemin dans la table de médias de l'objet. Sans rangement, tous les fichiers sont à la racine de Multimedia.

Objet Table des médias Clé de l'objet
Article F_ARTICLEMEDIA (et la photo F_ARTICLE.AR_Photo) AR_Ref
Tiers F_COMPTETMEDIA CT_Num
Document F_DOCENTETEMEDIA DO_Type, DO_Piece
Écriture comptable F_ECRITURECMEDIA EC_No
Compte analytique F_COMPTEAMEDIA N_Analytique, CA_Num
Immobilisation F_IMMOBILISATIONMEDIA IM_Code

Le connecteur lit toujours un média à l'emplacement enregistré en base, quelle que soit la forme du chemin : relative (.\Multimedia\…), adresse de fichier (file://./Multimedia/…) ou absolue.

Ce que vous pouvez faire

  • Lister les médias d'un objet : nom du fichier, chemin enregistré, commentaire, type de contenu et, pour un document, l'indicateur "à transmettre".
  • Lire le contenu d'un média.
  • Ajouter un média : nom du fichier et contenu encodé en base64, commentaire facultatif.
  • Modifier un média : commentaire, indicateur "à transmettre", ou contenu remplacé à la même place. Un média ne se renomme pas : supprimez-le puis ajoutez-le sous son nouveau nom.
  • Supprimer un média, et selon l'option du connecteur, son fichier.
  • Ranger les fichiers existants en sous-dossiers, par la tâche de fond du connecteur.

Ces opérations passent par l'API v2 (groupe Medias.Medias) et, pour les applications de la version 1, par l'enregistrement d'un objet Media.

Les routes de l'API v2

Chaque objet porteur est désigné par sa clé dans l'adresse :

Objet Adresse
Article /v2/medias/article/{arRef}
Tiers /v2/medias/tiers/{ctNum}
Document /v2/medias/document/{doType}/{doPiece}
Écriture comptable /v2/medias/ecriture/{ecNo}
Compte analytique /v2/medias/analytique/{nAnalytique}/{caNum}
Immobilisation /v2/medias/immobilisation/{imCode}
Méthode Adresse Effet
GET adresse de l'objet Liste des médias de l'objet (sans le contenu)
GET adresse de l'objet + /{fichier} Contenu du fichier
POST adresse de l'objet Ajoute un média ; corps { "fichier", "datas", "commentaire", "transmettre" } ; répond 201 avec le nom et le chemin réellement enregistrés
PATCH adresse de l'objet + /{fichier} Modifie le commentaire, l'indicateur "à transmettre" ou le contenu ; répond 204
DELETE adresse de l'objet + /{fichier} Supprime le média (nom de fichier exact) ; répond 204

Le contenu s'envoie en JSON, encodé en base64 (un préfixe data:…;base64, est accepté). Le connecteur ne pose aucune limite de taille ni d'extension : Sage reste seul juge.

POST /v2/medias/article/BAAR01?targets=BIJOU
Authorization: Bearer <jeton>
Content-Type: application/json

{ "fichier": "photo.jpg", "datas": "<contenu en base64>", "commentaire": "Vue de face" }

Droits et multi-dossier

  • L'objet porteur doit être visible pour l'appelant, sous ses filtres de données (dossier, profil, utilisateur, accès B2B) : sinon la réponse est 404, sans révéler que l'objet existe.
  • Document : droit Voir pour lire les médias, droit Modifier pour en ajouter, en modifier ou en supprimer, selon le type et l'état de la pièce en base.
  • Écriture comptable : droit "EcritureC" de consultation pour lire, de modification pour écrire.
  • Les ajouts, modifications et suppressions sont des écritures de l'API v2 : ils demandent l'option Autoriser les écritures API v2 (Serveur Web) et un dossier cible explicite quand l'utilisateur a accès à plusieurs dossiers.

Le rangement des médias

Le rangement se règle dans l'outil de configuration, écran Médias du groupe Gestion. Il est désactivé par défaut.

Les chemins par défaut

Chaque objet a un modèle de chemin, relatif au dossier Multimedia, modifiable dans la fenêtre Chemins de rangement des médias.

Objet Modèle par défaut Exemple sur le dossier de démonstration
Article Articles\{AR_Ref} .\Multimedia\Articles\BAAR01\
Tiers Tiers\{CT_Num} .\Multimedia\Tiers\CARAT\
Document Documents\{Domaine}\{DO_Tiers} .\Multimedia\Documents\Ventes\CARAT\
Écriture comptable Ecritures\{JO_Num}\{Compte}\{Periode} .\Multimedia\Ecritures\VTE\CARAT\2026-10\
Compte analytique Analytique\{N_Analytique}\{CA_Num} .\Multimedia\Analytique\1\COMMERCIAL\
Immobilisation Immobilisations\{IM_Code} .\Multimedia\Immobilisations\IM001\

Pourquoi ces choix :

  • Document : le numéro et le type de pièce changent au fil des transformations (devis, commande, livraison, facture) ; le domaine et le tiers restent. Pour un document de stock, le tiers est le dépôt, écrit Depot-<n°>.
  • Écriture comptable : journal, puis compte (le compte tiers s'il est renseigné, sinon le compte général), puis période.
  • Compte analytique : un numéro de section n'est unique que dans son plan, d'où le numéro de plan.

Les variables

Une variable s'écrit entre accolades. Ce sont les colonnes de la table de l'objet ({AR_Ref}, {FA_CodeFamille}, {CT_Num}, {DO_Tiers}, {JO_Num}…) et cinq variables calculées par le connecteur :

Variable Valeur Objets
{Domaine} Ventes, Achats, Stocks ou Internes, d'après le type de document Document
{Compte} Compte tiers s'il est renseigné, sinon compte général Écriture comptable
{Periode} Année et mois, AAAA-MM Document (date de pièce), écriture comptable (date du journal)
{Annee} Année, AAAA Document, écriture comptable
{Mois} Mois, MM Document, écriture comptable

Les valeurs sont normalisées en noms de dossier : caractères interdits par Windows et espaces remplacés par _ (BA AR/01 devient BA_AR_01), points finaux retirés, noms réservés de Windows (CON, COM1…) précédés de _, valeur vide remplacée par _SansCle. Deux valeurs qui donnent le même nom partagent le dossier ; les fichiers y restent distincts.

Avec l'option Nom du dossier comme base de rangement, chaque chemin commence par le nom du dossier Sage : .\Multimedia\BIJOU\Articles\BAAR01\. Utile quand plusieurs dossiers Sage partagent le même dossier Multimedia.

Ce qui est rangé, ce qui ne l'est pas

Fichier Traitement
À la racine de Multimedia, quelle que soit la forme de son chemin Rangé dans le dossier de son objet
Déjà dans un sous-dossier, autre que sa destination Laissé en place, sauf avec l'option Forcer le rangement
Déjà à sa destination Rien à faire
Hors du dossier Multimedia Jamais déplacé
Absent du disque Ignoré, compté dans le rapport

Au déplacement :

  • le lien en base est mis à jour dans la forme d'origine du chemin (relative, adresse de fichier ou absolue) ;
  • un fichier de même nom mais de contenu différent déjà présent à la destination n'est jamais écrasé : le fichier rangé prend le nom nom (2).ext, nom (3).ext… ;
  • un fichier dont le chemin dépasserait 259 caractères est raccourci ; s'il ne tient toujours pas, il reste en place et le rapport le signale ;
  • un fichier utilisé par plusieurs objets rangés dans des dossiers différents est copié dans chaque dossier ; l'original n'est supprimé que lorsque plus aucun objet ne l'utilise ;
  • les images optimisées par le connecteur suivent leur fichier : elles sont renommées vers le nouvel emplacement, sans être recalculées.

Simulation obligatoire

Rien n'est déplacé avant une simulation faite avec les réglages en cours. Le bouton Simuler le rangement parcourt tous les dossiers Sage sans rien déplacer et affiche un rapport par dossier : liens lus, fichiers à ranger par objet, fichiers déjà en place ou déjà rangés ailleurs, fichiers absents, hors de Multimedia, renommés, et des exemples de déplacements.

Changer une option ou un chemin, y compris Forcer le rangement, rend la simulation caduque : la tâche de fond ne déplace plus rien et l'écran demande une nouvelle simulation.

La tâche de fond

Quand l'option Ranger les médias est active et la simulation à jour, la tâche de fond du connecteur range les médias de chaque dossier, avant l'optimisation des images :

  • le premier passage, et celui qui suit un changement de réglages, traite tous les médias ;
  • les passages suivants ne traitent que les médias et les objets modifiés depuis le passage précédent ;
  • un passage complet a lieu au moins une fois par semaine ;
  • 2 000 fichiers au plus sont rangés par dossier et par passage : la suite au passage suivant.

Les journaux du connecteur reçoivent le rapport d'un dossier dès qu'il a des fichiers à ranger ou des signalements, le nombre de fichiers rangés, et chaque fichier qui n'a pas pu l'être (il est repris au prochain passage complet). Sans simulation à jour, le passage note un avertissement et ne déplace rien.

Les médias ajoutés par l'API

Rangement actif, un média ajouté par l'API est écrit directement dans le dossier de son objet. Rangement inactif, il est écrit à la racine de Multimedia, comme le fait Sage, sous un nom libre (nom (2).ext si le nom est pris).

Supprimer un média

Par défaut, supprimer un média retire seulement son lien : le fichier reste dans Multimedia.

Avec l'option Supprimer les fichiers à la suppression d'un média, le fichier est aussi effacé du disque, avec ses images optimisées, quand plus aucun objet Sage ne l'utilise. Seul un fichier situé dans Multimedia est effacé.

Effacement définitif

Les fichiers supprimés ne peuvent pas être récupérés : cette opération est irréversible. L'outil de configuration demande une confirmation à l'activation de l'option.

Questions fréquentes

Le rangement modifie-t-il mes données Sage ?

Il déplace les fichiers et met à jour leur chemin dans les tables de médias de Sage (et la photo de l'article). Les objets eux-mêmes ne changent pas.

Un document transformé change de numéro : ses médias changent-ils de dossier ?

Non avec le modèle par défaut : il ne contient ni le numéro ni le type de pièce, seulement le domaine et le tiers.

J'ai déjà rangé des fichiers à la main : le connecteur va-t-il les déplacer ?

Non. Un fichier déjà dans un sous-dossier n'est déplacé qu'avec l'option Forcer le rangement, après une nouvelle simulation.

Dans l'API v2

Les objets de cet écran sont exposés par l'API du connecteur. Chaque groupe détaille ses opérations, leurs paramètres et un exemple d'appel ; le point de départ est Démarrer avec l'API.

Voir aussi

Documentation de SenSaaS v2. Chaque page est écrite à partir du produit livré ; ce qui reste à vérifier y est signalé.