Offentlig API

Offentlig API giver organisationsadministratorer direkte HTTP-adgang til din organisations levende data — hent dem ind i ethvert websted, enhver app, bot eller automatisering, der kan lave en HTTP-forespørgsel. Det er en funktion på Business-planen.

Nøglen er afgrænset til din organisation — alle endpoints arbejder automatisk på den gruppe. Basis-URL: https://api.ludoya.com/public/v1. Auth-header: X-Api-Key: YOUR_KEY. Hastighedsgrænse: 100 forespørgsler i minuttet, hvorefter du får en 429.

Nøgler begynder med ldy_ og er 36 tegn lange, så de er lette at få øje på i en konfigurationsfil — og lette at scanne efter, hvis en engang ender et forkert sted. Behandl den som en adgangskode: kun på serversiden, og tilbagekald den fra den samme side, hvis den lækker.

Hvad du har adgang til

• Steder — din gruppes tilgængelige lokaler og deres pladser; bruges som input, når du opretter arrangementer
• Arrangementer (læs) — kommende og tidligere arrangementer med titel, beskrivelse, dato/tid, tidszone, kapacitet, deltagerantal og status
• Arrangementer (skriv) — opret og opdatér arrangementer via POST og PUT, med fuld kontrol over sted, kapacitet, rettigheder, synlighed og billede
• Underarrangementer — vis de arrangementer, der ligger inde i et overordnet arrangement
• Deltagere — føj nogen til et arrangement, ændr deres fremmøde, eller fjern dem
• Medlemmer — medlemsliste med brugerprofiler og roller (Ejer, Administrator, Medlem), pagineret
• Invitationer — invitér nogen ind i din gruppe
• Søgning — slå Ludoya-brugere og brætspilskataloget op, så du kan omsætte navne til ID'er, inden du skriver
• Samling — spilsamling med filtrering på ejerskab, navn, antal spillere og liste; sorterbar og pagineret; hvert spil indeholder BGG-metadata
• Statistik — spilstatistik for en vilkårlig periode: totaler, gennemsnit, topspillere med sejre og point, opdelinger pr. antal spillere, pr. sted og pr. spil
• Kampagner (læs) — vis gruppens kampagner med antal medlemmer og sessioner; hent fulde kampagnedetaljer inklusive medlemmer, tidligere sessioner og planlagte arrangementer
• Kampagner (skriv) — opret kampagner for gruppen, og opdatér deres navn, beskrivelse, status og synlighed
• Kampagnemedlemmer — tilføj, opdatér og fjern personerne i en kampagne

Endpoints

GET /locations

Returnerer gruppens tilgængelige steder. Hvert sted har et id, name, valgfri address, capacity, et isDefault-flag og et spots-array (hver plads har sit eget id, name og capacity). Brug sted- og plads-ID'er, når du opretter arrangementer.

Log ind med Ludoya

Den samme side, der rummer din API-nøgle, gør også din organisation til en login-udbyder. Lad folk logge ind på dit eget websted, forum eller community med deres Ludoya-konto — ingen separat adgangskode, de kan glemme, og ingen brugerdatabase, du skal drive.

Hvorfor det er det værd

Når nogen godkender login, bliver de tilknyttet din organisation: afhængigt af din gruppes optagelsespolitik bliver de medlem med det samme (åben), sender en anmodning om medlemskab, som en administrator godkender (ansøgning kræves), eller logger blot ind uden at melde sig ind (kun invitation). Uanset hvad dukker de op i /members-endpointet som alle andre — så dit websteds login og din Ludoya-medlemsliste holdes automatisk i takt.

Sådan sætter du det op

Det er almindelig OpenID Connect, så de fleste platforme skal ikke bruge andet end en issuer-URL plus et client ID og en hemmelighed. Registrér din applikation fra siden Offentlig API for at få de oplysninger, og angiv de redirect-URI'er, dit site vil bruge — du kan registrere flere, og hver af dem skal matche den redirect_uri, dit site sender, tegn for tegn, inklusive afsluttende skråstreg. Et næsten-match er den suverænt hyppigste grund til, at et første login-forsøg fejler.

• Discourse — installér OpenID Connect-plugin'et, indsæt discovery-URL'en, tilføj oplysningerne
• WordPress — et hvilket som helst generisk OpenID Connect-plugin med dets "auto discover"-mulighed
• Alt andet — hvis det taler OIDC, så peg det mod issuer-URL'en, og det konfigurerer sig selv

Hvert login returnerer personens permanente identifikator, brugernavn, visningsnavn og avatar samt e-mail. Fulde opsætningsinstruktioner, inklusive flowet i hånden, findes i udviklerguiden i appen under Developers → Sign in with Ludoya.

For dem, der logger ind

Enhver, der har brugt Ludoya til at logge ind et sted, kan gennemgå de forbindelser under Indstillinger → Tilsluttede apps, se hvornår hver enkelt blev tilsluttet og sidst brugt, og afbryde en hvilken som helst af dem når som helst. At afbryde forbindelsen afskærer webstedets adgang med det samme, men fjerner dem ikke fra din gruppe.

GET /events

Returnerer fremtidige og tidligere arrangementer i separate paginerede lister.

Hvert arrangement indeholder: type (MEETUP eller PLANNED_PLAY), title, description, startsAt, endsAt, timeZone, imageUrl, capacity, participantCount, canceled, teacher (brugerobjekt eller null), master (brugerobjekt eller null). Brugerobjekter indeholder id, username, name, avatarUrl.

