API pubblica

La API pubblica offre agli amministratori dell'organizzazione accesso HTTP diretto ai dati in tempo reale della tua organizzazione — portali in qualsiasi sito web, app, bot o automazione che possa effettuare una richiesta HTTP. È una funzionalità del piano Business.

La chiave è limitata alla tua organizzazione — tutti gli endpoint operano automaticamente su quel gruppo. URL di base: https://api.ludoya.com/public/v1. Intestazione di autenticazione: X-Api-Key: YOUR_KEY. Limite di frequenza: 100 richieste al minuto, superato il quale riceverai un 429.

Le chiavi iniziano con ldy_ e sono lunghe 36 caratteri, quindi sono facili da individuare in un file di configurazione — e facili da scansionare se mai dovessero finire dove non dovrebbero. Trattala come una password: solo lato server, e revocala dalla stessa pagina se dovesse trapelare.

A cosa puoi accedere

• Luoghi — i luoghi disponibili del tuo gruppo e i relativi posti; utilizzati come input durante la creazione di eventi
• Eventi (lettura) — eventi in arrivo e passati con titolo, descrizione, data/ora, fuso orario, capacità, conteggio dei partecipanti e stato
• Eventi (scrittura) — crea e aggiorna eventi tramite POST e PUT, con pieno controllo su luogo, capacità, autorizzazioni, visibilità e immagine
• Sotto-eventi — elenca gli eventi annidati all'interno di un evento principale
• Partecipanti — aggiungi qualcuno a un evento, modifica la sua partecipazione oppure rimuovilo
• Membri — elenco dei membri con profili utente e ruoli (Proprietario, Amministratore, Membro), con paginazione
• Inviti — invita qualcuno nel tuo gruppo
• Ricerca — cerca utenti Ludoya e nel catalogo di giochi da tavolo, così puoi risolvere i nomi in ID prima di scrivere
• Collezione — collezione di giochi con filtraggio per possesso, nome, numero di giocatori e lista; ordinabile e con paginazione; ogni gioco include metadati di BGG
• Statistiche — statistiche delle partite per qualsiasi periodo: totali, medie, migliori giocatori con vittorie e punteggi, suddivisioni per numero di giocatori, per luogo e per gioco
• Campagne (lettura) — elenca le campagne del gruppo con conteggi di membri e sessioni; recupera i dettagli completi della campagna, inclusi i membri, le sessioni passate e gli eventi programmati
• Campagne (scrittura) — crea campagne per il gruppo e aggiorna nome, descrizione, stato e visibilità
• Membri della campagna — aggiungi, aggiorna e rimuovi le persone in una campagna

Endpoint

GET /locations

Restituisce i luoghi disponibili del gruppo. Ogni luogo ha un id, name, un address facoltativo, capacity, un flag isDefault e un array spots (ogni posto ha il proprio id, name e capacity). Usa gli ID di luogo e di posto quando crei eventi.

Accedi con Ludoya

La stessa pagina che contiene la tua chiave API trasforma anche la tua organizzazione in un provider di accesso. Consenti alle persone di accedere al tuo sito web, forum o piattaforma della community con il loro account Ludoya — nessuna password separata che possano dimenticare e nessun database di utenti che tu debba gestire.

Perché ne vale la pena

Quando qualcuno approva l'accesso, viene collegato alla tua organizzazione: a seconda della politica di adesione del tuo gruppo, o diventa subito membro (aperta), invia una richiesta di adesione da far approvare a un amministratore (richiesta di adesione), oppure effettua semplicemente l'accesso senza aderire (solo su invito). In ogni caso, compare nell'endpoint /members come chiunque altro — così l'accesso al tuo sito web e la tua lista dei membri su Ludoya restano sincronizzati automaticamente.

Come configurarlo

È OpenID Connect standard, quindi alla maggior parte delle piattaforme non serve altro che un URL dell'issuer più un ID client e il relativo secret. Registra la tua applicazione dalla pagina Public API per ottenere tali credenziali ed elenca le URI di reindirizzamento che il tuo sito utilizzerà — puoi registrarne diverse e ciascuna deve corrispondere al redirect_uri che il tuo sito invia carattere per carattere, inclusa la barra finale. Una corrispondenza anche solo imperfetta è la ragione più comune per cui un primo tentativo di accesso fallisce.

• Discourse — installa il plugin OpenID Connect, incolla l'URL di discovery, aggiungi le credenziali
• WordPress — qualsiasi plugin generico OpenID Connect, usando l'opzione "auto discover"
• Qualsiasi altra piattaforma — se supporta OIDC, indirizzala all'URL dell'issuer e si configurerà da sola

Ogni accesso restituisce l'identificatore permanente della persona, il suo nome utente, nome visualizzato e avatar, e la sua email. Le istruzioni complete per la configurazione, incluso il flusso manuale, sono disponibili nella guida per sviluppatori in-app in Sviluppatori → Accedi con Ludoya.

Per chi effettua l'accesso

Chiunque abbia usato Ludoya per accedere da qualche parte può rivedere tali connessioni in Impostazioni → App collegate, vedere quando ciascuna è stata collegata e usata per l'ultima volta e disconnetterne una qualsiasi in qualsiasi momento. La disconnessione interrompe immediatamente l'accesso del sito ma non li rimuove dal tuo gruppo.

GET /events

Restituisce eventi futuri e passati in elenchi paginati separati.

Ogni evento include: type (MEETUP o PLANNED_PLAY), title, description, startsAt, endsAt, timeZone, imageUrl, capacity, participantCount, canceled, teacher (oggetto utente o null), master (oggetto utente o null). Gli oggetti utente contengono id, username, name, avatarUrl.

