Registrar e sincronizar anúncios

Um anúncio é o registro, na Lootfy, de que um item está à venda no market do seu jogo — com item, descrição, quantidade e preço em reais. Registrar o anúncio é o que torna um item comprável pela plataforma; manter o anúncio sincronizado com o que de fato existe no jogo é o que impede a plataforma de vender o que já foi consumido. Esta página cobre os dois lados: registrar (POST /v1/api/market/listings) e manter (PUT /v1/api/market/listings).

Para o dono de servidor: quando um jogador coloca um item à venda no seu market, o seu servidor espelha esse anúncio na Lootfy. Se depois o item some — vendido pela moeda do jogo, ou retirado —, o seu servidor avisa. Esse espelhamento constante é o que evita que alguém pague por um item que não está mais lá.

Antes de anunciar: as três pré-condições do vendedor

O anúncio só nasce se o vendedor cumprir três condições, todas obrigatórias:

1. ter conta Lootfy;
2. ter o personagem vinculado (ver Vincular um personagem);
3. ter um recebedor aprovado no PSP — é o que dá destino à fatia dele quando o dinheiro for dividido.

Faltando qualquer uma, o registro é recusado com um 400 que diz qual delas falta. A message já vem em pt-BR pronta para exibir ao jogador — repasse-a.

O vendedor resolve as duas primeiras sozinho, pela plataforma

Conta e recebedor são autogestão: o vendedor cria a conta e cadastra o recebedor (CPF, telefone e conta bancária) direto na plataforma, em Perfil → Recebimento — não é algo que o seu servidor faz por ele. O vínculo do personagem é o único que parte do jogo (é o passo que o seu servidor inicia). Ou seja: o seu papel aqui é só registrar o anúncio; garantir conta e recebedor é do próprio jogador.

Pré-checar antes de tentar ✅ disponível

Descobrir a recusa só ao tentar anunciar é ruim: o jogador preenche item, quantidade e preço para então levar um 400. A rota de elegibilidade responde isso antes, para você desabilitar (ou explicar) a opção de anunciar já na tela do jogo.

GET /v1/api/market/eligibility/char-777
X-Service-Api-Key: <sua-api-key>
X-Lootfy-Signature: <protegido>..<assinatura>

// 200
{ "data": {
    "allowed": false,
    "blocker": "SELLING_BLOCKED",          // NOT_LINKED | CHARACTER_BANNED | SELLING_BLOCKED
    "message": "Cadastre seus dados de recebimento para poder vender.",
    "linked": true,
    "banned": false,
    "selling": {
      "allowed": false,
      "blockers": ["RECIPIENT_MISSING"],
      "message": "Cadastre seus dados de recebimento para poder vender.",
      "action": "CREATE_RECIPIENT"
    }
} }

É dica, nunca portão

A elegibilidade é uma dica, jamais uma trava. O estado muda entre consultar e anunciar; quem de fato recusa continua sendo o POST /v1/api/market/listings, que reavalia tudo. O blocker aponta o primeiro impedimento, na mesma ordem em que o registro recusa, e a message é literalmente a mesma string. Personagem inexistente responde 200 com linked: false, nunca 404 — um 404 viraria oráculo para enumerar quais personagens do servidor têm conta Lootfy.

Registrar o anúncio ✅ disponível

Esta é uma das duas rotas signature-only: ela é transportada pelo client do jogo, que não pode carregar a sua API key. A identidade é o kid da assinatura, sozinho.

POST /v1/api/market/listings
X-Lootfy-Signature: <protegido>..<assinatura>
Content-Type: application/json

{
  "itemRef": "srv-offer-9931",
  "gameItemId": "bow-9",
  "itemName": "Arco Élfico",
  "attributes": "Ataque 140, Destreza +12, Encantado com Fogo",
  "quantityListed": 5,
  "unitAmountCents": 7000,
  "sellerCharacterRef": "char-777"
}

