API publique

L’API publique donne aux administrateurs de l’organisation un accès HTTP direct aux données en direct de votre organisation — intégrez-les dans n’importe quel site web, application, bot ou automatisation capable d’effectuer une requête HTTP. C’est une fonctionnalité de l’offre Business.

La clé est limitée à votre organisation — tous les points de terminaison opèrent automatiquement sur ce groupe. URL de base : https://api.ludoya.com/public/v1. En-tête d’authentification : X-Api-Key: YOUR_KEY. Limite de débit : 100 requêtes par minute, au-delà vous obtiendrez un 429.

Les clés commencent par ldy_ et comptent 36 caractères, ce qui les rend faciles à repérer dans un fichier de configuration — et faciles à rechercher si jamais l’une d’elles se retrouve là où elle ne devrait pas. Traitez-la comme un mot de passe : uniquement côté serveur, et révoquez-la depuis la même page en cas de fuite.

Ce à quoi vous pouvez accéder

• Lieux — les lieux disponibles de votre groupe et leurs emplacements ; utilisés comme entrée lors de la création d’événements
• Événements (lecture) — événements à venir et passés avec titre, description, date/heure, fuseau horaire, capacité, nombre de participants et statut
• Événements (écriture) — créez et mettez à jour des événements via POST et PUT, avec un contrôle total du lieu, de la capacité, des autorisations, de la visibilité et de l’image
• Sous-événements — liste des événements imbriqués dans un événement parent
• Participants — ajoutez quelqu’un à un événement, modifiez sa présence ou supprimez-le
• Membres — liste de membres avec profils utilisateur et rôles (Propriétaire, Administrateur, Membre), paginée
• Invitations — invitez quelqu’un dans votre groupe
• Recherche — recherchez des utilisateurs Ludoya et dans le catalogue de jeux de société, afin de faire correspondre des noms à des ID avant d’écrire
• Collection — collection de jeux avec filtrage par possession, nom, nombre de joueurs et liste ; triable et paginée ; chaque jeu inclut des métadonnées BGG
• Statistiques — statistiques de parties pour n’importe quelle période : totaux, moyennes, meilleurs joueurs avec victoires et scores, répartitions par nombre de joueurs, par lieu et par jeu
• Campagnes (lecture) — liste les campagnes du groupe avec nombres de membres et de sessions ; récupère le détail complet de la campagne, y compris les membres, les sessions passées et les événements programmés
• Campagnes (écriture) — crée des campagnes pour le groupe et met à jour leur nom, description, statut et visibilité
• Membres de la campagne — ajoute, met à jour et supprime les personnes dans une campagne

Points de terminaison

GET /locations

Renvoie les lieux disponibles du groupe. Chaque lieu possède un id, un name, une address facultative, une capacity, un indicateur isDefault, et un tableau spots (chaque emplacement a son propre id, name et capacity). Utilisez les ID de lieu et d’emplacement lors de la création d’événements.

Se connecter avec Ludoya

La même page qui contient votre clé d'API transforme aussi votre organisation en fournisseur de connexion. Laissez les personnes se connecter à votre propre site web, forum ou plateforme communautaire avec leur compte Ludoya — pas de mot de passe distinct à oublier, et aucune base de données d'utilisateurs à gérer.

Pourquoi cela en vaut la peine

Lorsqu'une personne approuve la connexion, elle est liée à votre organisation : selon la politique d'adhésion de votre groupe, elle devient membre immédiatement (ouverte), soumet une demande d'adhésion qu'un administrateur doit approuver (demande pour rejoindre), ou se connecte simplement sans rejoindre (sur invitation uniquement). Dans tous les cas, elle apparaît dans l'endpoint /members comme n'importe qui d'autre — ainsi, la connexion à votre site web et votre liste de membres Ludoya restent automatiquement synchronisées.

Configuration

C'est du OpenID Connect standard, donc la plupart des plateformes n'ont besoin que d'une URL d'émetteur, plus un ID client et un secret. Enregistrez votre application depuis la page Public API pour obtenir ces identifiants, et répertoriez les URI de redirection qu'utilisera votre site — vous pouvez en enregistrer plusieurs, et chacune doit correspondre au redirect_uri envoyé par votre site caractère par caractère, barre oblique finale comprise. Un quasi-match est la raison la plus courante de l'échec d'une première tentative de connexion.

• Discourse — installez le plugin OpenID Connect, collez l'URL de découverte, ajoutez les identifiants
• WordPress — n'importe quel plugin générique OpenID Connect, en utilisant son option "auto discover"
• Tout le reste — si c'est compatible OIDC, pointez-le vers l'URL de l'émetteur et il se configurera tout seul

Chaque connexion renvoie l'identifiant permanent de la personne, son nom d'utilisateur, son nom d'affichage et son avatar, ainsi que son adresse e‑mail. Les instructions complètes de configuration, y compris le flux manuel, se trouvent dans le guide développeurs intégré à l'application, sous Développeurs → Se connecter avec Ludoya.

Pour les personnes qui se connectent

Toute personne ayant utilisé Ludoya pour se connecter quelque part peut consulter ces connexions dans Paramètres → Applications connectées, voir quand chacune a été connectée et quand elle a été utilisée pour la dernière fois, et en déconnecter n'importe laquelle à tout moment. La déconnexion coupe immédiatement l'accès du site, mais ne les supprime pas de votre groupe.

GET /events

Renvoie des événements futurs et passés dans des listes paginées distinctes.

Chaque événement comprend : type (MEETUP ou PLANNED_PLAY), title, description, startsAt, endsAt, timeZone, imageUrl, capacity, participantCount, canceled, teacher (objet utilisateur ou null), master (objet utilisateur ou null). Les objets utilisateur contiennent id, username, name, avatarUrl.

