Visão geral

Esta seção é o guia de quem está do outro lado: o servidor de jogo que anuncia itens, cria pedidos de compra, confirma entregas e recebe de volta os avisos assinados da plataforma. Ela vale para qualquer engine — o case específico de OpenTibia tem uma seção própria. Aqui o assunto é o contrato: quem chama o quê, como cada chamada é autenticada e em que ordem faz sentido construir.

Se você ainda não leu a parte conceitual, comece por Como funciona. Esta página assume que você já entendeu o desenho geral e quer descer ao nível de rota, payload e assinatura.

Os atores

Uma venda envolve cinco participantes, e entender o papel de cada um explica quase todas as decisões do contrato.

• O seu servidor de jogo. É a autoridade. Ele conhece os itens, os personagens, o estoque e a posse. É ele quem assina toda chamada de saída e é ele quem entrega o item dentro do jogo. Nada de valor acontece sem que ele diga.
• O client do jogo (a máquina do jogador). É transporte e interface, nunca autor. Ele desenha botões e leva envelopes já assinados até a plataforma, mas roda na máquina do jogador — território hostil — e por isso jamais decide preço, quantidade ou entrega.
• A plataforma (Lootfy). Registra anúncios, cria transações, cobra o comprador via Pix, divide o dinheiro e envia ao seu servidor a ordem de transferência quando o pagamento é confirmado.
• O PSP (provedor de pagamento). Custodia o dinheiro, executa o split e paga os saques. A Lootfy nunca segura dinheiro — a carteira é apenas um espelho.
• Comprador e vendedor. As pessoas. Elas se autenticam no checkout web da plataforma para pagar e para gerenciar recebimentos.

A arquitetura, em uma frase

O servidor assina, o client transporta, a plataforma verifica — e responde de volta com webhooks que o servidor verifica.

Duas propriedades sustentam o desenho inteiro e vale fixá-las antes de qualquer rota:

• O servidor é quem assina, sempre. Toda chamada ao contrato leva uma assinatura JWS RS256. Como o engine da família TFS não tem criptografia de chave pública, essa assinatura costuma nascer fora do engine, num componente lateral. Esse componente é o Agent — ele guarda a chave privada e assina sob demanda, sem que o Lua do seu servidor jamais a veja. Ele é “a caneta”: assina e transporta, nunca decide regra de negócio.
• O preço nunca viaja pelo client. O valor é declarado ao registrar o anúncio (POST /v1/api/market/listings) e a plataforma multiplica. A oferta de compra transportada pelo client carrega só o mínimo que apenas o servidor conhece: qual anúncio, que quantidade e qual personagem está comprando.

Por que o client nunca assina

Assinatura prova quem assinou, não que o assinado é verdade. Se o assinante fosse o comprador, uma assinatura válida sobre “preço = 1 centavo” passaria em toda checagem. Por isso a autoridade é sempre o servidor, e o client é apenas o carteiro do envelope.

O ciclo completo

   VOCÊ (servidor do jogo)                      PLATAFORMA
   ─────────────────────────                    ──────────────────────────

   vendedor põe item no market
        │  POST /v1/api/market/listings
        └──────────────────────────────────────▶ anúncio registrado
                                                 (item, atributos, preço)

   moeda do jogo consumiu / vendedor retirou
        │  PUT /v1/api/market/listings
        └──────────────────────────────────────▶ estoque observado corrigido

   comprador clica em comprar, no jogo
        │  POST /v1/api/transactions
        │  (oferta assinada, TRANSPORTADA pelo client)
        └──────────────────────────────────────▶ transação criada
                                                 devolve checkoutUrl
                                                        │
                                       o jogador abre a URL no browser,
                                       paga o Pix, o PSP confirma
                                                        │
   ordem de transferência                               ▼
        ◀──────────────────────────────────────  webhook transfer_order (assinado por NÓS)
        │  você entrega o item in-game
        │
        ├─ deu certo → POST /v1/api/transactions/{id}/delivery
        │                                       ──────▶ PAGO / ENTREGUE
        │
        └─ não deu   → POST /v1/api/transactions/{id}/delivery-failure
                                                ──────▶ OUT_OF_STOCK: estorna
                                                        TEMPORARY: reenfileira

   estado terminal
        ◀──────────────────────────────────────  webhook transaction_terminal (assinado por NÓS)

