Introduction à l’API

Utilisez l’API Activity Messenger depuis votre serveur pour intégrer les données d’une organisation ou publier du contenu Web. Cette page présente la connexion et les conventions communes. Choisissez ensuite une référence par ressource.

Authentification et URL de base

Envoyez les requêtes à https://activitymessenger.com/api/v1/organization/{organization}. Remplacez {organization} par l’identifiant numérique de l’organisation. Le domaine personnalisé d’un site Web n’est pas l’hôte de l’API.

Obtenez la clé API dans E-Commerce → API & IFRAME. Transmettez-la dans l’en-tête HTTP X-Activity-Messenger-Api-Key. Conservez-la dans un stockage sécurisé côté serveur; ne l’intégrez pas au JavaScript du navigateur, aux URL ni aux dépôts publics. Envoyez Accept: application/json et, pour un corps JSON, Content-Type: application/json. Les téléversements de fichiers utilisent plutôt un formulaire multipart.

L’API générale accepte aussi les clés de réseau et de compte configurées. L’API de site Web exige la clé de l’organisation indiquée dans l’URL et l’activation des sites Web. Cette clé donne accès à tous les sites de l’organisation et n’est pas limitée à la lecture.

Première requête

Lisez les informations de l’organisation avec GET /api/v1/organization/{organization} et les en-têtes ci-dessus. Les références indiquent les méthodes HTTP et les chemins; remplacez les paramètres par les identifiants renvoyés par l’API. Les identifiants, clés externes de page, slugs et numéros de membre sont distincts : utilisez celui prévu par le point de terminaison.

Pagination

La pagination dépend du point de terminaison; les collections n’ont pas toutes la même structure de réponse.

Pagination facultative : utilisateurs, membres, formulaires, étiquettes de formulaire, cours et étiquettes de cours renvoient un tableau d’au plus 50 éléments sans page ni per_page. Fournissez l’un des paramètres pour obtenir data, current_page, next_page_url et les totaux. La valeur par défaut est 50 et le maximum est 250.
Messages et modèles publiés : toujours paginés, avec 10 éléments par page par défaut. Utilisez per_page et page au besoin.
Répondants de formulaire : toujours en pagination simple; 50 par défaut, maximum 250. Aucun total, last_page ni last_page_url.
Listes de sites Web : sites, pages et médias utilisent toujours la pagination simple, à 50 éléments par page. Utilisez page; per_page ne change pas la taille. Aucun total n’est renvoyé.
Autres collections : produits, étiquettes de produit et forfaits de réservation renvoient des tableaux. Les événements du calendrier utilisent des filtres de dates. Consultez la référence avant d’ajouter des paramètres de pagination.

Traitez data et arrêtez lorsque next_page_url vaut null. Conservez les filtres et la taille de page d’origine lors des requêtes suivantes; les liens renvoyés ne répètent pas nécessairement tous les paramètres. Authentifiez chaque requête. Évitez de journaliser la clé ou des données sensibles.

Limites de requêtes et nouvelles tentatives

L’API de l’application est configurée pour 240 requêtes par minute. Les routes de site Web appliquent aussi une limite de 60 requêtes par minute. Ces limites sont partagées, et non des quotas indépendants par point de terminaison ou clé d’organisation. Les requêtes habituelles avec une clé API sont limitées selon l’adresse IP appelante; plusieurs intégrations utilisant la même adresse de sortie peuvent partager cette capacité.

Consultez X-RateLimit-Limit et X-RateLimit-Remaining lorsqu’ils sont présents. Après HTTP 429, attendez au moins le nombre de secondes indiqué dans Retry-After. Réduisez les appels simultanés et limitez les tentatives, avec un délai croissant pour les erreurs temporaires. Ne répétez pas continuellement les erreurs d’authentification ou de validation.

Ne répétez pas aveuglément une écriture après un délai d’attente dépassé : elle peut avoir réussi. La préparation et la publication des révisions Web ont des garanties d’idempotence documentées; les autres modifications ne partagent pas cette garantie. Lisez l’état obtenu avant de répéter une écriture.

Réponses et erreurs

Les appels réussis renvoient du JSON propre au point de terminaison : objet, tableau ou réponse paginée. Vérifiez le statut HTTP avant de traiter le corps. Les erreurs n’ont pas toutes la même structure; certains anciens points de terminaison renvoient une chaîne JSON ou null.

401 : clé absente ou invalide. Vérifiez la clé et l’organisation cible.
404 : ressource absente ou inaccessible. Vérifiez les identifiants et la propriété; les sites Web doivent aussi être activés.
409 : état initial périmé pour une révision Web ou des redirections. Relisez l’état, réconciliez les changements et vérifiez une nouvelle requête.
413 : requête trop volumineuse. Les documents Web sont limités à 2 Mo; les limites de téléversement sont décrites séparément.
422 : entrée invalide ou opération non prise en charge. Les erreurs peuvent contenir message et errors par champ; corrigez la requête avant de réessayer.
429 : limite atteinte. Respectez Retry-After.

Dates, filtres et mises à jour

Respectez le format de chaque paramètre. Un horodatage terminé par Z est en UTC; une date métier YYYY-MM-DD n’est pas un instant UTC. Suivez les règles du point de terminaison pour le fuseau de l’organisation et les bornes de dates. Les filtres de tableaux utilisent des crochets, comme tags[]=natation. Distinguez les champs omis, null et les tableaux vides, surtout pour le remplacement de contenu ou de présences.

Références de l’API générale

Références de l’API de site Web

Publier des pages : découverte, documents complets, vérification, publication et suppression.
Médias, sections réutilisables et redirections : manifestes d’images, navigation réutilisable et remplacement des redirections.