Herkese Açık API

Herkese Açık API, organizasyon yöneticilerine organizasyonunuzun canlı verilerine doğrudan HTTP erişimi verir — HTTP isteği yapabilen herhangi bir web sitesine, uygulamaya, bota ya da otomasyona çekin. Business planına ait bir özelliktir.

Anahtar organizasyonunuzla sınırlıdır — tüm uç noktalar otomatik olarak o grup üzerinde çalışır. Temel URL: https://api.ludoya.com/public/v1. Kimlik doğrulama başlığı: X-Api-Key: YOUR_KEY. Hız sınırı: dakikada 100 istek; sonrasında 429 alırsınız.

Anahtarlar ldy_ ile başlar ve 36 karakter uzunluğundadır; böylece bir yapılandırma dosyasında kolayca fark edilir — ve biri olmaması gereken bir yere düşerse kolayca taranır. Ona bir parola gibi davranın: yalnızca sunucu tarafında tutun, sızarsa aynı sayfadan geri alın.

Nelere Erişebilirsiniz

• Konumlar — grubunuzun kullanılabilir mekânları ve yerleri; etkinlik oluştururken girdi olarak kullanılır
• Etkinlikler (okuma) — yaklaşan ve geçmiş etkinlikler; başlık, açıklama, tarih/saat, saat dilimi, kapasite, katılımcı sayısı ve durum bilgisiyle
• Etkinlikler (yazma) — POST ve PUT ile etkinlik oluşturun ve güncelleyin; konum, kapasite, izinler, görünürlük ve görsel üzerinde tam denetimle
• Alt etkinlikler — bir ana etkinliğin içindeki etkinlikleri listeleyin
• Katılımcılar — birini etkinliğe ekleyin, katılım durumunu değiştirin ya da çıkarın
• Üyeler — kullanıcı profilleri ve rolleriyle (Sahip, Yönetici, Üye) üye listesi, sayfalanmış
• Davetler — birini grubunuza davet edin
• Arama — Ludoya kullanıcılarını ve kutu oyunu kataloğunu arayın; böylece yazma işlemlerinden önce adları ID’lere çevirebilirsiniz
• Koleksiyon — sahiplik, ad, oyuncu sayısı ve listeye göre süzülebilen oyun koleksiyonu; sıralanabilir ve sayfalanmış; her oyun BGG üstverisi içerir
• İstatistikler — herhangi bir dönem için oyun istatistikleri: toplamlar, ortalamalar, galibiyet ve puanlarıyla en iyi oyuncular, oyuncu sayısına, konuma ve oyuna göre dökümler
• Kampanyalar (okuma) — grubun kampanyalarını üye ve oturum sayılarıyla listeleyin; üyeler, geçmiş oturumlar ve planlanmış etkinlikler dahil tam kampanya ayrıntısını alın
• Kampanyalar (yazma) — grup için kampanya oluşturun; adını, açıklamasını, durumunu ve görünürlüğünü güncelleyin
• Kampanya üyeleri — bir kampanyadaki kişileri ekleyin, güncelleyin ve çıkarın

Uç Noktalar

GET /locations

Grubun kullanılabilir konumlarını döndürür. Her konumun bir id, name, isteğe bağlı address, capacity, bir isDefault bayrağı ve bir spots dizisi vardır (her yerin kendi id, name ve capacity değeri olur). Etkinlik oluştururken konum ve yer ID’lerini kullanın.

Ludoya ile giriş

API anahtarınızın durduğu sayfa, organizasyonunuzu aynı zamanda bir giriş sağlayıcısına dönüştürür. İnsanlar kendi sitenize, forumunuza ya da topluluk platformunuza Ludoya hesaplarıyla giriş yapsın — unutacakları ayrı bir parola da olmasın, sizin işletmeniz gereken bir kullanıcı veritabanı da.

Neden değer

Biri girişi onayladığında organizasyonunuza bağlanır: grubunuzun katılma politikasına göre ya doğrudan üye olur (açık), ya bir yöneticinin onaylayacağı katılma isteği gönderir (istekle), ya da katılmadan yalnızca giriş yapar (yalnızca davetle). Her hâlükârda /members uç noktasında herkes gibi görünür — böylece sitenizin girişi ile Ludoya üye listeniz kendiliğinden aynı kalır.