A ordem recomendada de implementação

Construa nesta sequência — cada passo destrava o anterior, e você consegue testar ponta a ponta antes de escrever o próximo.

1. Provisionar credenciais. Solicite à equipe da Lootfy, pelo canal #integração no Discord, o registro do servidor, a API key e o par de chaves de assinatura. Depois configure a URL de webhook você mesmo, pela plataforma. Ver Provisionamento e credenciais.

2. Subir o Agent. É ele que assina e transporta. Coloque a chave privada nele e valide que ele responde no loopback. Ver O que é o Agent.

3. Vincular um personagem. Sem vínculo, ninguém compra nem vende. É o fluxo mais simples e o primeiro que você consegue exercitar de ponta a ponta. Ver Vincular um personagem.

4. Registrar e sincronizar anúncios. Publique um anúncio e aprenda a corrigir o estoque quando a moeda do jogo consumir a mesma listagem. Ver Registrar e sincronizar anúncios.

5. Criar e acompanhar transações. Gere um pedido de compra a partir de um anúncio e consulte o estado dele. Ver Criar e acompanhar transações.

6. Fechar o checkout. Acompanhe o comprador pagando o Pix no navegador. Você não implementa essa tela, mas precisa entender o que acontece nela. Ver Checkout e pagamento.

7. Receber o webhook e entregar. O último e mais delicado passo: validar a ordem de transferência assinada, entregar o item e confirmar. Ver Webhook e entrega.

Antes de tudo isso: você é capaz?

Existe uma leitura anterior a esta ordem — as capacidades A–D que o seu engine precisa ter para integrar (assinar, não travar o loop do jogo, ancorar o anúncio de forma durável). Se você ainda está decidindo se dá para integrar, comece pelos Pré-requisitos.

Para que serve cada modo de autenticação

Cada rota declara um authMethod. Você vai encontrar estes ao longo da seção, e a diferença entre eles não é burocrática — ela reflete quem faz a requisição HTTP.

Modo	Como se autentica	Usado quando
public	nenhuma credencial	rota aberta (ex.: pré-visualizar um vínculo)
bearer-only	JWT do usuário no header Authorization	é uma pessoa logada agindo (o comprador no checkout, o jogador confirmando um vínculo)
signature-only	só a assinatura JWS, sem API key	o envelope é transportado pelo client do jogo, que não pode carregar API key (criar transação, registrar anúncio)
service-only	API key X-Service-Api-Key + assinatura JWS	é o servidor chamando a plataforma, servidor→servidor (consultar transação, confirmar entrega, reportar falha de entrega, vincular personagem, ajustar ou retirar anúncio, e elegibilidade)
service-or-bearer	API key + JWS ou JWT	a rota aceita tanto o servidor quanto uma pessoa
client-only	credencial de client	uso interno de client; você não encontra nas rotas de integração

A diferença que mais importa para você é entre signature-only e service-only. Nas rotas signature-only, o kid da assinatura é a identidade — não há segunda fonte com que cruzar, e é por isso que elas são alcançáveis de qualquer IP. Nas rotas service-only, a API key diz quem chama e a assinatura tem de concordar: chave de um servidor com credencial de outro é recusada. Detalhe completo em Assinatura JWS na prática.

As páginas desta seção

Pré-requisitos (capacidades A–D) O que o seu engine precisa ser capaz de fazer antes de integrar.

Provisionamento e credenciais API key, par de chaves JWS e URL de webhook.

Vincular um personagem Vincular personagem (POST /v1/api/character-links) — associar um personagem a uma conta Lootfy.

Registrar e sincronizar anúncios Registrar anúncio e ajustar ou retirar anúncio — publicar, ajustar estoque e retirar.

Criar e acompanhar transações Criar transação e consultar transação — a oferta de compra e o estado do pedido.

Checkout e pagamento O que acontece quando o comprador abre a URL e paga o Pix.

Webhook e entrega Webhooks transfer_order e transaction_terminal, e confirmar entrega ou reportar falha — validar a ordem, entregar e confirmar.

Assinatura JWS na prática A mecânica detalhada da assinatura destacada e da validação.

Próximo: pré-requisitos As capacidades A–D que o seu servidor precisa entregar antes de olhar rota e payload.