Referência do servidor

O API app chama seu próprio servidor com sua chave secreta. Verifique sessões, liste produtos, confirme, entregue e reembolse cobranças, pague recompensas da sua pool, envie notificações, verifique anúncios e liste tabelas públicas.

#Noções básicas

Chame apenas do seu servidor. Sua chave é secreta: nunca coloque-a na sua página.

curl https://api.lialabs.org/api/apps/v1/pool \
  -H "Authorization: Bearer $LIA_KEY"

Um pequeno ajudante usado nos exemplos abaixo:

const LIA = "https://api.lialabs.org/api/apps/v1";

export async function lia(method, path, body) {
  const res = await fetch(LIA + path, {
    method,
    headers: { Authorization: `Bearer ${process.env.LIA_KEY}`, "Content-Type": "application/json" },
    body: body === undefined ? undefined : JSON.stringify(body),
  });
  const data = await res.json();
  if (!res.ok) throw Object.assign(new Error(data.error), { status: res.status, data });
  return data;
}

#Chaves e modos

Uma chave só vê seu próprio app, e apenas seu próprio modo: a chave de teste vê sessões de teste, cobranças, jogadores e anúncios; a chave de produção vê os de produção. Algo do outro modo é not_found (ou valid: false). Veja Teste e live.

#Erros

Erros respondem com um status 4xx e um corpo com um error código, às vezes com mais campos:

{ "error": "pool_empty", "pool": 3.5 }

Cada ponto de extremidade lista o seu próprio. Todo código está em Códigos de erro.

#Sessões

#POST/session/verify

# Set LIA_KEY on your server. Reuse Idempotency-Key only for the same request.
curl --request POST 'https://api.lialabs.org/api/apps/v1/session/verify' \
  --header "Authorization: Bearer $LIA_KEY" \
  --header 'Content-Type: application/json' \
  --header 'Idempotency-Key: example-request-1' \
  --data-raw '{
  "session": "lias_example_session"
}'

Verifica um token de sessão de Lia.init() ou Lia.session(), e lhe diz de quem é.

POST /api/apps/v1/session/verify
Authorization: Bearer lia_live_…
Content-Type: application/json

{ "session": "lias_eyJhcHAiOi…" }

Respostas 200 de qualquer forma:

{ "valid": true, "playerId": "p_3f9c0a6d1b2e4f5a6b7c", "mode": "live", "exp": 1761998400000 }

{ "valid": false }

Um token é válido quando Lia o assinou, ele'para o seu app e sua chave's modo, e não'não terminou (15 minutos após ter sido criado).

#Produtos

#GET/products

# Set LIA_KEY on your server. Reuse Idempotency-Key only for the same request.
curl --request GET 'https://api.lialabs.org/api/apps/v1/products' \
  --header "Authorization: Bearer $LIA_KEY"

O que seu app vende, nos preços em Lia's registros. Apenas produtos ativos, do mais barato ao mais caro.

{
  "products": [
    { "id": "extra-lives", "name": "3 extra lives", "price": 5, "active": true },
    { "id": "gold-pack", "name": "Gold pack", "price": 25, "active": true }
  ]
}

#Cobranças

Uma cobrança é um pagamento no Lia'sua folha de pagamento. Veja Pagamentos.

O objeto de cobrança:

#GET/charges/:id

# Set LIA_KEY on your server. Reuse Idempotency-Key only for the same request.
curl --request GET 'https://api.lialabs.org/api/apps/v1/charges/id_example' \
  --header "Authorization: Bearer $LIA_KEY"

Essa cobrança é real, paga e de quem? Sempre verifique aqui antes de entregar: nunca tome a página's ou um webhook'palavra para isso.

{
  "charge": {
    "id": "ch_9b1f4c2e7a0d5b8f3e6a1c4d",
    "playerId": "p_3f9c0a6d1b2e4f5a6b7c",
    "productId": "extra-lives",
    "amount": 5,
    "status": "paid",
    "mode": "live",
    "createdAt": 1761998400000,
    "deliveredAt": null,
    "refundedAt": null
  }
}

#POST/charges/:id/deliver

# Set LIA_KEY on your server. Reuse Idempotency-Key only for the same request.
curl --request POST 'https://api.lialabs.org/api/apps/v1/charges/id_example/deliver' \
  --header "Authorization: Bearer $LIA_KEY" \
  --header 'Idempotency-Key: example-request-1'

Marca uma cobrança entregue, uma vez que você'você deu à pessoa o que ela comprou. Seguro de repetir: entregar uma cobrança entregue não muda nada e responde da mesma forma. Nenhum corpo.

{ "charge": { "id": "ch_9b1f…", "status": "delivered", "deliveredAt": 1761998405000, "…": "…" } }

#POST/charges/:id/refund

# Set LIA_KEY on your server. Reuse Idempotency-Key only for the same request.
curl --request POST 'https://api.lialabs.org/api/apps/v1/charges/id_example/refund' \
  --header "Authorization: Bearer $LIA_KEY" \
  --header 'Idempotency-Key: example-request-1'

