Glossário

Esta página reúne os termos que você vai encontrar ao longo de toda a documentação. Sempre que um conceito precisar de mais profundidade, há um link para a página que o desenvolve.

Anúncio (listing)

Um item colocado à venda no mercado do jogo e registrado na Lootfy no instante em que o vendedor o publica. Carrega o item, seus atributos, a quantidade listada, o valor unitário e o personagem vendedor. Um anúncio só nasce se o vendedor tiver conta na Lootfy, personagem vinculado e recebedor aprovado. É o que faz o preço ser um registro da Lootfy, e não um dado que viaja no momento da compra. Veja Registrar e sincronizar anúncios.

Transação

Uma venda de um item digital, de uma quantidade escolhida pelo comprador dentro de um anúncio. A transação nasce sempre no servidor do jogo; a Lootfy nunca cria uma por conta própria. Coloquialmente é chamada de “pedido”. Veja Estados da transação.

Envelope assinado

Um JWS emitido pelo servidor do jogo e transportado pelo client até a Lootfy. Existem duas formas: o anúncio e a oferta de compra (que não carrega preço). Ambos carregam um jti e uma validade (exp) curta. Veja Assinatura JWS na prática.

item_ref

O identificador do anúncio no mercado do seu servidor, fornecido pelo próprio servidor. É a chave pela qual a Lootfy armazena o anúncio e faz a contabilidade de estoque. É de escolha e namespace local do parceiro — a Lootfy não impõe formato. Um anúncio tem estoque e quantidade, e vários compradores podem comprar fatias do mesmo item_ref.

Estoque estimado

O que a Lootfy acredita que ainda resta de um anúncio. Tem duas partes: a exata (quantidade listada menos quantidade que vendemos) e a estimada (última quantidade observada a partir do servidor). O disponível é o menor dos dois. Esse número só recusa, nunca autoriza uma venda. Veja Estoque estimado.

PSP (provedor de pagamento)

O provedor externo (Pagar.me) que custodia o dinheiro, executa o split e realiza os saques. A Lootfy não guarda dinheiro; ela apenas comanda o PSP. Veja Dinheiro: custódia, split e carteira.

Recebedor

Uma identidade financeira dentro do PSP, uma por pessoa, criada após a análise (KYC) do provedor. Cada vendedor individual tem a sua. O servidor do jogo não tem recebedor próprio: a fatia do servidor cai no recebedor do gestor. A plataforma tem um recebedor único de configuração.

Carteira

Um espelho contábil do saldo do recebedor no PSP. Não é dinheiro guardado pela Lootfy. Expõe o disponível, o que está a caminho e o histórico de saques.

Split de pagamento (três destinos)

A divisão do valor bruto de cada venda entre vendedor, plataforma e servidor. A taxa do próprio PSP é debitada da fatia da plataforma. Um destino cuja fatia seja zero não entra no split. Veja Dinheiro: custódia, split e carteira.

Custódia

A retenção do dinheiro, feita pelo PSP e não pela Lootfy. O mecanismo é o split nativo do provedor com a saída controlada por comando. “Escrow” pode ser usado como sinônimo conceitual.

Checkout

A página web voltada ao comprador, endereçada por um handle opaco. O comprador precisa estar autenticado na conta dona do personagem recebedor para pagar. Veja Checkout e pagamento.

Handle

Uma sequência aleatória de 32 bytes na URL do checkout. O handle não é o id da transação: ele endereça o pedido nas chamadas de checkout. O id serial é apenas para exibição (“Pedido nº 1042”).

paid_at

O horário de confirmação do pagamento, reportado pelo PSP no webhook (quando o Pix foi de fato pago). Não confundir com received_at (quando o endpoint de webhook da Lootfy recebeu o evento).

Personagem e vínculo

Um personagem pertence a um servidor e se associa a uma única conta Lootfy (relação 1:1). O vínculo é essa associação, comprovada por posse. Veja Vincular um personagem.

JWS e JWE

JWS é a assinatura, que garante autenticidade e integridade e é obrigatória nos dois sentidos da comunicação. JWE é a cifragem, aplicada de forma seletiva para confidencialidade; no escopo atual ela não é exercida, porque nenhum payload carrega dados pessoais fortes.

Agent

O componente que o parceiro roda ao lado do seu servidor para assinar e transportar as chamadas à Lootfy. Ele é “a caneta”: assina o que o servidor manda assinar, mas não decide regra de negócio nem acessa o banco do parceiro. Veja O que é o Agent.