API e credenciais

Separar permissões#

Licenças, permissões e tokens de upload têm funções diferentes. Tokens expiram e servem apenas para provas, não para gerenciar o painel.

Tratar erros#

Evite repetições rápidas em falhas ou limites. Não repita automaticamente escritas financeiras incertas. Não publique cabeçalhos de autenticação em URLs, cliente ou registros.

Associar endpoint e permissão#

Não há chave universal. A licença autentica a ponte SaaS; tokens de componentes podem exigir escopos. Ações no navegador precisam de papel, direitos e CSRF quando aplicável. Tokens de evidência são limitados ao contexto, servidor e pedido, sem administração.

O exemplo mostra só cabeçalhos. O marcador não é válido; o recurso cria o protocolo. JSON arbitrário não vira tarefa. Guarde autorização entre servidores, fora de navegador, URL, analytics e erros compartilhados.

Authorization: Bearer YOUR_SERVER_LICENSE
Content-Type: application/json

• Gerenciar licença

Separar resposta HTTP e tarefa#

A ponte aceita POST JSON, não SQL livre ou nome de tabela. pending/claimed ainda está em andamento. Confira resultado final antes de declarar sucesso.

• 401: licença do servidor correto e não regenerada.
• 403 bridge_disabled / subscription_inactive / permission_denied: confira o cartão Tosun Connect do servidor (bridge_disabled indica que a conexão foi desligada ali), assinatura e direitos; repetir não concede acesso.
• 405 / 415: corrija método e JSON Content-Type; não repita JSON inválido sem parar.
• 429: respeite Retry-After e espere; a ponte limita concorrência e aumenta atraso em falhas.
• 503 / timeout: registre horário e referência sem segredos, investigue conexão.

• Ponte e erros

Testar uma operação pequena#

Use servidor de teste ou personagem controlado. Leia uma vez e compare personagem/dados com o jogo. Operações fixas e páginas não são dump completo. Guarde referência para distinguir tarefa e repetição.

Registre só estado, duração e referência não secreta. Remova tokens e dados pessoais de relatórios públicos. Reteste ao mudar chaves, direitos ou pacote.

Não distribua o mesmo token administrativo a tudo. Use escopos mínimos e revogue credenciais sem uso. Após mudar endpoint ou direitos reteste sucesso e rejeição, sem confiar em resultado antigo.

1. Verifique sucesso próprio e rejeição de chaves erradas/revogadas.
2. Equipe sem direito deve ser rejeitada; não teste clientes alheios.
3. Exiba pending, failed, expired e done separadamente, sem sucesso genérico.
4. Em unknown_outcome financeiro confira saldo vivo e auditoria antes de escrever de novo.

• Pedidos limitados
• Frameworks

Separar navegador e protocolo do servidor#

/api/tenant_db_bridge.php autentica a equipe pela sessão. Exige POST, application/json, _csrf válido e conta do tenant atual; limita o corpo a 4096 bytes. action pode ser enqueue ou result. Licença não cria sessão. Permissão de leitura não concede escrita de dinheiro; a operação é autorizada separadamente.

/api/server_db_bridge.php troca saúde, trabalhos e resultados do servidor de jogo. Usa POST JSON e licença Bearer, com limite de 65536 bytes. Cookies e CSRF não substituem esse protocolo. Identifique a rota antes de alterar credenciais; valores de outra rota não corrigem acesso. Não imite o protocolo integrado com JSON arbitrário.

Distinguir aceitação de conclusão#

ok=true pode confirmar HTTP aceito sem provar conclusão no jogo. Acompanhe id, operation e status dentro de request. pending aguarda; claimed foi recebido pelo servidor. done concluiu, failed falhou e expired expirou. Mantenha contexto de server_id e request_id na consulta.

Verifique estado final e error antes de mostrar sucesso. Pedido pendente equivalente pode reutilizar o trabalho existente; isso não garante repetição ilimitada permanente. Pare escritas de dinheiro em unknown_outcome. Timeout ou resultado inválido não provam ausência de alteração. Compare saldo ao vivo, alvo anterior e auditoria; não apague evidências para tentar novamente.

Preparar relato técnico pequeno e limpo#

