Centre d’aide

API de site Web : médias, sections réutilisables et redirections

Consultez l’introduction à l’API pour la connexion et les conventions communes, et Publier des pages pour le processus de révision. Les chemins ci-dessous sont relatifs à https://activitymessenger.com/api/v1/organization/{organization}/websites/{website}.

Téléverser et référencer des images

• GET /assets énumère les médias selon les règles de pagination des sites Web. Ajoutez ?sha256=<SHA-256 de 64 caractères minuscules> pour trouver un fichier par son empreinte exacte.
• POST /assets téléverse un fichier PNG, JPEG ou WebP dans le champ multipart file, d’au plus 15 Mo. La réponse contient l’id, le sha256 et l’url. Un nouveau téléversement des mêmes octets réutilise le média de l’organisation.

Ajoutez chaque image utilisée par une page ou une section réutilisable à la liste assets du document. Utilisez l’identifiant et l’empreinte renvoyés :

{"path":"assets/fr/ecran.png","id":123,"sha256":"<empreinte minuscule de 64 caractères>"}

Référencez ce même chemin dans Markdown ou HTML et fournissez un texte alternatif descriptif non vide. Le chemin doit correspondre à la langue du contenu : assets/en/ en anglais et assets/fr/ en français. L’URL d’un média déclaré peut aussi être utilisée dans la langue correspondante. Une image absente du manifeste, sans texte alternatif, avec une empreinte différente ou appartenant à une autre organisation est refusée. Les médias peuvent servir sur plusieurs sites de l’organisation et ne sont pas supprimés lorsqu’une page change.

Publier une section latérale réutilisable

La section latérale partagée est une section réutilisable native du créateur de site Web, liée aux pages. La modification de sa source met à jour tous ses emplacements, y compris sur d’autres sites où un administrateur a lié cette source. Ce n’est pas une copie du bloc. Sous 992 pixels, la navigation s’empile au-dessus du contenu.

1. Appelez GET /shared-section-keys/{key}. La réponse contient shared_key et shared_section; une clé inutilisée renvoie shared_section: null. Une source existante comprend son identifiant, edit_version, checksum, son état et les emplacements, pages et sites touchés.
2. Appelez POST /shared-sections/revisions avec l’enveloppe de révision de page : operation: "shared_upsert", un page_key stable, name, expected_checksum ("missing" à la création ou le checksum courant à la modification) et document. Le document contient exactement une section single-column, du contenu pour toutes les langues activées et les médias déclarés. Les métadonnées de page et champs de visibilité exigés par l’enveloppe ne créent pas de page et ne contrôlent pas la visibilité de la source. Une section latérale imbriquée est refusée.
3. Vérifiez GET /revisions/{revision}, notamment la source compilée ainsi que l’état antérieur et la liste complète des emplacements. Publiez avec POST /revisions/{revision}/publish et le content_checksum exact de cette révision. La réponse comprend microsite_reusable_section_id.
4. Ajoutez "sidebar": {"id": 123, "edit_version": 1} à chaque document de page qui doit l’afficher. Préparez, vérifiez et publiez séparément ces révisions de page.

La source doit avoir été publiée par l’API de sections partagées de ce site et appartenir à l’organisation indiquée dans la route. Une erreur de propriété renvoie 404; un désaccord de version renvoie 409. Omettez sidebar ou donnez-lui la valeur null dans un remplacement de page pour retirer cet emplacement. Les autres pages et la source demeurent. Un emplacement masqué ou supprimé laisse la mise en page ordinaire. La publication d’une source partagée met à jour les emplacements liés de façon atomique et inscrit les pages touchées dans leur historique. Si la source ou la liste des emplacements change entre la vérification et la publication, l’API renvoie 409. Les mises à jour partagées changent les checksums des pages liées : relisez leur état avant de nouvelles révisions. Cette API ne supprime pas les sources partagées et n’adopte pas de sections réutilisables existantes arbitraires.

Présentation du centre d’aide

Une page du centre d’aide peut inclure "presentation": "help" dans son document normal. Cette option propre à la page est versionnée; omettez-la ou donnez-lui null lors d’un remplacement pour la retirer. Elle ajoute une typographie et des espacements ciblés, des tableaux adaptatifs et des encadrés, sans modifier les pages ordinaires ni la source partagée elle-même. Une citation Markdown qui commence par [!NOTE], [!TIP], [!IMPORTANT] ou [!WARNING] devient un encadré avec une étiquette localisée. Pour une navigation d’aide dynamique, écrivez une liste Markdown imbriquée et traduite, avec des catégories en texte simple et des liens d’articles relatifs à la racine. La page active est mise en évidence et ses catégories parentes se déploient; sur mobile, la liste se trouve d’abord derrière une commande Parcourir l’aide. Six niveaux d’imbrication sont pris en charge. Cette présentation ne synchronise pas la recherche de l’ancien centre d’aide ni le magasin vectoriel du soutien.

Remplacer les redirections

GET /redirects renvoie les redirections, l’URL publique et le hash revision courant. PUT /redirects applique immédiatement un remplacement complet, contrairement à la publication de pages. Lisez la liste actuelle, conservez les entrées appartenant aux autres intégrations et envoyez toutes les entrées voulues avec la révision courante :

{
  "revision": "<hash de GET /redirects>",
  "redirects": [
    {"source": "/ancien-guide", "destination": "/guides/bien-demarrer/"}
  ]
}

L’API vérifie les sources en double, les collisions de chemins et les chaînes de redirection. Une révision périmée crée un conflit. Elle accepte au plus 2 000 redirections. Les redirections d’un ancien domaine doivent aussi être configurées sur le serveur ou le site qui gère encore ce domaine.