Vincular um personagem

Antes que um personagem possa comprar ou vender na Lootfy, ele precisa estar vinculado a uma conta Lootfy. O vínculo é o que amarra um personagem do seu servidor a uma pessoa real com CPF, e-mail e dados de recebimento — é o que permite que o dinheiro de uma venda tenha um dono. Esta página descreve o fluxo de vincular personagem (POST /v1/api/character-links), que cria esse vínculo a partir do jogo.

Para o dono de servidor: vincular é como conectar a conta do jogo à conta da Lootfy. O seu servidor abre o pedido, a Lootfy gera um link, e o próprio jogador conclui logando na Lootfy. Você nunca manuseia a senha nem os dados da pessoa — só dá o empurrão inicial.

Como funciona

O vínculo tem três passos e cada um é de um ator diferente: o seu servidor inicia, a plataforma hospeda a confirmação, e a pessoa fecha o vínculo autenticada.

1. O seu servidor inicia o vínculo. Dentro do jogo, o jogador pede para vincular. O seu servidor chama a plataforma (POST /v1/api/character-links) informando o characterRef e o nome do personagem. A plataforma responde com uma url de uso único.

2. O jogador abre a URL no navegador. Você exibe ou abre essa url para ele. Ela leva a uma página da Lootfy que pré-visualiza o vínculo — qual personagem, qual servidor — sem consumi-lo.

3. O jogador confirma logado. Autenticado na conta Lootfy dele (ou criando uma na hora), ele confirma. Nesse instante o personagem passa a ser daquela conta. É a pessoa quem fecha o vínculo, pela web — não o seu servidor.

Um personagem, uma conta

O vínculo é 1:1: um personagem pertence a exatamente uma conta Lootfy, e o link é de uso único com TTL curto. Isso impede que um link vazado seja reaproveitado e que um personagem seja reivindicado por duas contas.

A chamada — vincular personagem ✅ disponível

Esta rota é service: exige a API key no header X-Service-Api-Key e a assinatura JWS. Como é o seu servidor quem chama (não o client), o jti funciona como nonce — gere um novo a cada tentativa.

POST /v1/api/character-links
X-Service-Api-Key: <sua-api-key>
X-Lootfy-Signature: <protegido>..<assinatura>
Content-Type: application/json

{ "characterRef": "char-123", "name": "Lucasss_" }

// 200
{ "data": {
    "linkId": "8f2c1a9b-...",
    "url": "https://api.lootfy.gg/v1/character-links/8f2c1a9b-...",
    "expiresAt": "2026-09-14T12:10:00.000Z"
} }

Abra a url no navegador do jogador. O expiresAt diz até quando ela vale — expirada, é só iniciar o vínculo de novo.

As rotas que fecham o ciclo (não são suas)

Os dois passos seguintes acontecem na web, com o jogador. Você não os chama, mas conhecê-los ajuda a entender o fluxo:

• Pré-visualizar — GET /v1/character-links/{linkId} público — mostra o personagem e o servidor do processo sem consumir o link. É o que a página de confirmação usa para exibir “você está vinculando o personagem X do servidor Y”.
• Confirmar — POST /v1/character-links/{linkId}/confirm bearer — exige o jogador logado. É aqui que o vínculo se fecha, associando o personagem à conta autenticada.

O que não existe: confirmar posse do personagem (planejado)

O contrato original previa uma rota de “confirmar posse de personagem”, em que o servidor selaria o vínculo de volta. Essa rota não foi implementada, e não faz falta. O vínculo se fecha inteiramente pela web, quando a pessoa confirma logada (vincular personagem + a rota de confirm). Não há nada travando o seu lado à espera de uma confirmação do servidor — o personagem já está vinculado no instante em que a pessoa clica.

Sem vínculo, nada de comércio

Um personagem não vinculado não aparece como comprador nem como vendedor. Ao tentar anunciar, a recusa vem com o motivo NOT_LINKED; ao tentar comprar, a criação da transação é recusada. Vincular é o pré-requisito de tudo que vem depois nesta seção.

Próximo: registrar e sincronizar anúncios Com o personagem vinculado, o vendedor pode publicar um anúncio — registrar anúncio (POST /v1/api/market/listings) e ajustar ou retirar anúncio (PUT /v1/api/market/listings).