Para 405 verifique método; para 415, JSON Content-Type; para 400, JSON válido e campos permitidos. No navegador, 401 envolve sessão e 419 validação CSRF; reabra pela navegação normal. Para 404 confira contexto sem testar outro cliente. Espere trabalhos ativos em 429.

Para 503 ou rede incerta, anote hora, endpoint, estado HTTP, operação e referência não secreta. O exemplo é nota de suporte, não corpo de solicitação. Exclua cookies, Authorization, _csrf, licenças e dados de jogadores. Corrija a etapa responsável em vez de repetir rapidamente; valide primeiro com uma leitura controlada.

Endpoint: /api/tenant_db_bridge.php
Method: POST
HTTP status: 419
Error: csrf_failed
Operation: players.list
Reference: YOUR_REQUEST_REFERENCE
Time: YOUR_ERROR_TIME

Leia uma página de jogadores com dois corpos JSON verificados#

Este exemplo lê a primeira página de jogadores num navegador que já tem sessão iniciada no painel da sua conta. O servidor 123 e o ID da solicitação são fictícios: use o seu servidor e request.id da resposta de enqueue. Substitua CURRENT_PAGE_CSRF pelo valor válido da página atual. Não é uma licença do servidor e não deve ser copiado para uma nota de suporte. É necessário um POST para a mesma origem, application/json e a sessão do navegador. A leitura exige servers.manage ou players.view; enqueue é recusado na demonstração de somente leitura.

O primeiro corpo envia apenas um cursor vazio; esta operação devolve no máximo 25 registros por página. Não acrescente limit, SQL, nome de tabela, string de conexão nem parâmetros de dinheiro. Se a resposta inicial indicar pending, consulte esse trabalho com o segundo corpo em vez de criar outro. Ao receber done, leia request.result.items. Se request.result.has_more for true, use request.result.next_cursor na próxima solicitação deliberada de página. Interprete uma lista vazia juntamente com o estado de conclusão bem-sucedida. Estes modelos não contêm credenciais utilizáveis. Limite o primeiro teste a uma leitura no seu próprio servidor de testes; não use o exemplo para conceder acesso administrativo a extensões públicas do navegador.

POST /api/tenant_db_bridge.php
Content-Type: application/json

Enqueue:
{
  "_csrf": "CURRENT_PAGE_CSRF",
  "server_id": 123,
  "action": "enqueue",
  "operation": "players.list",
  "params": {"cursor": ""}
}

Result (use request.id from the enqueue response):
{
  "_csrf": "CURRENT_PAGE_CSRF",
  "server_id": 123,
  "action": "result",
  "request_id": "00112233445566778899aabbccddeeff"
}

• Ponte MySQL
• Acesso ao painel e à conta

Separe o timeout HTTP do prazo do trabalho#

Imagine que enqueue foi aceito às 14:03:10 e request.id ficou guardado, mas uma chamada posterior de result perdeu a conexão. Uma solicitação HTTP do painel pode parar após 12 segundos; o trabalho na fila expira 120 segundos depois da criação. Interromper a solicitação no navegador não cancela o trabalho no servidor. Não apresente “sem resposta” como resultado expired ou failed. Preserve o ID conhecido e consulte result com o mesmo server_id quando a conexão voltar. O painel normalmente verifica resultados pendentes a cada três segundos; não acrescente um ciclo de consultas contínuas.

Se a leitura players.list acabar em expired com request_expired, registre o erro, corrija a conexão e depois inicie uma nova leitura deliberada. Em player.money.set, expirar depois de claimed ou receber um resultado inválido pode gerar unknown_outcome: isso não comprova que o saldo permaneceu igual. Suspenda novas escritas e confira o saldo atual e a operação existente. Os resultados não são um arquivo ilimitado; registros expirados são removidos posteriormente por uma limpeza limitada. Se o registro já não existir, não tente descobrir o resultado enviando outra alteração monetária. Para o suporte, guarde apenas uma referência não secreta, hora, operation e último estado conhecido.

Illustrative observations; not an API request body:
14:03:10  enqueue accepted; save request.id
14:03:22  HTTP timeout; job outcome is not established
Later     result with the same server_id + request_id

Read:  expired + request_expired -> investigate before a new read
Write: expired + unknown_outcome -> stop writes and reconcile

• Ponte MySQL
• Desempenho e intervalos de espera