Endpoints e status

Esta página é o índice de consulta rápida das rotas que importam para quem integra um servidor de jogo com a Lootfy. Ela é um mapa: diz o que existe e qual a forma geral. A forma exata de cada rota — campos, tipos, obrigatoriedade, enums — está nas páginas de fluxo do Guia de Integração, com exemplos reais de request e response. Trate o que está aqui como orientação de navegação.

Antes de escrever qualquer chamada, guarde duas regras. A primeira: só consuma o que está marcado como pronto. Uma rota 🚧 tem contrato instável e pode mudar sem aviso; uma 📋 ainda não existe; uma ⛔ existe mas é ferramenta de desenvolvimento, nunca produto. A segunda: o Lootfy expõe muitas rotas de conta, perfil e administração que não fazem parte da integração do jogo — elas servem ao portal do usuário e ao painel do admin. Esta página lista só o que o seu servidor, o client do jogo ou o comprador tocam no fluxo de venda.

Legenda de status

✅ pronto implementado, contrato estável, pode consumir. 🚧 instável existe no spec, contrato pode mudar. 📋 planejado ainda não existe. ⛔ dev existe, mas é uso interno/desenvolvimento, nunca produto.

Base URL e forma da resposta

Em desenvolvimento, a base é http://localhost:3000/v1; em produção, https://api.lootfy.gg/v1. Todas as rotas ficam sob o prefixo v1, com a única exceção do health check interno. Sucesso com corpo vem sempre embrulhado em data; PUT e DELETE sem retorno respondem vazio; erro é { "message": string } na raiz, sem envelope. Toda rota responde 200 no caminho feliz, inclusive POST. Valores monetários são inteiros em centavos, e datas são ISO-8601 em UTC.

Vínculo de personagem

O primeiro passo de qualquer venda: o jogador precisa ligar o personagem do jogo à conta Lootfy. O servidor abre o processo de vínculo; o jogador confirma logado no portal.

Operação	Rota	Auth	Status	O que faz
Vincular personagem	POST /v1/api/character-links	service	✅ pronto	Inicia um vínculo a partir do jogo e devolve o link de uso único (linkId, url, expiresAt).

Market e anúncios

O servidor registra na Lootfy os anúncios que o jogador criou no market do jogo, ajusta o estoque observado e retira quando a oferta some. A pré-checagem diz, antes de tentar, se o personagem pode anunciar.

Operação	Rota	Auth	Status	O que faz
Registrar anúncio	POST /v1/api/market/listings	signature-only	✅ pronto	Registra um anúncio anunciado por um vendedor dentro do jogo. Envelope assinado, transportado pelo client.
Ajustar ou retirar anúncio	PUT /v1/api/market/listings	service	✅ pronto	Ajusta o estoque observado de um anúncio (ADJUST_STOCK) ou o retira (WITHDRAW).
Consultar elegibilidade do vendedor	GET /v1/api/market/eligibility/{characterRef}	service	✅ pronto	Diz se um personagem pode anunciar e, quando não pode, o que falta. É dica, nunca portão.

attributes é texto livre

O campo attributes do anúncio é uma string única montada pelo client do jogo (era um mapa chave-valor até 2026-08-20). Renderize como um parágrafo e não invente separador: "Ataque 140, Destreza +12, Encantado com Fogo" é texto livre, sem estrutura garantida. Limite de 255 caracteres; vazio é recusado com 400.

Transações e entrega

A transação nasce de uma oferta de compra assinada, transportada pelo client. Depois de paga, o servidor confirma a entrega do item — ou reporta por que não conseguiu entregar.

