Provisionamento e credenciais

Antes de assinar a primeira chamada, o seu servidor precisa de três materiais: uma API key (para dizer quem chama), um par de chaves de assinatura (para provar que foi você) e uma URL de webhook (para receber os avisos da plataforma). Os dois primeiros são gerados pela equipe da Lootfy e entregues a você; o terceiro você configura sozinho pela plataforma.

Para o dono de servidor: pense nisto como retirar as chaves da sua loja. Você recebe uma vez, guarda bem, e não há segunda via — perdeu, refaz. O detalhe importa porque uma dessas chaves, nas mãos erradas, autoriza mover dinheiro.

1. Solicite o provisionamento à equipe da Lootfy

O registro do servidor e a emissão das credenciais de integração são feitos pela equipe da Lootfy — são operações administrativas da plataforma, não algo que você executa. Você abre o pedido, informa os dados do seu servidor e recebe as credenciais prontas.

Isso quem faz é a equipe Lootfy

Para dar início à integração, entre no Discord da Lootfy e abra um pedido no canal #integração. Solicite, de uma vez: o registro do seu servidor, uma API key e o par de chaves de assinatura.

Ao pedir o registro, tenha à mão o nome do servidor e o domínio do seu site (quando houver). As comissões e os limites do servidor são definidos pela plataforma nesse momento — se precisar ajustá-los depois, é também pelo mesmo canal.

2. O que você recebe

Concluído o provisionamento, você recebe um conjunto de credenciais. Alguns valores são entregues uma única vez e não têm segunda via — guarde-os com segurança assim que os receber.

Você recebe	O que é	Reexibível?
serverId	o identificador do seu servidor na plataforma	sim
API key (sk_...)	identifica quem chama nas rotas servidor→servidor; viaja no header X-Service-Api-Key	não — só o prefixo fica visível depois
serverPrivateKeyPem	a SUA chave privada — assina as chamadas que você faz	não — não há re-download
serverKeyKid	o kid da sua chave, que vai no header protegido de cada assinatura sua	sim
platformPublicKeyPem	a chave pública da plataforma — você a usa para validar os webhooks que recebe	sim
platformKeyKid	o kid que a plataforma usa ao assinar; você exige que o webhook traga exatamente este	sim

A API key e a chave privada aparecem uma única vez

Tanto a API key completa quanto o serverPrivateKeyPem são entregues apenas no momento do provisionamento. A plataforma guarda só o hash da API key e a chave pública do seu par — o material secreto não fica com ela. Perdeu algum deles, solicite uma rotação pelo mesmo canal; a rotação tem janela de graça, então a integração não cai no meio. Guarde esses dois valores direto no Agent e em nenhum outro lugar.

Por que são dois kid e duas chaves públicas

A assinatura acontece nos dois sentidos, então existem dois pares de chaves RS256 para o seu servidor — não um:

Par	Quem assina	Quem valida	Onde a privada fica
SERVER	você — criar transação (POST /v1/api/transactions), confirmar entrega (POST /v1/api/transactions/{transactionId}/delivery), reportar falha de entrega (POST /v1/api/transactions/{transactionId}/delivery-failure), vincular personagem (POST /v1/api/character-links), registrar anúncio (POST /v1/api/market/listings) e ajustar ou retirar anúncio (PUT /v1/api/market/listings)	a plataforma	só com você — a Lootfy não a guarda
PLATFORM	a plataforma — webhooks transfer_order e transaction_terminal	você	só com a plataforma

O motivo de a Lootfy nunca guardar a sua chave privada é direto: com ela seria possível forjar uma confirmação de entrega, que é a fonte da verdade da entrega e libera a conclusão de uma transação com dinheiro dentro. Guardá-la esvaziaria o não-repúdio que é a razão de a assinatura ser assimétrica.

3. Onde cada credencial vai

Recebidas as credenciais, elas se distribuem em dois lugares — e nenhum deles é o seu banco de dados:

• No Agent: a API key, o serverPrivateKeyPem e o serverKeyKid. É o Agent que assina e faz as chamadas servidor→servidor. A chave privada não sai dele.
• No seu endpoint de webhook: o platformPublicKeyPem e o platformKeyKid, usados para validar cada webhook que a plataforma manda.

A configuração exata de cada valor no Agent está em Configuração.

4. Configure a URL de webhook (você mesmo)

Diferente do provisionamento, a URL de webhook você configura sozinho, pela plataforma — quem conhece o endpoint do seu jogo é você, não a equipe da Lootfy. No painel, abra o seu servidor → aba Geral e informe a webhookUrl (é para onde a plataforma manda a ordem de transferência e o estado terminal).

Exige https (exceto localhost)

A webhookUrl precisa ser https. http só é aceito em localhost/127.0.0.1, para desenvolvimento. A assinatura garante origem e integridade, não sigilo: o corpo do webhook leva item, quantidade e personagem receptor, e em http isso trafegaria em claro.

Enquanto a URL não existir, nada se perde: as entregas ficam enfileiradas retentando, e drenam sozinhas quando você configurar o destino.

O que mais você faz sozinho pela plataforma

Além da URL de webhook, o painel do seu servidor e o seu perfil já resolvem, sem depender da equipe da Lootfy:

• Dados do servidor: nome, domínio e a logo do servidor — no painel, aba Geral.
• Conferir suas credenciais: a aba Integrações do seu servidor mostra os metadados das suas API keys e chaves de assinatura (prefixo, kid, data) — só para conferência. O material secreto não é reexibido; ele foi entregue no provisionamento. Emitir, rotacionar ou revogar credencial continua sendo um pedido à equipe da Lootfy.
• Dados de recebimento: o cadastro do recebedor (CPF, telefone, conta bancária) fica em Perfil → Recebimento. É o que habilita um vendedor a receber — cada pessoa cadastra o seu.

Checklist do que você deve ter no fim

1. O serverId, que endereça o seu servidor.
2. A API key completa, guardada com segurança — ela não volta a aparecer.
3. serverPrivateKeyPem e serverKeyKid, colocados no Agent e em nenhum outro lugar.
4. platformPublicKeyPem e platformKeyKid, colocados no seu endpoint de webhook para validar o que a plataforma manda.
5. A webhookUrl cadastrada pela plataforma e alcançável por https.

Com isso, você está pronto para configurar o Agent e assinar a primeira chamada.

Próximo: vincular um personagem O primeiro fluxo que você consegue exercitar de ponta a ponta — vincular personagem (POST /v1/api/character-links).