API publică

La API publică le oferă administratorilor organizației acces HTTP direct la datele în timp real ale organizației tale — adu-le în orice site web, aplicație, bot sau automatizare care poate face o cerere HTTP. Este o funcționalitate din Planul Business.

Cheia este limitată la organizația ta — toate endpoint-urile operează automat asupra acelui grup. URL de bază: https://api.ludoya.com/public/v1. Antet de autentificare: X-Api-Key: YOUR_KEY. Limită de rată: 100 de cereri pe minut, după care vei primi un 429.

Cheile încep cu ldy_ și au 36 de caractere, astfel că sunt ușor de observat într-un fișier de configurare — și ușor de găsit la o scanare, dacă vreuna ajunge unde nu ar trebui. Trateaz-o ca pe o parolă: doar pe partea de server și revocă-o din aceeași pagină dacă se divulgă.

Ce poți accesa

• Locații — locațiile disponibile ale grupului tău și locurile acestora; folosite ca intrare la crearea de evenimente
• Evenimente (citire) — evenimente viitoare și trecute cu titlu, descriere, dată/oră, fus orar, capacitate, număr de participanți și stare
• Evenimente (scriere) — creează și actualizează evenimente prin POST și PUT, cu control deplin asupra locației, capacității, permisiunilor, vizibilității și imaginii
• Sub-evenimente — listează evenimentele imbricate într-un eveniment părinte
• Participanți — adaugă pe cineva la un eveniment, schimbă-i prezența sau elimină-l
• Membri — listă de membri cu profiluri de utilizator și roluri (Proprietar, Administrator, Membru), paginată
• Invitații — invită pe cineva în grupul tău
• Căutare — caută utilizatori Ludoya și în catalogul de jocuri de societate, ca să poți asocia nume la ID-uri înainte de a scrie
• Colecție — colecție de jocuri cu filtrare după deținere, nume, număr de jucători și listă; sortabilă și paginată; fiecare joc include metadate BGG
• Statistici — statistici ale partidelor pentru orice perioadă: totaluri, medii, jucători de top cu victorii și scoruri, defalcări pe număr de jucători, pe locație și pe joc
• Campanii (citire) — listează campaniile grupului cu număr de membri și sesiuni; preia detaliul complet al campaniei, inclusiv membri, sesiuni trecute și evenimente programate
• Campanii (scriere) — creează campanii pentru grup și actualizează numele, descrierea, starea și vizibilitatea
• Membrii campaniei — adaugă, actualizează și elimină persoanele dintr-o campanie

Endpoint-uri

GET /locations

Returnează locațiile disponibile ale grupului. Fiecare locație are un id, name, un address opțional, capacity, un indicator isDefault și o listă spots (fiecare loc are propriul id, name și capacity). Folosește ID-urile locației și ale locului când creezi evenimente.

Autentificare cu Ludoya

Aceeași pagină care conține cheia ta API îți transformă și organizația într-un furnizor de autentificare. Permite-le oamenilor să se conecteze pe propriul tău site, forum sau platformă de comunitate cu contul lor Ludoya — fără parolă separată pe care s-o uite și fără bază de date de utilizatori pe care să o gestionezi.

De ce merită

Când cineva aprobă autentificarea, este asociat cu organizația ta: în funcție de politica de aderare a grupului tău, fie devine membru imediat (deschis), trimite o cerere de aderare pentru aprobarea unui administrator (cerere de aderare), sau pur și simplu se autentifică fără a se alătura (doar cu invitație). Oricum ar fi, apare în endpointul /members ca oricine altcineva — astfel, autentificarea pe site-ul tău și lista ta de membri Ludoya rămân sincronizate automat.

Cum se configurează

Este OpenID Connect standard, astfel că majoritatea platformelor nu au nevoie decât de un URL al emitentului plus un ID de client și un secret. Înregistrează-ți aplicația din pagina Public API pentru a obține aceste acreditări și listează URI-urile de redirecționare pe care le va folosi site-ul tău — poți înregistra mai multe, iar fiecare trebuie să se potrivească cu redirect_uri trimis de site-ul tău caracter cu caracter, inclusiv bara oblică finală. O nepotrivire minimă este cel mai frecvent motiv pentru care eșuează prima încercare de autentificare.

• Discourse — instalează pluginul OpenID Connect, lipește URL-ul de descoperire, adaugă acreditările
• WordPress — orice plugin generic de OpenID Connect, folosind opțiunea sa "auto discover"
• Orice altceva — dacă este compatibil cu OIDC, indică-i URL-ul emitentului și se configurează singur

Fiecare autentificare returnează identificatorul permanent al persoanei, numele de utilizator, numele afișat și avatarul, precum și adresa de email. Instrucțiunile complete de configurare, inclusiv fluxul manual, se găsesc în ghidul pentru dezvoltatori din aplicație, la Dezvoltatori → Autentificare cu Ludoya.

Pentru persoanele care se autentifică

Oricine a folosit Ludoya pentru a se autentifica undeva poate revizui acele conexiuni în Setări → Aplicații conectate, poate vedea când a fost conectată și când a fost folosită ultima dată fiecare și le poate deconecta oricând. Deconectarea întrerupe imediat accesul site-ului, dar nu îi elimină din grupul tău.

GET /events

Returnează evenimente viitoare și trecute în liste paginate separate.

Fiecare eveniment include: type (MEETUP sau PLANNED_PLAY), title, description, startsAt, endsAt, timeZone, imageUrl, capacity, participantCount, canceled, teacher (obiect de utilizator sau null), master (obiect de utilizator sau null). Obiectele de utilizator conțin id, username, name, avatarUrl.