// 200
{ "data": {
    "id": 88,
    "itemRef": "srv-offer-9931",
    "gameItemId": "bow-9",
    "itemName": "Arco Élfico",
    "attributes": "Ataque 140, Destreza +12, Encantado com Fogo",
    "unitAmountCents": 7000,
    "quantityListed": 5,
    "quantitySold": 0,
    "observedQuantity": null,
    "observedAt": null,
    "status": "ACTIVE",
    "createdAt": "2026-09-14T12:00:00.000Z",
    "updatedAt": "2026-09-14T12:00:00.000Z",
    "withdrawnAt": null
} }

Os campos que exigem atenção:

• itemRef identifica o anúncio e é a chave por onde ele é reencontrado depois (para ajustar ou retirar). É único por servidor e não reciclável: repetir um itemRef já usado responde 409, mesmo que o anúncio anterior já esteja retirado. Escolha um valor que sobreviva a um ciclo de save do seu servidor — é a capacidade B1 dos pré-requisitos.
• attributes é texto livre, montado por você — até 255 caracteres, e vazio é recusado. A plataforma não interpreta, não quebra em pares e não reformata: exibe como veio. Ele é a descrição do item para o comprador e a prova do que foi prometido numa disputa.
• unitAmountCents é o preço unitário em centavos. É aqui que o preço é declarado — ele não viaja na compra depois.

jti é chave de idempotência aqui

Como registrar anúncio é transportado pelo client, retry de rede e replay são bit a bit idênticos. Por isso o jti desta rota é chave de idempotência: a segunda chegada do mesmo jti devolve o mesmo anúncio, nunca um erro nem um segundo registro. Isso é o oposto das rotas service, onde repetir o jti dá 401. Detalhe em Assinatura JWS na prática.

Manter o anúncio ✅ disponível

O anúncio, uma vez registrado, só encolhe pelas próprias vendas da plataforma. Mas a moeda do jogo pode consumir a mesma listagem sem passar por nós, e o vendedor pode simplesmente retirar o item. Ajustar ou retirar anúncio (PUT /v1/api/market/listings) é como você conta isso à plataforma. É uma rota service (API key + JWS), servidor→servidor.

Ela tem duas ações:

Ajustar o estoque

PUT /v1/api/market/listings
X-Service-Api-Key: <sua-api-key>
X-Lootfy-Signature: <protegido>..<assinatura>
Content-Type: application/json

{ "action": "ADJUST_STOCK", "itemRef": "srv-offer-9931", "observedQuantity": 3 }

Informa a quantidade que o servidor observa disponível agora. observedQuantity: 0 marca o anúncio como esgotado sem retirá-lo — uma observação futura pode corrigi-lo para cima.

Retirar o anúncio

PUT /v1/api/market/listings
X-Service-Api-Key: <sua-api-key>
X-Lootfy-Signature: <protegido>..<assinatura>
Content-Type: application/json

{ "action": "WITHDRAW", "itemRef": "srv-offer-9931" }

Retira o anúncio de vez. WITHDRAW é definitivo: um anúncio retirado não volta a ficar ativo por observação de estoque.

Chame sempre que a moeda do jogo consumir a listagem

Ajustar ou retirar anúncio é a única fonte que corrige o disponível antes de alguém tentar comprar. Sem ele, a plataforma vende o que não existe mais, e o desfecho é estorno — que a plataforma paga do próprio bolso. Manter essa sincronia é a capacidade C2 dos pré-requisitos, e depende de você ter um registro local durável do que anunciou (capacidade B2).

Como esta é uma rota service, o jti é nonce: gere um novo a cada chamada. Repetir o mesmo envelope responde 401 Requisição já processada.

Próximo: criar e acompanhar transações Com anúncios no ar, um comprador gera um pedido de compra — criar transação (POST /v1/api/transactions) e consultar transação (GET /v1/api/transactions/{transactionId}).