API pública

A API pública dá aos administradores da organização acesso HTTP direto aos dados em tempo real da sua organização — integre-os a qualquer site, aplicativo, bot ou automação que possa fazer uma solicitação HTTP. É um recurso do Plano Business.

A chave tem escopo para a sua organização — todos os endpoints operam nesse grupo automaticamente. URL base: https://api.ludoya.com/public/v1. Cabeçalho de autenticação: X-Api-Key: YOUR_KEY. Limite de taxa: 100 solicitações por minuto, após o qual você receberá um 429.

As chaves começam com ldy_ e têm 36 caracteres de comprimento, portanto são fáceis de identificar em um arquivo de configuração — e fáceis de localizar caso alguma acabe onde não deveria. Trate-a como uma senha: somente no lado do servidor e revogue-a na mesma página se vazar.

O que você pode acessar

• Localizações — as localizações disponíveis do seu grupo e seus lugares; usadas como entrada ao criar eventos
• Eventos (leitura) — eventos próximos e passados com título, descrição, data/hora, fuso horário, capacidade, número de participantes e status
• Eventos (escrita) — crie e atualize eventos via POST e PUT, com controle total sobre a localização, capacidade, permissões, visibilidade e imagem
• Subeventos — liste os eventos aninhados dentro de um evento principal
• Participantes — adicione alguém a um evento, altere sua participação ou remova essa pessoa
• Membros — lista de membros com perfis de usuário e funções (Proprietário, Administrador, Membro), paginada
• Convites — convide alguém para o seu grupo
• Busca — procure usuários da Ludoya e no catálogo de jogos de tabuleiro, para que você possa resolver nomes para IDs antes de escrever
• Coleção — coleção de jogos com filtragem por posse, nome, número de jogadores e lista; ordenável e paginada; cada jogo inclui metadados do BGG
• Estatísticas — estatísticas de partidas para qualquer período: totais, médias, melhores jogadores com vitórias e pontuações, detalhamentos por número de jogadores, por localização e por jogo
• Campanhas (leitura) — liste as campanhas do grupo com contagens de membros e sessões; recupere o detalhamento completo da campanha, incluindo membros, sessões passadas e eventos programados
• Campanhas (escrita) — crie campanhas para o grupo e atualize seu nome, descrição, status e visibilidade
• Membros da campanha — adicione, atualize e remova as pessoas em uma campanha

Pontos de extremidade

GET /locations

Retorna as localizações disponíveis do grupo. Cada localização tem um id, name, address opcional, capacity, um indicador isDefault e uma lista spots (cada lugar tem seu próprio id, name e capacity). Use os IDs de localização e de lugar ao criar eventos.

Entrar com a Ludoya

A mesma página que contém sua chave de API também transforma sua organização em um provedor de login. Permita que as pessoas entrem no seu próprio site, fórum ou plataforma de comunidade com a conta da Ludoya — sem uma senha separada para elas esquecerem e sem um banco de dados de usuários para você manter.

Por que vale a pena

Quando alguém aprova o login, fica vinculado à sua organização: dependendo da política de adesão do seu grupo, essa pessoa se torna membro imediatamente (aberta), envia uma solicitação para entrar para um administrador aprovar (solicitação para entrar), ou simplesmente entra sem aderir (somente por convite). Em qualquer caso, ela aparece no endpoint /members como qualquer outra pessoa — assim, o login do seu site e sua lista de membros da Ludoya permanecem sincronizados automaticamente.

Como configurar

É OpenID Connect padrão, então a maioria das plataformas não precisa de nada além de uma URL do emissor mais um ID de cliente e segredo. Registre seu aplicativo na página Public API para obter essas credenciais e liste as URIs de redirecionamento que seu site usará — você pode registrar várias, e cada uma deve corresponder ao redirect_uri que seu site enviar caractere por caractere, incluindo a barra final. Um quase-acerto é o motivo mais comum pelo qual a primeira tentativa de login falha.

• Discourse — instale o plugin de OpenID Connect, cole a URL de descoberta e adicione as credenciais
• WordPress — qualquer plugin genérico de OpenID Connect, usando a opção "auto discover"
• Qualquer outra coisa — se fala OIDC, aponte para a URL do emissor e ele se configura sozinho

Cada login retorna o identificador permanente da pessoa, seu nome de usuário, nome de exibição e avatar, e seu e-mail. As instruções completas de configuração, incluindo o fluxo manual, estão no guia para desenvolvedores dentro do app em Desenvolvedores → Entrar com a Ludoya.

Para quem entra

Qualquer pessoa que tenha usado a Ludoya para entrar em algum lugar pode revisar essas conexões em Configurações → Aplicativos conectados, ver quando cada uma foi conectada e usada pela última vez e desconectar qualquer uma delas a qualquer momento. Ao desconectar, o acesso do site é interrompido imediatamente, mas isso não a remove do seu grupo.

GET /events

Retorna eventos futuros e passados em listas paginadas separadas.

Cada evento inclui: type (MEETUP ou PLANNED_PLAY), title, description, startsAt, endsAt, timeZone, imageUrl, capacity, participantCount, canceled, teacher (objeto de usuário ou null), master (objeto de usuário ou null). Os objetos de usuário contêm id, username, name, avatarUrl.

POST /events

