Riot API: Riot ID, PUUID e summonerID

Referência operacional para implementar a resolução de identidade dos players cadastrados em PLAYER_REGISTRY.

Objetivo

Resolver e manter três identificadores diferentes:

Campo local	Papel	Regra
`riot_id.game_name` + `riot_id.tag_line`	Identidade legível e atual para entrada e exibição.	Manter estruturado. Não armazenar apenas a string com `#`.
`puuid`	Identificador técnico preferencial para integrações.	Persistir quando obtido da Riot API. Preferir endpoints baseados em `PUUID` quando disponíveis.
`summoner_id`	Identificador técnico específico do LoL por plataforma.	Persistir quando necessário para endpoints que ainda o utilizam.

Não usar summonerName como identidade principal.

Roteamento

A Riot API usa o host para rotear a chamada. O host depende do serviço:

Serviço	Tipo de rota	Host relevante para os players BR
`ACCOUNT-V1`	Regional	`americas.api.riotgames.com`
`SUMMONER-V4`	Plataforma	`br1.api.riotgames.com`

Não assumir que todos os endpoints usam a mesma rota. Conferir a referência oficial do endpoint ao implementar novas chamadas.

Obtaining PUUID and summonerID from RiotID

Fluxo principal para preencher os identificadores técnicos de um player cadastrado:

Riot ID estruturado
  -> ACCOUNT-V1 by-riot-id no host regional AMERICAS
    -> PUUID
      -> SUMMONER-V4 by-puuid no host de plataforma BR1
        -> summonerID e dados de summoner

Etapa 1: Riot ID para PUUID

Endpoint oficial:

GET https://americas.api.riotgames.com/riot/account/v1/accounts/by-riot-id/{gameName}/{tagLine}

Referência: ACCOUNT-V1 GET_getByRiotId

Entrada:

riot_id:
  game_name: after hours
  tag_line: goia

Saída relevante:

puuid: <persistir valor retornado>
game_name: <valor retornado>
tag_line: <valor retornado>

Etapa 2: PUUID para summonerID

Endpoint oficial:

GET https://br1.api.riotgames.com/lol/summoner/v4/summoners/by-puuid/{encryptedPUUID}

Referência: SUMMONER-V4 GET_getByPUUID

Saída relevante:

summoner_id: <campo id retornado pelo SUMMONER-V4>
puuid: <confirmar consistência com a etapa anterior>

Obtaining Riot ID from PUUID

Usar este fluxo para recuperar ou atualizar o Riot ID legível quando já houver PUUID persistido:

PUUID
  -> ACCOUNT-V1 by-puuid no host regional AMERICAS
    -> gameName + tagLine

Endpoint oficial:

GET https://americas.api.riotgames.com/riot/account/v1/accounts/by-puuid/{puuid}

Referência: ACCOUNT-V1 GET_getByPuuid

Quando o Riot ID retornado diferir do cadastro:

mover o Riot ID anterior para riot_id_aliases, sem duplicar aliases;
atualizar riot_id;
manter player_slug inalterado;
registrar a alteração em log.

Obtaining Riot ID from summonerID

Quando existir somente summonerID, resolver primeiro o PUUID e depois o Riot ID:

summonerID
  -> SUMMONER-V4 by summonerID no host de plataforma BR1
    -> PUUID
      -> ACCOUNT-V1 by-puuid no host regional AMERICAS
        -> gameName + tagLine

Endpoint oficial para a primeira etapa:

GET https://br1.api.riotgames.com/lol/summoner/v4/summoners/{encryptedSummonerId}

Referência: SUMMONER-V4 GET_getBySummonerId

Summoner Names Post Migration

A Riot migrou a identificação legível para Riot ID em 20 de novembro de 2023.

Consequências práticas:

campos e formulários para players devem usar Riot ID: gameName + tagLine;
o endpoint legado SUMMONER-V4 by-name está depreciado;
summonerName pode ficar desatualizado;
novos summoners após a migração podem receber um valor aleatório no campo legado;
não criar dependências novas baseadas em summonerName;
a FAQ oficial informa que não existe endpoint direto para converter Riot ID em summonerName ou summonerName em Riot ID.

Endpoint legado a evitar:

GET /lol/summoner/v4/summoners/by-name/{summonerName}

Regras de Riot ID

Segundo a FAQ oficial consultada:

gameName: de 3 a 16 caracteres;
não usar # dentro de gameName;
tagLine: de 3 a 5 caracteres alfanuméricos;
letras Unicode são aceitas nos dois campos.

