Bonnes pratiques d’usage de l’API Asterio

Pourquoi une leçon dédiée à l’API

Un module d’extension bien codé peut rester instable si la clé API qu’il utilise est mal gérée, si les quotas Asterio ne sont pas respectés ou si aucune journalisation ne permet de retracer un incident. Cette leçon détaille les six domaines sur lesquels notre équipe insiste auprès de chaque client, quel que soit le nombre de modules abonnés.

1. Gestion des clés API

Une bonne hygiène commence par une clé API par usage. Créez une clé dédiée pour chaque module Asteriomod plutôt qu’une clé unique partagée. Cela permet, en cas de compromission, de révoquer un périmètre précis sans interrompre les autres modules. Nommez chaque clé de manière explicite dans Asterio (Paramètres → API → Clés d’intégration) : par exemple « ABS — Multi-Propriété — Prod » ou « ABS — Rapport TVA — Recette ».

Planifiez une rotation semestrielle des clés en production. La rotation se pilote depuis notre plateforme : générez une nouvelle clé dans Asterio, remplacez la valeur dans la fiche du module, puis révoquez l’ancienne après 24 heures d’observation. Aucune interruption de service n’est nécessaire tant que la fenêtre de recouvrement est respectée.

2. Rate-limiting et quotas

L’API Asterio impose des quotas par clé et par minute. Nos modules respectent ces limites nativement grâce à une file d’attente locale qui lisse les appels. Vous n’avez normalement rien à configurer, mais un usage combiné de plusieurs modules sur une même propriété peut faire converger les pics. Ouvrez la page « Journaux API » de votre espace : elle affiche par heure le nombre d’appels réussis, ralentis et rejetés. Une part de rejetés supérieure à 1 % justifie de contacter notre support pour ajuster les fenêtres.

Ne réduisez jamais manuellement l’intervalle de synchronisation d’un module en dessous de la valeur par défaut : cela accroît la pression sur le quota Asterio sans améliorer la qualité des données restituées.

3. Journalisation des appels

Chaque module conserve un journal détaillé des appels API : horodatage, endpoint, code retour, latence, empreinte de la charge utile. La durée de rétention est de 90 jours par défaut, extensible à 12 mois pour les clients soumis à un audit annuel. Vous pouvez exporter ces journaux au format CSV depuis votre espace, ou les recevoir chaque nuit sur un endpoint SFTP.

Nous recommandons de conserver ces journaux hors de votre PMS, dans votre propre SIEM ou dans un service d’observabilité (Grafana Loki, Datadog, Elastic). La corrélation avec les événements applicatifs de vos autres systèmes est bien plus efficace lorsqu’un incident survient.

4. Sécurité opérationnelle

Les clés API sont stockées côté Asteriomod en chiffrement au repos (AES-256) et ne sont jamais restituées en clair dans l’interface : seul le préfixe est affiché. Les échanges réseau se font exclusivement en TLS 1.3. Aucun collaborateur d’Asteriomod n’a accès aux valeurs de clé à l’état déchiffré ; les opérations d’exploitation reposent sur des identifiants machine distincts.

De votre côté, appliquez le principe du moindre privilège dans Asterio : n’accordez à chaque clé que les scopes strictement nécessaires au module concerné. La documentation de chaque module précise la liste minimale de scopes à activer.

5. Dépannage

Quatre motifs représentent 90 % des incidents que nous voyons remonter :

• Clé révoquée sans rotation : la clé a été supprimée dans Asterio sans être remplacée dans le module. Correction : régénérer et enregistrer la nouvelle valeur.
• Scope insuffisant : Asterio renvoie un 403 sur un endpoint précis. Correction : ouvrir la fiche « Scopes requis » du module et compléter la clé.
• Quota dépassé : pic anormal d’écritures. Correction : décaler l’heure de synchronisation d’un module secondaire.
• Horodatage désynchronisé : un serveur mal synchronisé provoque des rejets de signatures. Correction : vérifier que NTP est actif sur vos machines qui interagissent avec l’espace Asteriomod.

6. Prêt pour la production

Une fois ces six domaines maîtrisés, votre configuration est stable. La page « Santé de la connexion » de votre espace affiche un score global tenant compte du taux de réussite des appels, du délai moyen et de la fraîcheur des données. Ce score doit rester supérieur à 98 % en régime normal.

En cas de doute, notre équipe support est joignable à support@asteriomod.org avec un délai de première réponse inférieur à 24 heures ouvrées.