Estoque estimado

O estoque é um dos pontos mais sutis da integração, e entendê-lo evita a maior fonte de confusão do modelo. A ideia acessível primeiro: a Lootfy não é dona do estoque nem sabe com certeza quanto resta de um anúncio. Ela mantém uma estimativa e a usa para uma coisa só — recusar uma compra grande demais. Ela nunca usa essa estimativa para autorizar, porque quem realmente sabe se o item existe é o seu servidor, no momento de entregar.

Por que a Lootfy não pode saber o estoque com certeza

Um anúncio começa com uma quantidade conhecida, mas o estoque some por duas fontes, e a Lootfy só enxerga uma delas:

Compras pela plataforma

Vendas que passam pela Lootfy. Essas ela conhece com precisão — são as próprias transações dela.

Compras com a moeda do jogo

Vendas feitas in-game, na mesma listagem, com a moeda do próprio jogo. A Lootfy não as enxerga, não é notificada e não pode impedi-las.

É a segunda fonte que decide todo o desenho. Qualquer mecanismo em que a Lootfy tentasse arbitrar “quem levou o item” seria ficção: o estoque pode ter ido embora por um caminho que não passa por ela.

A regra de ouro: o estoque só recusa, nunca autoriza

Este é o princípio que você deve levar desta página: a estimativa de estoque da Lootfy é um gate de uma direção só. Ela pode recusar uma compra cuja quantidade exceda o disponível estimado. Ela nunca autoriza: “o anúncio diz 50, então pode pagar” não é uma conclusão válida, porque entre a última informação que a Lootfy teve e agora, a moeda do jogo pode ter esvaziado tudo. Quem arbitra de fato quem leva o item é o seu servidor, na entrega.

Por que a assimetria

Um falso bloqueio custa uma venda que existia; um falso aceite custa um estorno. Como o estorno é caminho previsto e a plataforma absorve a taxa do PSP nele, a Lootfy prefere errar para o lado de deixar passar. Além disso, bloquear por dado velho se auto-alimenta: se ninguém consegue comprar, ninguém entrega, e a informação de estoque nunca se renova.

As duas partes do estoque

O disponível estimado tem duas partes de naturezas diferentes, e confundi-las é a fonte de erro. O disponível é o menor dos dois.

Parte	O que é	Confiabilidade
Exata	quantidade anunciada − quantidade vendida por nós	Precisa — são as vendas da própria Lootfy. Recusa sempre.
Estimada	A última quantidade observada vinda do seu servidor	Estimativa — envelhece sozinha. Só recusa se for recente.

A parte exata não envelhece e recusa sempre: vender mais do que a Lootfy anunciou seria um erro dela, não uma estimativa. A parte estimada corrige para baixo o que a moeda do jogo consumiu sem notificar — mas, como envelhece, ela só bloqueia enquanto a observação é recente (um prazo configurável). Uma observação envelhecida é tratada como desconhecida e deixa passar: é o servidor, na entrega, quem arbitra de fato.

Não existe reserva por transação

Vale reforçar um ponto que decorre disto: a reserva existe, mas é do jogo, por listagem — não da Lootfy, por transação. Quando o vendedor cria a oferta no mercado, o próprio jogo retira a quantidade do inventário dele e a retém na listagem. Isso é mecânica nativa do servidor de jogo, não algo que a Lootfy peça ao seu servidor. A Lootfy não mantém uma reserva em nome de um comprador específico e não pede que o seu servidor implemente uma. O que resta em disputa é apenas a moeda do jogo consumindo a mesma listagem, e quem resolve isso é o servidor, na entrega.

Como o seu servidor sincroniza o estoque

A parte estimada só é útil se for alimentada. A operação que faz isso é ajustar ou retirar anúncio (PUT /v1/api/market/listings) ✅ disponível, chamada pelo seu servidor, e ela tem dois usos:

1. Ajustar o estoque observado (ADJUST_STOCK). O seu servidor informa a nova quantidade disponível de um anúncio, identificado pelo itemRef. É a única fonte que corrige, antes de alguém tentar comprar, o consumo feito pela moeda do jogo. Sem ela, o registro da Lootfy só encolheria pelas próprias vendas — e um item já esgotado in-game continuaria comprável até a entrega falhar.

2. Retirar o anúncio (WITHDRAW). O seu servidor tira o anúncio de circulação — por exemplo, quando o vendedor o remove do mercado do jogo.

Além de ajustar ou retirar anúncio, a estimativa também é corrigida por observações que chegam em outros momentos: a resposta da ordem de transferência (evento transfer_order) devolve o estoque atualizado junto com o aceite, e o reporte de falha de entrega (POST /v1/api/transactions/{transactionId}/delivery-failure) carrega o estoque atualizado — esta última é a observação mais informativa que existe, porque o estoque acabou de furar exatamente ali. O passo a passo dessas chamadas está em Registrar e sincronizar anúncios.

Onde o estoque é reavaliado

O estoque estimado é consultado no momento de criar a transação (POST /v1/api/transactions): se a quantidade pedida excede o disponível estimado, a compra é recusada — respeitando sempre a regra de que estimativa velha não recusa. E é reavaliado de novo no checkout, antes de emitir a cobrança, para não deixar o comprador pagar por algo que a Lootfy já sabe estar acima do que anunciou. Nenhuma dessas checagens autoriza a entrega: a palavra final é sempre do seu servidor, quando a ordem de transferência chega.

Próximo: segurança, assinatura e idempotência Como a Lootfy confia na origem de cada chamada e por que o mesmo jti tem dois papéis opostos.