POST /events

Crée un événement dans le groupe. Champs obligatoires : type et title. Si locationId est omis, le lieu par défaut du groupe est utilisé ; s'il n'existe pas, renvoie 400.

Les champs facultatifs comprennent : description, locationId, spotId, gameId, parentEventId (pour les sous-événements), startsAt, endsAt, restrictedAttendance, capacity, minParticipants, estimatedDurationMinutes, maxReservationsPerUser, takeGamesPermission, organizePlaysPermission, teacherUserId, masterUserId, visibility, image.

Le champ image accepte {"base64": "data:image/jpeg;base64,..."} or {"url": "https://..."}. Max. 5 Mo.

Renvoie {"id": "string"} avec le statut 201.

PUT /events/{eventId}

Met à jour un événement existant. Même structure de corps que POST — n'incluez que les champs que vous souhaitez modifier. L'appelant doit être l'organisateur de l'événement (le compte du groupe). Renvoie 202 avec un corps vide.

GET /events/{eventId}

Récupère un seul événement par ID, avec la même structure que les éléments de GET /events.

GET /events/{eventId}/children

Répertorie les sous-événements imbriqués dans un événement parent — les volets thématiques ou les sessions individuelles d'un rassemblement de plus grande envergure. Chaque sous-événement a la même structure qu'un événement standard.

Gestion des participants

Trois endpoints vous permettent de gérer la liste des participants d’un événement depuis l’extérieur de Ludoya — pratique si les inscriptions se font sur votre propre site web, ou si vous importez une liste existante.

GET /members

Renvoie une liste paginée de membres.

Chaque membre inclut : id, username, name, avatarUrl, role (OWNER, ADMIN ou MEMBER).

POST /members/invite

Invite quelqu’un dans votre groupe. Ce point de terminaison accepte un username directement — pas besoin de rechercher l’ID — vous pouvez ainsi intégrer des membres directement depuis votre propre site ou outil d’administration.

GET /search/users et GET /search/boardgames

Les deux endpoints de recherche. La plupart des opérations d'écriture attendent un id plutôt qu'un nom, et ceux-ci permettent d'en obtenir un.

GET /search/users

GET /search/boardgames

Le filtre de jeux de société utilise la même forme key=value séparée par des points-virgules que le filtre de la collection, vous pouvez donc rechercher dans le catalogue par nombre de joueurs, durée de jeu, complexité, année, âge ou étiquettes.

GET /collection

Renvoie votre collection de jeux avec filtrage, tri et pagination.

Réponse : totalGames, totalExpansions, games[] — chacun avec : id, slug, name, imageUrl, isExpansion, yearPublished, minPlayerCount, maxPlayerCount.

GET /stats

Renvoie des statistiques de parties pour une fenêtre temporelle configurable.

La réponse inclut :

• Résumé — parties totales, durée de jeu totale/moyenne, nombres de jeux, de joueurs et de lieux uniques
• Par joueur — parties par personne, victoires, score moyen et meilleur score
• Par nombre de joueurs — répartition des parties à 2, 3, 4 joueurs, etc.
• Par lieu — nombre de parties et de jeux uniques par lieu
• Par jeu — nombre de parties, durée de jeu totale/moyenne et joueurs uniques par titre

GET /campaigns

Renvoie une liste paginée de campagnes appartenant au groupe.

Chaque campagne comprend : id, game (id, name, imageUrl), name, image, status, visibility, createdAt, updatedAt, memberCount, sessionCount.

GET /campaigns/{campaignId}

Renvoie le détail complet d’une campagne appartenant au groupe.

La réponse inclut : Tous les champs de la liste, ainsi que template, description, globalNotes, globalState, members[] (chacun avec user, role, characterNotes, characterState), sessions[] et events[].

POST /campaigns

Crée une campagne pour le groupe. Champs obligatoires : gameId et name. La visibilité est, par défaut, limitée aux membres du groupe (ONLY_GROUP) si elle est omise.

Champs facultatifs : templateId, description, visibility (PUBLIC, ONLY_GROUP, ONLY_FRIENDS ou PRIVATE).

Renvoie {"id": "string"} avec le statut 201.

PUT /campaigns/{campaignId}

Met à jour une campagne existante. Tous les champs sont facultatifs — incluez uniquement ce que vous souhaitez modifier.

Champs facultatifs : name, description, status (ACTIVE, COMPLETED, ARCHIVED), visibility.

Renvoie 202 avec un corps vide.

Membres de la campagne

Gérez qui fait partie d'une campagne, de la même manière que vous gérez les participants à un événement.

Codes d'erreur

Premiers pas

1. Générer une clé d'API

1. Accédez à la page de profil de votre organisation
2. Touchez le menu (⋮) → API publique
3. Touchez Générer une clé
4. Copiez votre clé immédiatement — elle n'est affichée qu'une seule fois et ne peut pas être récupérée à nouveau

La clé est liée à votre organisation. Gardez-la secrète : toute personne disposant de la clé peut lire et écrire toutes les données ci-dessus.

2. Révoquer ou régénérer

Pour révoquer une clé existante, retournez à la page API publique et touchez Révoquer. Confirmez la boîte de dialogue. Tout système utilisant l'ancienne clé commencera immédiatement à recevoir des erreurs 401. Pour émettre une nouvelle clé, touchez Générer une clé de nouveau.

Voir aussi :

• Organisations — comptes d'organisation et fonctionnalités premium
• Premium — tarifs du plan Business
• Intégrations — autres façons de connecter Ludoya avec des outils externes