POST /events

Opretter et arrangement i gruppen. Påkrævede felter: type og title. Udelades locationId, bruges gruppens standardsted; findes der intet, returneres 400.

Valgfrie felter omfatter: description, locationId, spotId, gameId, parentEventId (til underarrangementer), startsAt, endsAt, restrictedAttendance, capacity, minParticipants, estimatedDurationMinutes, maxReservationsPerUser, takeGamesPermission, organizePlaysPermission, teacherUserId, masterUserId, visibility, image.

Feltet image accepterer enten {"base64": "data:image/jpeg;base64,..."} or {"url": "https://..."}. Maks. 5 MB.

Returnerer {"id": "string"} med status 201.

PUT /events/{eventId}

Opdaterer et eksisterende arrangement. Samme body-struktur som POST — medtag kun de felter, du vil ændre. Kalderen skal være arrangementets arrangør (gruppekontoen). Returnerer 202 med tom body.

GET /events/{eventId}

Henter en enkelt begivenhed ud fra id, med samme struktur som posterne i GET /events.

GET /events/{eventId}/children

Viser underarrangementerne inde i et overordnet arrangement — de enkelte spor eller sessioner i en større begivenhed. Hvert underarrangement har samme struktur som et almindeligt arrangement.

Administration af deltagere

Tre endpoints lader dig styre et arrangements deltagerliste uden for Ludoya — praktisk, hvis tilmeldinger sker på dit eget websted, eller du importerer en eksisterende liste.

GET /members

Returnerer en pagineret medlemsliste.

Hvert medlem indeholder: id, username, name, avatarUrl, role (OWNER, ADMIN, eller MEMBER).

POST /members/invite

Inviterer nogen ind i din gruppe. Denne tager et username direkte – der er ingen id-opslag – så du kan tilføje medlemmer direkte fra dit eget websted eller adminværktøj.

GET /search/users and GET /search/boardgames

De to opslagsendpoints. De fleste skriveoperationer vil have et id frem for et navn, og det er sådan, du får et.

GET /search/users

GET /search/boardgames

Brætspilsfilteret tager den samme semikolonadskilte key=value-form som samlingsfilteret, så du kan søge i kataloget efter antal spillere, spilletid, kompleksitet, år, alder eller tags.

GET /collection

Returnerer din spilsamling med filtrering, sortering og paginering.

Svar: totalGames, totalExpansions, games[] — hver med: id, slug, name, imageUrl, isExpansion, yearPublished, minPlayerCount, maxPlayerCount.

GET /stats

Returnerer spilstatistik for et konfigurerbart tidsvindue.

Svaret indeholder:

• Opsummering — samlet antal partier, samlet/gennemsnitlig spilletid, antal unikke spil, spillere og steder
• Pr. spiller — partier, sejre, gennemsnitlig og bedste score pr. person
• Pr. antal spillere — fordeling på 2-spiller-, 3-spiller-, 4-spillerspil osv.
• Pr. sted — antal partier og unikke spil pr. spillested
• Pr. spil — antal partier, samlet/gennemsnitlig spilletid og unikke spillere pr. titel

GET /campaigns

Returnerer en pagineret liste over kampagner, der tilhører gruppen.

Hver kampagne indeholder: id, game (id, name, imageUrl), name, image, status, visibility, createdAt, updatedAt, memberCount, sessionCount.

GET /campaigns/{campaignId}

Returnerer de fulde detaljer for en kampagne, der tilhører gruppen.

Svaret indeholder: Alle listefelter plus template, description, globalNotes, globalState, members[] (hver med user, role, characterNotes, characterState), sessions[] og events[].

POST /campaigns

Opretter en kampagne for gruppen. Påkrævede felter: gameId og name. Synligheden er som standard kun gruppemedlemmer (ONLY_GROUP), hvis den udelades.

Valgfrie felter: templateId, description, visibility (PUBLIC, ONLY_GROUP, ONLY_FRIENDS eller PRIVATE).

Returnerer {"id": "string"} med status 201.

PUT /campaigns/{campaignId}

Opdaterer en eksisterende kampagne. Alle felter er valgfrie — medtag kun det, du vil ændre.

Valgfrie felter: name, description, status (ACTIVE, COMPLETED, ARCHIVED), visibility.

Returnerer 202 med tom body.

Kampagnemedlemmer

Administrér, hvem der er med i en kampagne, på samme måde som du administrerer deltagere i et arrangement.

Fejlkoder

Kom godt i gang

1. Generer en API-nøgle

1. Gå til din organisations profilside
2. Tryk på menuen (⋮) → Offentlig API
3. Tryk på Generer nøgle
4. Kopiér din nøgle med det samme — den vises kun én gang og kan ikke hentes igen

Nøglen er knyttet til din organisation. Hold den hemmelig: enhver med nøglen kan læse og skrive alle ovenstående data.

2. Tilbagekald eller generer på ny

For at tilbagekalde en eksisterende nøgle skal du gå tilbage til siden Offentlig API og trykke på Tilbagekald. Bekræft dialogen. Ethvert system, der bruger den gamle nøgle, begynder straks at modtage 401-fejl. Tryk på Generer nøgle igen for at udstede en ny nøgle.

Se også:

• Organisationer — organisationskonti og premiumfunktioner
• Premium — prissætning for Business-planen
• Integrationer — andre måder at forbinde Ludoya med eksterne værktøjer på