Offentlig API

Den offentlige API-en gir organisasjonsadministratorer direkte HTTP-tilgang til sanntidsdataene for organisasjonen din — trekk dem inn i hvilket som helst nettsted, app, bot eller automatisering som kan gjøre en HTTP-forespørsel. Det er en funksjon i Business-abonnementet.

Nøkkelen er avgrenset til organisasjonen din — alle endepunkter opererer automatisk på den gruppen. Basis-URL: https://api.ludoya.com/public/v1. Autentiseringsheader: X-Api-Key: YOUR_KEY. Begrensning: 100 forespørsler per minutt, etter det får du en 429.

Nøkler starter med ldy_ og er 36 tegn lange, så de er lette å oppdage i en konfigurasjonsfil — og lette å skanne etter hvis en noen gang ender opp et sted den ikke burde. Behandle den som et passord: kun på serversiden, og tilbakekall den fra samme side hvis den lekker.

Hva du kan få tilgang til

• Lokasjoner — gruppens tilgjengelige steder og deres plasser; brukes som input når du oppretter arrangementer
• Arrangementer (lesing) — kommende og tidligere arrangementer med tittel, beskrivelse, dato/klokkeslett, tidssone, kapasitet, antall deltakere og status
• Arrangementer (skriving) — opprett og oppdater arrangementer via POST og PUT, med full kontroll over lokasjon, kapasitet, tillatelser, synlighet og bilde
• Underarrangementer — list arrangementene som er nestet i et overordnet arrangement
• Deltakere — legg til noen i et arrangement, endre deltakelsesstatusen deres, eller fjern dem
• Medlemmer — medlemsliste med brukerprofiler og roller (Eier, Administrator, Medlem), paginert
• Invitasjoner — inviter noen inn i gruppen din
• Søk — slå opp Ludoya-brukere og brettspillkatalogen, slik at du kan mappe navn til ID-er før du skriver
• Samling — spillsamling med filtrering etter eierskap, navn, antall spillere og liste; sorterbar og paginert; hvert spill inkluderer BGG-metadata
• Statistikk — statistikk for spilløkter for enhver tidsperiode: totaler, gjennomsnitt, toppspillere med seire og poeng, fordelinger per antall spillere, per lokasjon og per spill
• Kampanjer (lesing) — list gruppens kampanjer med antall medlemmer og økter; hent fullstendige detaljer for kampanjen, inkludert medlemmer, tidligere økter og planlagte arrangementer
• Kampanjer (skriving) — opprett kampanjer for gruppen og oppdater navn, beskrivelse, status og synlighet
• Kampanjemedlemmer — legg til, oppdater og fjern personene i en kampanje

Endepunkter

GET /locations

Returnerer gruppens tilgjengelige lokasjoner. Hver lokasjon har en id, name, valgfri address, capacity, et isDefault-flagg og en spots-liste (hver plass har sin egen id, name og capacity). Bruk lokasjons- og plass-ID-er når du oppretter arrangementer.

Logg inn med Ludoya

Den samme siden som inneholder API-nøkkelen din, gjør også organisasjonen din til en påloggingsleverandør. La folk logge inn på ditt eget nettsted, forum eller fellesskapsplattform med Ludoya-kontoen sin — uten et eget passord de kan glemme, og uten en brukerdatabase du må drifte.

Hvorfor det er verdt det

Når noen godkjenner innloggingen, blir de knyttet til organisasjonen din: avhengig av gruppens opptakspolicy blir de enten medlem med en gang (åpen), sender en forespørsel om å bli med for at en administrator kan godkjenne (be om å bli med), eller bare logger inn uten å bli med (kun invitasjon). Uansett vises de i endepunktet /members som alle andre — slik forblir innloggingen på nettstedet ditt og Ludoya-medlemslisten din automatisk synkronisert.

Slik setter du det opp

Det er standard OpenID Connect, så de fleste plattformer trenger bare en utsteder-URL pluss en klient-ID og hemmelighet. Registrer applikasjonen din fra Public API-siden for å få disse opplysningene, og oppgi omdirigerings-URI-er som nettstedet ditt vil bruke — du kan registrere flere, og hver må samsvare med redirect_uri som nettstedet ditt sender tegn for tegn, inkludert avsluttende skråstrek. Et nesten-treff er den vanligste årsaken til at et første påloggingsforsøk mislykkes.

• Discourse — installer OpenID Connect-tillegget, lim inn discovery-URL-en, legg inn klient-ID og hemmelighet
• WordPress — et hvilket som helst generelt OpenID Connect-tillegg, ved å bruke alternativet "auto discover"
• Alt annet — hvis det støtter OIDC, pek det mot utsteder-URL-en, så konfigurerer det seg selv

Hver innlogging returnerer personens permanente identifikator, brukernavn, visningsnavn og avatar, og e-post. Fullstendige oppsettinstruksjoner, inkludert den manuelle flyten, finnes i utviklerveiledningen i appen under Utviklere → Logg inn med Ludoya.