Cria um evento no grupo. Campos obrigatórios: type e title. Se locationId for omitido, usa-se a localização padrão do grupo; se nenhuma existir, retorna 400.

Os campos opcionais incluem: description, locationId, spotId, gameId, parentEventId (para subeventos), startsAt, endsAt, restrictedAttendance, capacity, minParticipants, estimatedDurationMinutes, maxReservationsPerUser, takeGamesPermission, organizePlaysPermission, teacherUserId, masterUserId, visibility, image.

O campo image aceita {"base64": "data:image/jpeg;base64,..."} or {"url": "https://..."}. Máximo 5 MB.

Retorna {"id": "string"} com status 201.

PUT /events/{eventId}

Atualiza um evento existente. Mesmo formato de corpo que o POST — inclua apenas os campos que deseja alterar. O solicitante deve ser o organizador do evento (a conta do grupo). Retorna 202 com corpo vazio.

GET /events/{eventId}

Obtém um único evento por ID, com a mesma estrutura que os itens de GET /events.

GET /events/{eventId}/children

Lista os subeventos aninhados dentro de um evento principal — as trilhas temáticas ou sessões individuais de um evento de maior porte. Cada subevento tem a mesma estrutura que um evento normal.

Gestão de participantes

Três endpoints permitem que você gerencie a lista de participantes de um evento de fora da Ludoya — útil se as inscrições acontecem no seu próprio site, ou se você está importando uma lista existente.

GET /members

Retorna uma lista paginada de membros.

Cada membro inclui: id, username, name, avatarUrl, role (OWNER, ADMIN ou MEMBER).

POST /members/invite

Convida alguém para o seu grupo. Este aceita um username diretamente — não é preciso buscar o ID —, assim você pode incorporar membros diretamente do seu próprio site ou ferramenta de administração.

GET /search/users e GET /search/boardgames

Os dois endpoints de pesquisa. A maioria das operações de escrita requer um id em vez de um nome, e é assim que se obtém um.

GET /search/users

GET /search/boardgames

O filtro de jogos de tabuleiro usa a mesma forma key=value separada por ponto e vírgula que o filtro da coleção, assim é possível pesquisar o catálogo por número de jogadores, tempo de jogo, complexidade, ano, idade ou etiquetas.

GET /collection

Retorna sua coleção de jogos com filtragem, ordenação e paginação.

Resposta: totalGames, totalExpansions, games[] — cada um com: id, slug, name, imageUrl, isExpansion, yearPublished, minPlayerCount, maxPlayerCount.

GET /stats

Retorna estatísticas de partidas para uma janela de tempo configurável.

A resposta inclui:

• Resumo — partidas totais, tempo de jogo total/médio, contagens únicas de jogos, jogadores e localizações
• Por jogador — partidas por pessoa, vitórias, pontuação média e melhor pontuação
• Por número de jogadores — detalhamento de jogos para 2 jogadores, 3 jogadores, 4 jogadores, etc.
• Por localização — quantidade de partidas e jogos únicos por local
• Por jogo — quantidade de partidas, tempo de jogo total/médio e jogadores únicos por título

GET /campaigns

Retorna uma lista paginada de campanhas pertencentes ao grupo.

Cada campanha inclui: id, game (id, name, imageUrl), name, image, status, visibility, createdAt, updatedAt, memberCount, sessionCount.

GET /campaigns/{campaignId}

Retorna os detalhes completos de uma campanha pertencente ao grupo.

A resposta inclui: Todos os campos da lista, mais template, description, globalNotes, globalState, members[] (cada um com user, role, characterNotes, characterState), sessions[] e events[].

POST /campaigns

Cria uma campanha para o grupo. Campos obrigatórios: gameId e name. A visibilidade padrão é apenas para membros do grupo (ONLY_GROUP) se omitida.

Campos opcionais: templateId, description, visibility (PUBLIC, ONLY_GROUP, ONLY_FRIENDS ou PRIVATE).

Retorna {"id": "string"} com status 201.

PUT /campaigns/{campaignId}

Atualiza uma campanha existente. Todos os campos são opcionais — inclua apenas o que você deseja alterar.

Campos opcionais: name, description, status (ACTIVE, COMPLETED, ARCHIVED), visibility.

Retorna 202 com o corpo vazio.

Membros da campanha

Gerencie quem está em uma campanha, da mesma forma que você gerencia os participantes de um evento.

Códigos de erro

Primeiros passos

1. Gerar uma chave de API

1. Vá para a página de perfil da sua organização
2. Toque no menu (⋮) → API pública
3. Toque em Gerar chave
4. Copie sua chave imediatamente — ela é mostrada apenas uma vez e não pode ser recuperada novamente

A chave está vinculada à sua organização. Mantenha-a em segredo: qualquer pessoa com a chave pode ler e escrever todos os dados acima.

2. Revogar ou gerar novamente

Para revogar uma chave existente, volte à página de API pública e toque em Revogar. Confirme a caixa de diálogo. Qualquer sistema que use a chave antiga começará imediatamente a receber erros 401. Para emitir uma nova chave, toque em Gerar chave novamente.

Relacionado:

• Organizações — contas de organização e recursos premium
• Premium — preços do plano Business
• Integrações — outras formas de conectar a Ludoya com ferramentas externas