Kurulum

Standart OpenID Connect’tir; bu yüzden çoğu platformun bir issuer URL ile bir client ID ve secret dışında bir şeye ihtiyacı olmaz. Bu kimlik bilgilerini almak için uygulamanızı Herkese Açık API sayfasından kaydedin ve sitenizin kullanacağı yönlendirme URI’lerini listeleyin — birden fazla kaydedebilirsiniz ve her biri, sitenizin gönderdiği redirect_uri ile harfi harfine eşleşmelidir; sondaki eğik çizgi dahil. Kıl payı kaçırma, ilk giriş denemesinin başarısız olmasının açık ara en yaygın nedenidir.

• Discourse — OpenID Connect eklentisini kurun, discovery URL’sini yapıştırın, kimlik bilgilerini ekleyin
• WordPress — herhangi bir genel OpenID Connect eklentisi, "auto discover" seçeneğiyle
• Diğer her şey — OIDC konuşuyorsa issuer URL’sine yöneltin, kendini yapılandırsın

Her giriş, kişinin kalıcı tanımlayıcısını, kullanıcı adını, görünen adını, avatarını ve e-postasını döndürür. Elle yürütülen akış dahil kurulum yönergelerinin tamamı, uygulama içindeki geliştirici kılavuzunda Developers → Sign in with Ludoya altındadır.

Giriş yapanlar için

Ludoya ile bir yere giriş yapmış olan herkes, bu bağlantıları Ayarlar → Bağlı uygulamalar altında gözden geçirebilir; her birinin ne zaman bağlandığını ve en son ne zaman kullanıldığını görebilir ve dilediği zaman herhangi birinin bağlantısını kesebilir. Bağlantıyı kesmek sitenin erişimini anında sonlandırır ama kişiyi grubunuzdan çıkarmaz.

GET /events

Gelecek ve geçmiş etkinlikleri ayrı sayfalanmış listeler hâlinde döndürür.

Her etkinlik şunları içerir: type (MEETUP veya PLANNED_PLAY), title, description, startsAt, endsAt, timeZone, imageUrl, capacity, participantCount, canceled, teacher (kullanıcı nesnesi veya null), master (kullanıcı nesnesi veya null). Kullanıcı nesneleri id, username, name, avatarUrl içerir.

POST /events

Grupta bir etkinlik oluşturur. Zorunlu alanlar: type ve title. locationId belirtilmezse grubun varsayılan konumu kullanılır; hiç yoksa 400 döner.

İsteğe bağlı alanlar şunları içerir: description, locationId, spotId, gameId, parentEventId (alt etkinlikler için), startsAt, endsAt, restrictedAttendance, capacity, minParticipants, estimatedDurationMinutes, maxReservationsPerUser, takeGamesPermission, organizePlaysPermission, teacherUserId, masterUserId, visibility, image.

image alanı şunlardan birini kabul eder: {"base64": "data:image/jpeg;base64,..."} or {"url": "https://..."}. En fazla 5 MB.

201 durumuyla {"id": "string"} döndürür.

PUT /events/{eventId}

Mevcut bir etkinliği günceller. Gövde yapısı POST ile aynıdır — yalnızca değiştirmek istediğiniz alanları ekleyin. Çağrıyı yapan, etkinliğin organizatörü (grup hesabı) olmalıdır. Boş gövdeyle 202 döndürür.

GET /events/{eventId}

Tek bir etkinliği id ile getirir; GET /events içindeki kayıtlarla aynı yapıdadır.

GET /events/{eventId}/children

Üst etkinliğin içinde yer alan alt etkinlikleri listeler — daha büyük bir organizasyonun ayrı bölümleri veya oturumları. Her alt etkinlik, normal bir etkinlikle aynı yapıya sahiptir.

Katılımcıları Yönetme

Üç uç nokta, bir etkinliğin katılımcı listesini Ludoya dışından yönetmenizi sağlar — kayıtlar kendi sitenizde alınıyorsa ya da mevcut bir listeyi içe aktarıyorsanız işinize yarar.

GET /members

Sayfalanmış bir üye listesi döndürür.

Her üye şunları içerir: id, username, name, avatarUrl, role (OWNER, ADMIN, veya MEMBER).

POST /members/invite