POST /events

Creează un eveniment în grup. Câmpuri obligatorii: type și title. Dacă se omite locationId, se utilizează locația implicită a grupului; dacă nu există, returnează 400.

Câmpurile opționale includ: description, locationId, spotId, gameId, parentEventId (pentru sub-evenimente), startsAt, endsAt, restrictedAttendance, capacity, minParticipants, estimatedDurationMinutes, maxReservationsPerUser, takeGamesPermission, organizePlaysPermission, teacherUserId, masterUserId, visibility, image.

Câmpul image acceptă {"base64": "data:image/jpeg;base64,..."} or {"url": "https://..."}. Maxim 5 MB.

Returnează {"id": "string"} cu status 201.

PUT /events/{eventId}

Actualizează un eveniment existent. Aceeași structură a corpului ca la POST — include doar câmpurile pe care dorești să le schimbi. Apelantul trebuie să fie organizatorul evenimentului (contul grupului). Returnează 202 cu corp gol.

GET /events/{eventId}

Obține un singur eveniment după ID, cu aceeași structură ca elementele din GET /events.

GET /events/{eventId}/children

Listează subevenimentele imbricate din cadrul unui eveniment părinte — track-urile tematice sau sesiunile individuale ale unei întâlniri mai ample. Fiecare subeveniment are aceeași structură ca un eveniment obișnuit.

Gestionarea participanților

Trei endpointuri îți permit să gestionezi lista de participanți a unui eveniment din afara Ludoya — util dacă înscrierile au loc pe propriul tău site web sau dacă imporți o listă existentă.

GET /members

Returnează o listă paginată de membri.

Fiecare membru include: id, username, name, avatarUrl, role (OWNER, ADMIN sau MEMBER).

POST /members/invite

Invită pe cineva în grupul tău. Acesta acceptă un username direct — nu e nevoie de căutarea ID-ului — astfel poți adăuga membri direct de pe propriul tău site sau din instrumentul tău de administrare.

GET /search/users și GET /search/boardgames

Cele două endpointuri de căutare. Majoritatea operațiunilor de scriere au nevoie de un ID în loc de un nume, iar acestea sunt modul în care obții unul.

GET /search/users

GET /search/boardgames

Filtrul pentru jocuri de societate folosește aceeași formă key=value separată prin punct și virgulă ca filtrul colecției, astfel încât poți căuta în catalog după număr de jucători, timp de joc, complexitate, an, vârstă sau etichete.

GET /collection

Returnează colecția ta de jocuri, cu filtrare, sortare și paginare.

Răspuns: totalGames, totalExpansions, games[] — fiecare cu: id, slug, name, imageUrl, isExpansion, yearPublished, minPlayerCount, maxPlayerCount.

GET /stats

Returnează statistici de partide pentru o fereastră de timp configurabilă.

Răspunsul include:

• Rezumat — partide totale, timp de joc total/mediu, număr de jocuri, jucători și locații unice
• După jucător — partide per persoană, victorii, scor mediu și cel mai bun scor
• După numărul de jucători — defalcare a jocurilor cu 2 jucători, 3 jucători, 4 jucători etc.
• După locație — număr de partide și jocuri unice pe locație
• După joc — număr de partide, timp de joc total/mediu și jucători unici pe titlu

GET /campaigns

Returnează o listă paginată de campanii care aparțin grupului.

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

GET /campaigns/{campaignId}

Returnează detaliile complete ale unei campanii aparținând grupului.

Răspunsul include: Toate câmpurile listei, plus template, description, globalNotes, globalState, members[] (fiecare cu user, role, characterNotes, characterState), sessions[] și events[].

POST /campaigns

Creează o campanie pentru grup. Câmpuri obligatorii: gameId și name. Vizibilitatea implicită este doar pentru membrii grupului (ONLY_GROUP) dacă este omisă.

Câmpuri opționale: templateId, description, visibility (PUBLIC, ONLY_GROUP, ONLY_FRIENDS sau PRIVATE).

Returnează {"id": "string"} cu statusul 201.

PUT /campaigns/{campaignId}

Actualizează o campanie existentă. Toate câmpurile sunt opționale — include doar ceea ce vrei să schimbi.

Câmpuri opționale: name, description, status (ACTIVE, COMPLETED, ARCHIVED), visibility.

Returnează 202 cu corpul gol.

Membrii campaniei

Gestionează cine se află într-o campanie, la fel cum gestionezi participanții la un eveniment.

Coduri de eroare

Primii pași

1. Generează o cheie API

1. Mergi la pagina de profil a organizației tale
2. Atinge meniul (⋮) → API publică
3. Atinge Generează cheie
4. Copiază-ți cheia imediat — este afișată o singură dată și nu mai poate fi recuperată

Cheia este legată de organizația ta. Păstreaz-o secretă: oricine are cheia poate citi și scrie toate datele de mai sus.

2. Revocă sau generează din nou

Pentru a revoca o cheie existentă, revino la pagina API publică și atinge Revocă. Confirmă dialogul. Orice sistem care folosește cheia veche va începe imediat să primească erori 401. Pentru a emite o cheie nouă, atinge din nou Generează cheie.

Vezi și:

• Organizații — conturi de organizație și funcții premium
• Premium — prețuri pentru planul Business
• Integrări — alte modalități de a conecta Ludoya la instrumente externe