Ao montar URLs, codificar gameName e tagLine como segmentos de path. Isso é necessário para nomes com espaços e caracteres Unicode, como os já presentes em fuji, be e joao.

Decisões para a skill de resolução

A futura skill lol-riot-resolve-player deve:

receber um player_slug válido de PLAYER_REGISTRY;
ler o Riot ID estruturado do registry;
chamar ACCOUNT-V1 by-riot-id para obter PUUID;
chamar SUMMONER-V4 by-puuid para obter summonerID;
validar a consistência dos campos retornados;
persistir cada resposta original em raw/players/<player-slug>/riot-api/ sem sobrescrever arquivos existentes;
atualizar registry e página do player somente após respostas válidas;
nunca gravar API key, token ou segredo no vault;
tratar erros por status HTTP, sem depender da estrutura do corpo de erro;
interromper ou reagendar chamadas após 429, respeitando o header Retry-After.

Nome sugerido para fontes imutáveis:

raw/players/<player-slug>/riot-api/<timestamp>-account-v1-by-riot-id.json
raw/players/<player-slug>/riot-api/<timestamp>-summoner-v4-by-puuid.json

Primeira implementação disponível:

skills/get-players-puuid/

Ela cobre a etapa ACCOUNT-V1 by-riot-id: preenche puuid e puuid_source
nas páginas de players. A resolução de summonerID continua como etapa
posterior.

Descoberta de partidas recentes do grupo

Script disponível:

scripts/get-team-recent-matches

Para cada player cadastrado, consulta:

GET https://americas.api.riotgames.com/lol/match/v5/matches/by-puuid/{puuid}/ids?start=0&count=5

Referência: MATCH-V5 GET_getMatchIdsByPUUID

Cada resposta original é preservada em:

raw/players/<player-slug>/riot-api/<timestamp>-match-v5-by-puuid-ids-start-0-count-5.json

A saída JSON contém apenas partidas presentes nas listas recentes de pelo menos
dois membros cadastrados:

[
  {
    "Match": "MATCH_CODE",
    "players": ["bastardo", "be"]
  }
]

Payload completo de partidas pendentes

Skill disponível:

skills/fetch-pending-match-data/

Para cada página de partida com analyzed: false que ainda não possui payload
completo persistido, consulta:

GET https://americas.api.riotgames.com/lol/match/v5/matches/{matchId}

Referência: MATCH-V5 GET_getMatch

Cada resposta original válida é preservada sem reescrita em:

raw/matches/<match-id>/riot-api.json

A página compilada correspondente recebe um item em raw_sources:

raw_sources:
  - raw/matches/<match-id>/riot-api
  - raw/matches/<match-id>/analysis-input

Esta etapa hidrata evidência objetiva e não altera analyzed: false. A análise
estratégica pertence a uma skill posterior.

Após validar o payload completo, a skill executa
scripts/extract-match-analysis-input --match-id <match-id>. O script gera um
resumo compacto em raw/matches/<match-id>/analysis-input.json com contexto,
objetivos, composições e métricas relevantes para análise geral e dos players
cadastrados.

Em seguida, scripts/update-match-wiki-from-analysis-input --match-id <match-id> projeta fatos objetivos na página compilada: data, patch, fila,
resultado do grupo cadastrado, duração, objetivos, composições e placares. O
campo analyzed permanece false até a análise estratégica posterior.

Segurança e chaves

Usar HTTPS.
Não incluir API key no código, no vault ou em logs.
Injetar credenciais em runtime por mecanismo externo ao vault. Nesta workspace,
a chave fica no macOS Keychain e é lida pelo helper local
scripts/riot-api-key.
Chaves de desenvolvimento expiram a cada 24 horas segundo a documentação do Developer Portal.
Para uso privado do grupo, avaliar uma personal key ao registrar o projeto.

Quartz 5

Explorer

riot-id-resolution

Riot API: Riot ID, PUUID e summonerID

Objetivo

Roteamento

Obtaining PUUID and summonerID from RiotID

Etapa 1: Riot ID para PUUID

Etapa 2: PUUID para summonerID

Obtaining Riot ID from PUUID

Obtaining Riot ID from summonerID

Summoner Names Post Migration

Regras de Riot ID

Decisões para a skill de resolução

Descoberta de partidas recentes do grupo

Payload completo de partidas pendentes

Segurança e chaves

Fontes oficiais

Notas manuais

Graph View

Table of Contents

Backlinks