Grubunuza birini davet eder. Bu uç nokta doğrudan bir username alır – id araması gerekmez – böylece üyeleri kendi sitenizden veya yönetim aracınızdan doğrudan ekleyebilirsiniz.

GET /search/users and GET /search/boardgames

İki arama uç noktası. Yazma işlemlerinin çoğu ad yerine bir id ister; bunları da buradan alırsınız.

GET /search/users

GET /search/boardgames

Kutu oyunu filtresi, koleksiyon filtresiyle aynı noktalı virgülle ayrılmış key=value biçimini alır; böylece kataloğu oyuncu sayısına, oyun süresine, karmaşıklığa, yıla, yaşa veya etiketlere göre arayabilirsiniz.

GET /collection

Oyun koleksiyonunuzu filtreleme, sıralama ve sayfalama ile döndürür.

Yanıt: totalGames, totalExpansions, games[] — her biri şunlarla: id, slug, name, imageUrl, isExpansion, yearPublished, minPlayerCount, maxPlayerCount.

GET /stats

Yapılandırılabilir bir zaman aralığı için oyun istatistiklerini döndürür.

Yanıt şunları içerir:

• Özet — toplam oturum sayısı, toplam/ortalama oyun süresi, benzersiz oyun, oyuncu ve konum sayıları
• Oyuncuya göre — kişi başına oturum, galibiyet, ortalama ve en iyi puan
• Oyuncu sayısına göre — 2, 3, 4 kişilik oyunların dökümü vb.
• Konuma göre — mekân başına oturum sayısı ve benzersiz oyunlar
• Oyuna göre — başlık başına oturum sayısı, toplam/ortalama oyun süresi ve benzersiz oyuncular

GET /campaigns

Gruba ait kampanyaların sayfalanmış listesini döndürür.

Her kampanya şunları içerir: id, game (id, name, imageUrl), name, image, status, visibility, createdAt, updatedAt, memberCount, sessionCount.

GET /campaigns/{campaignId}

Gruba ait bir kampanyanın tüm ayrıntılarını döndürür.

Yanıt şunları içerir: Tüm liste alanları; ayrıca template, description, globalNotes, globalState, members[] (her biri user, role, characterNotes, characterState ile), sessions[] ve events[].

POST /campaigns

Grup için bir kampanya oluşturur. Zorunlu alanlar: gameId ve name. Görünürlük belirtilmezse varsayılan olarak yalnızca grup üyeleri (ONLY_GROUP) olur.

İsteğe bağlı alanlar: templateId, description, visibility (PUBLIC, ONLY_GROUP, ONLY_FRIENDS veya PRIVATE).

201 durumuyla {"id": "string"} döndürür.

PUT /campaigns/{campaignId}

Mevcut bir kampanyayı günceller. Tüm alanlar isteğe bağlıdır — yalnızca değiştirmek istediğinizi ekleyin.

İsteğe bağlı alanlar: name, description, status (ACTIVE, COMPLETED, ARCHIVED), visibility.

Boş gövdeyle 202 döndürür.

Kampanya Üyeleri

Bir kampanyada kimlerin olduğunu, etkinlik katılımcılarını yönettiğiniz gibi yönetin.

Hata kodları

Başlarken

1. API Anahtarı Oluşturun

1. Organizasyonunuzun profil sayfasına gidin
2. Menüye (⋮) → Herkese Açık API dokunun
3. Anahtar oluştur düğmesine dokunun
4. Anahtarınızı hemen kopyalayın — yalnızca bir kez gösterilir ve tekrar alınamaz

Anahtar organizasyonunuza bağlıdır. Gizli tutun: anahtara sahip olan herkes yukarıdaki tüm verileri okuyabilir ve yazabilir.

2. Geri Alma veya Yeniden Oluşturma

Mevcut bir anahtarı geri almak için Herkese Açık API sayfasına dönün ve Geri Al düğmesine dokunun. İletişim kutusunu onaylayın. Eski anahtarı kullanan tüm sistemler anında 401 hataları almaya başlar. Yeni bir anahtar vermek için yeniden Anahtar oluştur düğmesine dokunun.

İlgili:

• Organizasyonlar — organizasyon hesapları ve premium özellikler
• Premium — Business plan fiyatlandırması
• Entegrasyonlar — Ludoya'yı harici araçlarla bağlamanın diğer yolları