Devolve o $LIA para a pessoa, quando você puder'não entregar o que eles compraram. Funciona em uma cobrança paga ou entregue. Seguro repetir: reembolsar uma cobrança reembolsada responde com ela e paga nada mais. Sem corpo.

{ "charge": { "id": "ch_9b1f…", "status": "refunded", "refundedAt": 1761998410000, "…": "…" } }

O preço total volta para a pessoa's saldo, no modo ao vivo, fora de Lia'sua parte e sua parcela. Um charge.refunded o webhook é enviado.

#Recompensas

Ver Potes de recompensas.

#POST/rewards

# Set LIA_KEY on your server. Reuse Idempotency-Key only for the same request.
curl --request POST 'https://api.lialabs.org/api/apps/v1/rewards' \
  --header "Authorization: Bearer $LIA_KEY" \
  --header 'Content-Type: application/json' \
  --header 'Idempotency-Key: example-request-1' \
  --data-raw '{
  "playerId": "player_example",
  "amount": 1,
  "key": "reward-example-1",
  "reason": "Level completed"
}'

Paga um jogador do seu app'pool de recompensas, uma vez por chave.

POST /api/apps/v1/rewards
Authorization: Bearer lia_live_…
Content-Type: application/json

{
  "playerId": "p_3f9c0a6d1b2e4f5a6b7c",
  "amount": 25,
  "key": "tournament-2026-11-01:p_3f9c0a6d1b2e4f5a6b7c",
  "reason": "Weekly tournament, 1st place"
}

Pago:

{ "status": "paid", "amount": 25, "pool": 975 }

A mesma chave paga nada novamente e responde com o que a primeira paga:

{ "status": "duplicate", "amount": 25, "pool": 975 }

pool é o que's restantes em seu pool de prêmios, e o máximo que um jogador pode obter dele por dia.'para usar e o limite diário não't aplicar.

A reward.paid o webhook é enviado para cada recompensa paga (não para duplicatas).

#GET/pool

# Set LIA_KEY on your server. Reuse Idempotency-Key only for the same request.
curl --request GET 'https://api.lialabs.org/api/apps/v1/pool' \
  --header "Authorization: Bearer $LIA_KEY"

O que's restantes.

{ "balance": 975, "dailyCapPerPlayer": 50, "mode": "live" }

dailyCapPerPlayer é 0 quando lá's não tem limite diário. balance é o pool ao vivo, também quando você pede com sua chave de teste.

#Notificações

Ver Notificações.

#POST/notifications

# Set LIA_KEY on your server. Reuse Idempotency-Key only for the same request.
curl --request POST 'https://api.lialabs.org/api/apps/v1/notifications' \
  --header "Authorization: Bearer $LIA_KEY" \
  --header 'Content-Type: application/json' \
  --header 'Idempotency-Key: example-request-1' \
  --data-raw '{
  "playerId": "player_example",
  "text": "Ready for another round?",
  "startParam": "round_2"
}'

Envia uma notificação para um jogador que permitiu. Ela aparece sob o seu app's nome e abre seu app com seu startParam.

POST /api/apps/v1/notifications
Authorization: Bearer lia_live_…
Content-Type: application/json

{ "playerId": "p_3f9c0a6d1b2e4f5a6b7c", "text": "It's your move against @amara.", "startParam": "match-8k2d" }

Enviado:

{ "sent": true, "pushed": true }

pushed é false quando ele chegou a Lia's campainha mas não o telefone (a pessoa tem Lia'desativa as notificações).

#Anúncios

Ver Anúncios.

#POST/ads/verify

# Set LIA_KEY on your server. Reuse Idempotency-Key only for the same request.
curl --request POST 'https://api.lialabs.org/api/apps/v1/ads/verify' \
  --header "Authorization: Bearer $LIA_KEY" \
  --header 'Content-Type: application/json' \
  --header 'Idempotency-Key: example-request-1' \
  --data-raw '{
  "adId": "ad_example"
}'

Esse anúncio foi realmente assistido, e por quem? Verifique antes de dar algo por um vídeo recompensado.

POST /api/apps/v1/ads/verify
Authorization: Bearer lia_live_…
Content-Type: application/json

{ "adId": "ad_8e1c4b0f2a9d47c6b3e15a07" }

{ "adId": "ad_8e1c4b0f2a9d47c6b3e15a07", "playerId": "p_3f9c0a6d1b2e4f5a6b7c", "format": "rewarded", "watched": true, "watchedAt": 1761998400000 }

Pergunte com a chave do modo em que o anúncio foi exibido: um anúncio de modo de teste (sempre um dos Google'anúncios de teste, nunca contabilizados para ganhos) é not_found para a chave ao vivo.

Lia não pode'marcar um anúncio como usado quando você o verificar, para pagar cada adId uma vez que você mesmo (use ad:<adId> como a chave de recompensa).

#Lobby

Mesas públicas que qualquer um em Lia pode encontrar. Lia mantém apenas o anúncio: seu servidor executa a mesa. Veja Mesas públicas.

O objeto da tabela:

#POST/lobby/tables

# Set LIA_KEY on your server. Reuse Idempotency-Key only for the same request.
curl --request POST 'https://api.lialabs.org/api/apps/v1/lobby/tables' \
  --header "Authorization: Bearer $LIA_KEY" \
  --header 'Content-Type: application/json' \
  --header 'Idempotency-Key: example-request-1' \
  --data-raw '{
  "tableId": "table_example",
  "hostPlayerId": "player_example",
  "seats": 2,
  "taken": 1,
  "title": "A friendly game",
  "stake": 1,
  "pot": 1,
  "expiresIn": 1800
}'

