API REST Oniva

Qu'est-ce que la REST API ?

La REST API d'Oniva te permet d'accéder aux données d'Oniva depuis des systèmes externes – sans passer par l'interface utilisateur. Elle est conçue pour les développeur·trice·s qui souhaitent intégrer Oniva dans des systèmes existants ou créer leurs propres applications par-dessus.

Contrairement aux webhooks, qui envoient les données automatiquement lorsqu'un événement se produit, la REST API te permet de récupérer les données à la demande – quand tu en as besoin.

Que peux-tu faire avec l'API ?

La REST API te donne accès aux domaines suivants :

Événements

• Récupérer des événements individuels (incl. options, statut, date et lieu)
• Lister et filtrer tous les événements au sein d'une entité – p. ex. par statut, période ou workspace

Réservations

• Récupérer les réservations d'un événement
• Récupérer une réservation individuelle avec les coordonnées, les informations de paiement et les options réservées
• Filtrer les réservations – p. ex. par statut, adresse e-mail ou période

Informations utilisateur·trice

• Récupérer les informations relatives au client API authentifié

À quoi peut servir l'API ?

L'API permet de connecter Oniva de manière ciblée à d'autres systèmes. Les cas d'utilisation typiques sont les suivants :

Rapports et analyses personnalisés: Les données de réservation peuvent être récupérées périodiquement et transférées vers ton propre outil d'analyse ou de reporting – sans aucun export manuel.

Exemple : Oniva → REST API → script Python → Excel / Power BI

Intégrations personnalisées: Si un système tiers a besoin de données de réservation ou d'événements, il peut les récupérer directement via l'API. Cela permet des connexions sur mesure qui vont au-delà des webhooks standard.

Synchronisation des données: Les données d'Oniva peuvent être récupérées régulièrement et synchronisées avec d'autres systèmes – p. ex. des CRM, des bases de données de membres ou des outils internes.

💡 Conseil : Pour les notifications en temps réel sur les réservations ou les check-ins, les webhooks sont plus adaptés. La REST API est idéale lorsque tu dois récupérer des données à la demande.

Configurer l'API

Prérequis

• Droits d'administrateur·trice de l'entité
• La fonctionnalité API doit être activée sur ta licence

Si la fonctionnalité n'est pas encore disponible, elle peut être activée par l'équipe de support Oniva.

Créer un client API

1. Navigue vers Paramètres de l'entité → Clients API
2. Crée un nouveau client API
3. Une fois créé, tu recevras :
   • Client ID – ton identifiant unique
   • Client Secret – ton mot de passe secret (affiché une seule fois – sauvegarde-le immédiatement !)
4. Utilise le Client ID et le Client Secret pour t'authentifier auprès de l'API

⚠️ Important : Le Client Secret n'est affiché qu'une seule fois après la création. Assure-toi de le stocker immédiatement dans un endroit sécurisé.

Authentification

L'API utilise OAuth 2.0 Client Credentials. Cela signifie que tu échanges ton Client ID et ton Client Secret contre un token d'accès limité dans le temps (Bearer Token), que tu inclus dans chaque requête API.

Les tokens sont valables 1 heure. Passé ce délai, un nouveau token doit être demandé.

Accéder à la documentation API

La documentation technique complète – incluant tous les endpoints disponibles, les paramètres et des exemples de requêtes – se trouve directement dans ton compte Oniva à l'adresse suivante :

/admin/de/apidocs

Tu peux également y tester les endpoints directement dans ton navigateur.

Limites d'utilisation et détails techniques

Rate limiting: L'API autorise un maximum de 300 requêtes par minute (par client OAuth). Les endpoints d'authentification sont limités à 20 requêtes par minute et par adresse IP. Si tu dépasses ces limites, tu recevras un message d'erreur indiquant combien de temps attendre avant de réessayer.

Pagination: Les requêtes de liste (p. ex. toutes les réservations d'un événement) sont retournées par pages. Par défaut, 10 entrées sont retournées par requête, avec un maximum de 100.

Version de l'API: L'API est actuellement en bêta. Des changements sont possibles. Nous recommandons de vérifier régulièrement la compatibilité de tes intégrations.

🔐 Avis de protection des données

Lors de l'utilisation de la REST API, les données relatives aux événements et aux participant·e·s sont transférées vers des systèmes externes. Assure-toi que le système destinataire répond aux exigences applicables en matière de protection des données et que les données sont traitées de manière sécurisée.

Vérifie en particulier si le système cible est conforme aux réglementations suisses et européennes en matière de protection des données. En tant qu'opérateur·trice du système cible, tu es responsable de t'assurer que tout traitement ultérieur des données est effectué de manière conforme. En cas de doute, nous recommandons de discuter de l'intégration avec ton·ta responsable de la protection des données ou ton service informatique.