Operação	Rota	Auth	Status	O que faz
Criar transação	POST /v1/api/transactions	signature-only	✅ pronto	Cria uma transação a partir de uma oferta de compra assinada. O corpo leva só itemRef, quantity e buyerCharacterRef — sem preço, que a plataforma resolve.
Consultar transação	GET /v1/api/transactions/{transactionId}	service	✅ pronto	Devolve o estado atual de uma transação do servidor que consulta.
Confirmar entrega	POST /v1/api/transactions/{transactionId}/delivery	service	✅ pronto	Confirma que o servidor transferiu o item de uma transação paga. É a fonte da verdade da entrega.
Reportar falha de entrega	POST /v1/api/transactions/{transactionId}/delivery-failure	service	✅ pronto	Reporta que a entrega não foi possível, com o motivo (OUT_OF_STOCK estorna; TEMPORARY mantém em PAGO e reenfileira).

Confirmar entrega não tem corpo, mas o parser exige um

POST sem corpo com Content-Type: application/json responde 400 (“Body cannot be empty…”). A confirmação de entrega não tem quantidade a informar — entrega é tudo ou nada —, então mande {} ou omita o Content-Type. É comportamento do parser do Fastify, não da rota.

Checkout (comprador, web)

O pagamento acontece no checkout web da Lootfy, operado pelo comprador autenticado — não é uma superfície que o seu servidor integra, então as rotas de checkout não entram neste índice. O seu servidor produz a checkoutUrl ao criar a transação e a entrega ao jogador; o resultado do pagamento chega ao seu servidor pelo webhook transfer_order e pode ser consultado por GET /v1/api/transactions/{transactionId}. O que se passa nessa tela, do seu ponto de vista, está em Checkout e pagamento.

Webhooks (a plataforma chama você)

Estes dois não são rotas que você chama — é a Lootfy que faz a chamada, assinada com a chave da plataforma, contra o webhookUrl que o gestor do servidor configurou. O seu endpoint só verifica a assinatura e responde; nunca assina. O contrato deles está documentado aqui e em Webhook e entrega.

Operação	Evento	Direção	Status	O que faz
Ordem de transferência (webhook de entrega)	transfer_order	Lootfy → servidor	✅ pronto	Ordem de transferência do item ao comprador, disparada quando o pagamento é confirmado. A resposta precisa devolver { observedQuantity }.
Estado terminal (webhook)	transaction_terminal	Lootfy → servidor	✅ pronto	Avisa que a transação chegou a um estado terminal (CONCLUIDA, ESTORNADA, EXPIRADA ou CANCELADA), para o servidor destravar o item.

O webhook exige https

O webhookUrl precisa ser https (só localhost/127.0.0.1 aceita http, para desenvolvimento). O JWS garante origem e integridade, não sigilo, e o corpo carrega item, quantidade e personagem — em http isso trafega em claro. O endpoint deve ser idempotente por transactionId: a entrega é at-least-once.

Fora do escopo de integração

Boa parte do que a plataforma faz não é chamada pelo seu servidor e, por isso, fica fora deste contrato de integração:

• Portal do usuário (você faz pela plataforma, logado): autenticação e 2FA, perfil e sessões, cadastro de recebimento, carteira e compras. São telas do site, não rotas que o jogo chama.
• Operações administrativas da plataforma (a equipe da Lootfy faz): registrar o servidor, emitir a API key e gerar as chaves de assinatura, além de comissões, aprovação de saque e gestão de contas. Você não executa essas operações — você as solicita. Para o provisionamento inicial, veja Provisionamento e credenciais.

Se você está integrando um servidor, o que importa para anunciar, vender e entregar são as rotas de parceiro e os webhooks acima. O que ainda não existe (cancelar transação, confirmar posse, escrita de disputa, saque completo) está na página Disponível vs planejado.

A forma exata de cada rota

Esta página diz o que existe e qual a forma geral. O corpo e a resposta de cada rota, campo a campo, estão nas páginas de fluxo do Guia de Integração — cada uma traz exemplos reais de request e response. Se ainda restar dúvida sobre um campo, um tipo ou um enum, pergunte no canal #integração do Discord antes de assumir.

Modos de autenticação Que header cada rota espera e por que criar transação e registrar anúncio são signature-only.

Estados da transação O modelo de dois eixos: paymentStatus, deliveryStatus e completedAt.