Disponível vs planejado

Esta página existe para uma coisa: separar o que já funciona do que ainda não foi construído, para que a sua integração não se apoie em algo inexistente. Um portal de documentação é tentado a descrever o sistema completo como se tudo estivesse pronto; aqui a linha é dura. O que está na lista de baixo pode existir como valor de enum, como nome numa ADR, ou como intenção clara de arquitetura — e ainda assim não ter um caminho executável hoje.

Não construa passo a passo sobre o que está aqui embaixo

Se um fluxo depende de algo na seção “Planejado”, ele vai falhar em silêncio ou travar. Não escreva código que aguarde uma transição automática, chame uma rota 📋 ou assuma que um job roda. Quando precisar de algo dessa lista, sinalize a lacuna — não a preencha com suposição.

Disponível hoje ✅

O núcleo da integração de um servidor de jogo está pronto e com contrato estável:

• Vínculo de personagem — abrir o processo pelo jogo (POST /v1/api/character-links) e o jogador confirmar logado no portal.
• Market e anúncios — registrar anúncio (POST /v1/api/market/listings), ajustar estoque e retirar (PUT /v1/api/market/listings), e a pré-checagem de elegibilidade do vendedor.
• Transações e entrega — criar a transação a partir da oferta assinada (POST /v1/api/transactions), consultar estado (GET /v1/api/transactions/{transactionId}), confirmar entrega (POST /v1/api/transactions/{transactionId}/delivery) e reportar falha com motivo (POST /v1/api/transactions/{transactionId}/delivery-failure).
• Checkout e pagamento — o comprador paga a transação via Pix real no checkout web da Lootfy, com split de três destinos e a confirmação do provedor de pagamento levando a transação a PAGO. É a tela da plataforma, não uma rota que o seu servidor chama: o seu servidor só produz a checkoutUrl e recebe o resultado pelo webhook.
• Webhooks de saída — transfer_order (webhook de entrega) e transaction_terminal (webhook de estado terminal), que a Lootfy assina com a chave da plataforma e o seu servidor só verifica.
• Modelo de estado de dois eixos — paymentStatus + deliveryStatus + completedAt, com o par exposto em todas as rotas de transação.

Conta, carteira e recebimento pertencem ao portal do usuário, não à integração do servidor: o usuário cadastra o recebedor, vê saldos e o histórico pela plataforma. Você não chama nada disso do lado do servidor — e a solicitação de saque em si ainda não está fechada (veja abaixo).

Planejado ou incompleto 📋 / 🚧

Nada aqui está pronto para ser consumido em produção. Alguns têm rota, outros nem isso.

• Cancelar transação — 📋 planejado não existe. Não há rota para o servidor cancelar uma transação; hoje o pedido não pago apenas expira por TTL.
• Confirmar posse do personagem — 📋 planejado não existe; o vínculo fecha pela web.
• Saque completo — 🚧 instável a solicitação de saque existe, mas o caminho até o payout efetivo não é exercitável e, na prática, o saque para em SOLICITADO (a aprovação e a liberação são feitas pela plataforma e ainda não estão fechadas). Não construa a experiência de “dinheiro na conta” sobre isso ainda.
• Escrita de disputa — 📋 planejado não há caminho de escrita para abrir ou resolver disputa pela API. A resolução é só do admin, sem estorno parcial.
• Timeout de entrega → EM_DISPUTA — 📋 planejado não há worker. Uma transação cujo servidor nunca responde fica em PAGO / AGUARDANDO_SERVIDOR para sempre; o valor EM_DISPUTA existe no enum, mas nada o produz por tempo.
• Jobs de expiração — 📋 planejado a expiração de transação e a de cobrança Pix não têm job. Um QR vencido continua PENDENTE na nossa base até algo mudar.
• Pipeline de KYC — 📋 planejado não há esteira de análise própria: a verdade do KYC é o status do recebedor no PSP. No sandbox, todo recebedor nasce active, então PENDING e REFUSED não aparecem em teste — trate os três estados mesmo assim.
• JWE (cifra de payload) — 📋 planejado a cifra seletiva de payloads sensíveis está prevista nas invariantes, mas não implementada. Hoje a proteção é a assinatura JWS, que garante origem e integridade, não sigilo.
• Escrita de ban — 📋 planejado não existe o caminho para aplicar um ban pela API. As travas de ban já valem (o vendedor banido não anuncia, o receptor banido não fecha o checkout), mas o registro do ban ainda não tem rota de produto.

Por que algumas coisas parecem existir mas não valem

Um valor de enum como EM_DISPUTA, uma rota como a de saque, um estado como PENDING de recebedor — todos aparecem no contrato, e é fácil supor que funcionam ponta a ponta. Não supunha: a página Endpoints e status diz o que pode ser consumido, e na dúvida o canal #integração no Discord confirma. Só o que está marcado como pronto é pronto.

Endpoints e status A lista das rotas de integração e o status de consumo de cada uma.

Estados da transação O modelo de dois eixos e as transições que já acontecem — e as que ainda não.