Lista uma mesa que'está esperando por jogadores, ou atualiza sua lista (mantém seu lugar na lista). Liste-o novamente sempre que suas vagas mudarem.

{ "tableId": "t8k2d", "hostPlayerId": "p_3f9c0a6d1b2e4f5a6b7c", "seats": 2, "taken": 1, "title": "Quick game", "stake": 5, "expiresIn": 900 }

{ "listed": true, "tableId": "t8k2d", "seats": 2, "taken": 1, "expiresAt": 1761999300000 }

Quando taken atinge seats, a tabela é removida da lista, e a resposta é { "listed": false }.

#GET/lobby/tables

# Set LIA_KEY on your server. Reuse Idempotency-Key only for the same request.
curl --request GET 'https://api.lialabs.org/api/apps/v1/lobby/tables' \
  --header "Authorization: Bearer $LIA_KEY"

Seu app's mesas abertas na sua chave's modo, mais recentes primeiro, até 200: cada host'com blocos deixados de lado (aquele'para cada jogador'seu próprio visual).

{ "tables": [{ "id": "t8k2d", "game": "your-app", "host": { "name": "amara" }, "seats": 2, "taken": 1, "title": "Quick game", "stake": 5, "pot": 0, "createdAt": 1761998400000, "expiresAt": 1761999300000 }] }

#POST/lobby/tables/:id/sit

# Set LIA_KEY on your server. Reuse Idempotency-Key only for the same request.
curl --request POST 'https://api.lialabs.org/api/apps/v1/lobby/tables/id_example/sit' \
  --header "Authorization: Bearer $LIA_KEY" \
  --header 'Content-Type: application/json' \
  --header 'Idempotency-Key: example-request-1' \
  --data-raw '{
  "playerId": "player_example"
}'

Assenta um jogador em uma mesa listada, antes que o seu servidor o deixe entrar. Lia recusa pessoas que o anfitrião bloqueou ou que bloquearam o anfitrião. Quando a última cadeira é ocupada, a mesa sai da lista.

{ "playerId": "p_8a1e0c4d2b7f9e3a5c6d" }

{ "seated": true, "taken": 2, "seats": 2, "full": true }

#DELETE/lobby/tables/:id

# Set LIA_KEY on your server. Reuse Idempotency-Key only for the same request.
curl --request DELETE 'https://api.lialabs.org/api/apps/v1/lobby/tables/id_example' \
  --header "Authorization: Bearer $LIA_KEY" \
  --header 'Idempotency-Key: example-request-1'

Tira uma tabela da lista, quando seu jogo começa ou se fecha. Seguro repetir.

{ "removed": true }

removed é false quando ele não'está listado.

#Re tentando

Enviar um Idempotency-Key cabeçalho com cada POST, e o mesmo novamente em cada tentativa de repetição dessa solicitação. Uma tentativa de repetição então nunca faz nada duas vezes, e responde como a primeira solicitação fez.

POST /api/apps/v1/notifications
Authorization: Bearer lia_live_…
Content-Type: application/json
Idempotency-Key: 6f1c2a9e-0b7d-4c35-9e1a-2d8f4b7c3a10

{ "playerId": "p_3f9c0a6d1b2e4f5a6b7c", "text": "It's your move." }

• Qualquer chave que você quiser, 1 para 128 de letras, dígitos, _, -, . e :. Um UUID por operação é certo.
• A primeira solicitação é executada. Se for bem-sucedido (2xx), sua resposta é mantida por 24 horas, e uma nova tentativa com a mesma chave e o mesmo corpo obtém novamente essa resposta, com o cabeçalho Idempotent-Replayed: true.
• Uma recusa não mantém nada (4xx ou 5xx), então você pode corrigir a causa e tentar novamente com a mesma chave.
• A mesma chave com um corpo diferente é 422 idempotency_key_reused.
• A mesma chave enquanto a primeira ainda está em execução é 409 idempotency_key_in_use com Retry-After: 1. Tente novamente, e você recebe o primeiro's resposta.
• Chaves são seu app's próprio, e testes e produção mantêm os seus separados. A mesma chave em outro ponto final é outra chave.

Sem o cabeçalho, a maioria dos endpoints ainda é segura para repetir: leituras não mudam nada, entregar e reembolsar são seguros para repetir, e recompensas são pagas uma vez por key. Notificações são a exceção: sem o cabeçalho, um retry envia a notificação novamente.

Traduzido automaticamente. O inglês é a fonte de verdade. Leia em inglês