POST /events

Crea un evento nel gruppo. Campi obbligatori: type e title. Se si omette locationId, viene utilizzato il luogo predefinito del gruppo; se non esiste, restituisce 400.

I campi facoltativi includono: description, locationId, spotId, gameId, parentEventId (per sotto-eventi), startsAt, endsAt, restrictedAttendance, capacity, minParticipants, estimatedDurationMinutes, maxReservationsPerUser, takeGamesPermission, organizePlaysPermission, teacherUserId, masterUserId, visibility, image.

Il campo image accetta {"base64": "data:image/jpeg;base64,..."} or {"url": "https://..."}. Massimo 5 MB.

Restituisce {"id": "string"} con stato 201.

PUT /events/{eventId}

Aggiorna un evento esistente. Stessa struttura del corpo di POST — includi solo i campi che vuoi modificare. Il chiamante deve essere l'organizzatore dell'evento (l'account del gruppo). Restituisce 202 con corpo vuoto.

GET /events/{eventId}

Recupera un singolo evento per ID, con la stessa struttura degli elementi in GET /events.

GET /events/{eventId}/children

Elenca i sottoeventi annidati all'interno di un evento principale — le singole tracce tematiche o sessioni di un evento più ampio. Ogni elemento figlio ha la stessa struttura di un evento normale.

Gestione dei partecipanti

Tre endpoint ti consentono di gestire l'elenco dei partecipanti di un evento dall'esterno di Ludoya — utile se le iscrizioni avvengono sul tuo sito web o se stai importando un elenco esistente.

GET /members

Restituisce un elenco paginato di membri.

Ogni membro include: id, username, name, avatarUrl, role (OWNER, ADMIN o MEMBER).

POST /members/invite

Invita qualcuno nel tuo gruppo. Questo accetta direttamente un username — non serve cercare l'ID — così puoi inserire membri direttamente dal tuo sito o dallo strumento di amministrazione.

GET /search/users e GET /search/boardgames

I due endpoint di ricerca. La maggior parte delle operazioni di scrittura richiede un id anziché un nome, e con questi puoi ottenerne uno.

GET /search/users

GET /search/boardgames

Il filtro dei giochi da tavolo usa la stessa forma key=value separata da punto e virgola del filtro della collezione, quindi puoi cercare nel catalogo per numero di giocatori, tempo di gioco, complessità, anno, età o tag.

GET /collection

Restituisce la tua collezione di giochi con filtraggio, ordinamento e paginazione.

Risposta: totalGames, totalExpansions, games[] — ciascuno con: id, slug, name, imageUrl, isExpansion, yearPublished, minPlayerCount, maxPlayerCount.

GET /stats

Restituisce statistiche delle partite per una finestra temporale configurabile.

La risposta include:

• Riepilogo — partite totali, tempo di gioco totale/medio, conteggi di giochi, giocatori e luoghi unici
• Per giocatore — partite per persona, vittorie, punteggio medio e miglior punteggio
• Per numero di giocatori — suddivisione di giochi a 2 giocatori, 3 giocatori, 4 giocatori, ecc.
• Per luogo — numero di partite e giochi unici per luogo
• Per gioco — numero di partite, tempo di gioco totale/medio e giocatori unici per titolo

GET /campaigns

Restituisce un elenco paginato di campagne appartenenti al gruppo.

Ogni campagna include: id, game (id, name, imageUrl), name, image, status, visibility, createdAt, updatedAt, memberCount, sessionCount.

GET /campaigns/{campaignId}

Restituisce i dettagli completi di una campagna appartenente al gruppo.

La risposta include: Tutti i campi dell'elenco, più template, description, globalNotes, globalState, members[] (ciascuno con user, role, characterNotes, characterState), sessions[] e events[].

POST /campaigns

Crea una campagna per il gruppo. Campi obbligatori: gameId e name. La visibilità predefinita è solo per i membri del gruppo (ONLY_GROUP) se omessa.

Campi facoltativi: templateId, description, visibility (PUBLIC, ONLY_GROUP, ONLY_FRIENDS o PRIVATE).

Restituisce {"id": "string"} con stato 201.

PUT /campaigns/{campaignId}

Aggiorna una campagna esistente. Tutti i campi sono facoltativi — includi solo ciò che desideri modificare.

Campi facoltativi: name, description, status (ACTIVE, COMPLETED, ARCHIVED), visibility.

Restituisce 202 con il corpo vuoto.

Membri della campagna

Gestisci chi fa parte di una campagna, allo stesso modo in cui gestisci i partecipanti di un evento.

Codici di errore

Per iniziare

1. Generare una chiave API

1. Vai alla pagina del profilo della tua organizzazione
2. Tocca il menu (⋮) → API pubblica
3. Tocca Genera chiave
4. Copia subito la tua chiave — viene mostrata solo una volta e non può essere recuperata di nuovo

La chiave è legata alla tua organizzazione. Conservala segreta: chiunque abbia la chiave può leggere e scrivere tutti i dati sopra indicati.

2. Revocare o rigenerare

Per revocare una chiave esistente, torna alla pagina API pubblica e tocca Revoca. Conferma la finestra di dialogo. Qualsiasi sistema che utilizza la vecchia chiave inizierà immediatamente a ricevere errori 401. Per emettere una nuova chiave, tocca di nuovo Genera chiave.

Vedi anche:

• Organizzazioni — account di organizzazione e funzioni premium
• Premium — prezzi del piano Business
• Integrazioni — altri modi per connettere Ludoya con strumenti esterni