For dem som logger inn

Alle som har brukt Ludoya til å logge inn et sted kan gjennomgå disse tilkoblingene under Innstillinger → Tilkoblede apper, se når hver ble koblet til og sist brukt, og koble fra hvilken som helst av dem når som helst. Å koble fra kutter nettstedets tilgang umiddelbart, men fjerner dem ikke fra gruppen din.

GET /events

Returnerer kommende og tidligere arrangementer i separate sideinndelte lister.

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

POST /events

Oppretter et arrangement i gruppen. Obligatoriske felt: type og title. Hvis locationId utelates, brukes gruppens standardlokasjon; hvis ingen finnes, returneres 400.

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

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

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

PUT /events/{eventId}

Oppdaterer et eksisterende arrangement. Samme kropp som i POST — inkluder bare feltene du vil endre. Den som kaller må være arrangør for arrangementet (gruppekontoen). Returnerer 202 med tom kropp.

GET /events/{eventId}

Henter ett enkelt arrangement etter ID, med samme struktur som elementene i GET /events.

GET /events/{eventId}/children

Lister opp underarrangementene som ligger under et overordnet arrangement — de enkelte sporene eller øktene i et større arrangement. Hvert underarrangement har samme struktur som et vanlig arrangement.

Administrere deltakere

Tre endepunkter lar deg administrere deltakerlisten for et arrangement utenfor Ludoya — praktisk hvis påmeldinger skjer på ditt eget nettsted, eller hvis du importerer en eksisterende liste.

GET /members

Returnerer en paginert liste over medlemmer.

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

POST /members/invite

Inviterer noen til gruppen din. Denne tar et username direkte — ingen ID-oppslag nødvendig — slik at du kan ta inn medlemmer rett fra ditt eget nettsted eller administrasjonsverktøy.

GET /search/users og GET /search/boardgames

De to oppslagsendepunktene. De fleste skriveoperasjoner trenger en id i stedet for et navn, og med disse kan du hente en.

GET /search/users

GET /search/boardgames

Brettspillfilteret bruker samme semikolon-separerte key=value-form som samlingsfilteret, slik at du kan søke i katalogen etter antall spillere, spilletid, kompleksitet, år, alder eller tagger.

GET /collection

Returnerer spillsamlingen din med filtrering, sortering og paginering.

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

GET /stats

Returnerer statistikk for spilløkter for et konfigurerbart tidsvindu.

Svaret inkluderer:

• Sammendrag — totalt antall spilløkter, total/gjennomsnittlig spilletid, antall unike spill, spillere og lokasjoner
• Etter spiller — spilløkter per person, seire, gjennomsnittlig poengsum og beste poengsum
• Etter antall spillere — fordeling av spill med 2, 3, 4 spillere osv.
• Etter lokasjon — antall spilløkter og unike spill per lokasjon
• Etter spill — antall spilløkter, total/gjennomsnittlig spilletid og unike spillere per tittel

GET /campaigns

Returnerer en sideinndelt liste over kampanjer som tilhører gruppen.

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

GET /campaigns/{campaignId}

Returnerer alle detaljer for en kampanje som tilhører gruppen.

Svaret inkluderer: Alle listefeltene, pluss template, description, globalNotes, globalState, members[] (hver med user, role, characterNotes, characterState), sessions[] og events[].

POST /campaigns

Oppretter en kampanje for gruppen. Obligatoriske felt: gameId og name. Synligheten er som standard kun for gruppemedlemmer (ONLY_GROUP) hvis utelatt.

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

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

PUT /campaigns/{campaignId}

Oppdaterer en eksisterende kampanje. Alle felter er valgfrie — ta bare med det du vil endre.

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

Returnerer 202 med tom responskropp.

Kampanjemedlemmer

Administrer hvem som er i en kampanje, på samme måte som du administrerer deltakere i et arrangement.

Feilkoder

Kom i gang

1. Generer en API-nøkkel

1. Gå til organisasjonens profilside
2. Trykk på menyen (⋮) → Offentlig API
3. Trykk på Generer nøkkel
4. Kopier nøkkelen din med en gang — den vises bare én gang og kan ikke hentes frem igjen

Nøkkelen er knyttet til organisasjonen din. Hold den hemmelig: alle som har nøkkelen kan lese og skrive alle dataene nevnt ovenfor.

2. Opphev eller generer på nytt

For å oppheve en eksisterende nøkkel, gå tilbake til Offentlig API-siden og trykk på Opphev. Bekreft dialogen. Alle systemer som bruker den gamle nøkkelen vil umiddelbart begynne å motta 401-feil. For å utstede en ny nøkkel, trykk på Generer nøkkel igjen.

Se også:

• Organisasjoner — organisasjonskontoer og premium-funksjoner
• Premium — priser for Business-planen
• Integrasjoner — andre måter å koble Ludoya til eksterne verktøy på