{ } API

Coin API — Referência completaCoin API — Complete Reference

Todos os endpoints, formatos de requisição/resposta e comportamentos derivados de api.js e logic.js.All endpoints, request/response shapes and behavior derived from api.js and logic.js.

Base URL: https://bank.foxsrv.netContent-Type: application/json

1Visão geralOverview

Esta documentação espelha exatamente o comportamento implementado nos arquivos do servidor (api.js e logic.js).

This documentation mirrors the exact behavior implemented in the server files (api.js and logic.js).

Arquitetura: a API HTTP enfileira as operações em uma fila limitada em memória (com persistência opcional no banco para jobs pendentes) e então aguarda o resultado do worker ou devolve uma resposta no formato legado, para compatibilidade. A fila anexa um txId aos payloads para idempotência; se esse txId aparece na resposta HTTP depende das regras de mapeamento por rota implementadas em doEnqueueAndMap.

Key architecture: the HTTP API enqueues write operations into a bounded in-memory queue (with optional DB persistence for pending jobs) and then either waits for the queue worker result or returns a legacy-shaped response for backward compatibility. The queue attaches a txId to payloads for idempotency; whether that txId appears in the HTTP response depends on per-route mapping rules implemented in doEnqueueAndMap.

Valores: as Coins usam 8 casas decimais (1 coin = 100.000.000 sats). Os endpoints de cartão truncam o valor para 8 casas (Math.floor(amount * 1e8) / 1e8).

Amounts: Coins use 8 decimal places (1 coin = 100,000,000 sats). Card endpoints truncate the amount to 8 decimals (Math.floor(amount * 1e8) / 1e8).

2AutenticaçãoAuthentication

Endpoints que exigem autenticação usam o cabeçalho Authorization com o token de sessão:

Endpoints that require authentication use an Authorization header with a session token:

Authorization: Bearer <sessionId>
Content-Type: application/json

O middleware resolve a sessão com db.getSession e define req.userId. Se a sessão for inválida, a rota responde 403 com { error: "operation failed" }. O sessionId é obtido em POST /api/login ou POST /api/register.

The middleware resolves the session using db.getSession and sets req.userId. If the session is invalid the route returns 403 with { error: "operation failed" }. The sessionId comes from POST /api/login or POST /api/register.

O site oficial guarda o token no localStorage (session) e nos cookies coin_sid/coin_uid. Uma futura versão do servidor pode ler esse cookie diretamente (ex.: como alternativa ao cabeçalho), sem mudança no front-end.The official website stores the token in localStorage (session) and in the coin_sid/coin_uid cookies. A future server version can read that cookie directly (e.g. as an alternative to the header) with no front-end change.

3Fila e idempotênciaQueue & idempotency

O servidor usa queue.enqueueAndWait(payload). Antes de enfileirar, doEnqueueAndMap garante payload.args.ip e anexa payload.txId = UUID aleatório se não informado.
Se a fila recusar com ENQUEUE_REJECTED, o wrapper tenta um cache em memória e um job pendente no banco. Se isso também falhar, a API responde 429 / { error: "QUEUE_FULL" }. O worker de cache depois despeja os itens pendentes na fila.
Rotas que passam por doEnqueueAndMap também aplicam limite por IP (token bucket: RATE_LIMIT_PER_IP/s, rajada RATE_LIMIT_BURST, padrão 10) → 429 RATE_LIMIT_EXCEEDED.
Mapeamento legado por rota:
- legacyReturn: 'transfer' → resposta sempre { success: true } (oculta o txId).
- legacyReturn: 'transfer_card' → { success: true, txId?, date? } se o resultado do worker tiver txId; caso contrário { success: true }.
- Padrão (sem legacyReturn) → devolve o resultado do worker como está.

The server uses queue.enqueueAndWait(payload). Before enqueueing, doEnqueueAndMap ensures payload.args.ip is set and attaches payload.txId = a random UUID if not provided.
If the queue refuses with ENQUEUE_REJECTED the wrapper attempts an in-memory cache and a DB pending job. If that also fails, the API returns 429 / { error: "QUEUE_FULL" }. The cache worker later flushes pending items into the queue.
Routes going through doEnqueueAndMap also apply a per-IP rate limit (token bucket: RATE_LIMIT_PER_IP/s, burst RATE_LIMIT_BURST, default 10) → 429 RATE_LIMIT_EXCEEDED.
Per-route legacy mapping:
- legacyReturn: 'transfer' → response is always { success: true } (hides txId).
- legacyReturn: 'transfer_card' → response is { success: true, txId?, date? } if the worker result contains a txId, otherwise { success: true }.
- Default (no legacyReturn) → returns the worker result as-is.

4Endpoints (lista completa)Endpoints (complete list)

Conta e sessãoAccount & session

POST/api/loginPúblicoPublic

Autentica um usuário e cria uma sessão. O servidor aplica SHA-256 na senha antes de verificar.

Authenticates a user and creates a session. The server hashes the password using SHA-256 before checking.

Corpo:

Body:

{
  "username": "alice",
  "password": "secret"
}

Resposta (sucesso):

Response (success):

{
  "sessionCreated": true,
  "passwordCorrect": true,
  "userId": "123456789012345678",
  "sessionId": "<session-token>",
  "saldo": 12.345678,
  "cooldownRemainingMs": 0
}

Se o IP estiver bloqueado por excesso de tentativas, responde 429 com error: "IP blocked. Try again in X seconds.". Credenciais erradas: sessionCreated: false, passwordCorrect: false. Campos ausentes: 400.

If IP is locked due to too many failed attempts, returns 429 with error: "IP blocked. Try again in X seconds.". Wrong credentials: sessionCreated: false, passwordCorrect: false. Missing fields: 400.

POST/api/registerPúblicoPublic

Cria um novo usuário e já devolve uma sessão. Aplica cooldown de cadastro por IP (bloqueio de 24h no código, atualmente configurado para 1 s).

Creates a new user and returns a session. Enforces an IP registration cooldown (24h block in code, currently set to 1s).

Corpo:

Body:

{
  "username": "bob",
  "password": "s3cret"
}

Resposta:

Response:

{
  "success": true,
  "userId": "987654321",
  "sessionId": "<session-token>"
}

Erros: 409 se o usuário já existir, 429 se o IP estiver bloqueado (Block: …) ou a fila cheia, 400 se faltar usuário/senha.

Errors: 409 if username already taken, 429 if IP blocked (Block: …) or queue full, 400 if username/password missing.

POST/api/logoutBearer tokenBearer token

Exclui o token de sessão informado no cabeçalho Authorization.

Deletes the session token provided in the Authorization header.

Resposta:

Response:

{ "success": true }

POST/api/account/changeBearer tokenBearer token

Altera a senha e, opcionalmente, o nome de usuário do usuário autenticado. password é obrigatório; username é opcional. A sessão atual é encerrada após a alteração.

Changes the password and, optionally, the username of the authenticated user. password is required; username is optional. The current session is deleted after the change.

Corpo:

Body:

{
  "username": "newalice",
  "password": "newpass"
}

Resposta:

Response:

{ "success": true }

POST/api/account/unregisterBearer tokenBearer token

Exclui a conta do usuário (limpa usuário/senha e remove a sessão).

Deletes the user account (clears username/password and removes the session).

Resposta:

Response:

{ "success": true }

POST/api/account/updateBearer tokenBearer token

Atualiza o nome de usuário e o hash da senha do usuário.

Updates the username and password hash for the user.

Corpo:

Body:

{
  "username": "alice",
  "passwordHash": "sha256 hash"
}

Resposta:

Response:

{ "success": true }

TransferênciasTransfers

POST/api/transferBearer tokenBearer token

Transfere coins do usuário autenticado para outro usuário. Usa resposta legada (oculta o txId).

Transfers coins from the authenticated user to another user. This endpoint uses legacy response (hides txId).

Corpo:

Body:

{
  "toId": "987654321",
  "amount": 0.001
}

Resposta:

Response:

{ "success": true }

Nota: se precisar do txId, envie seu próprio txId no corpo ou use o endpoint por cartão. O site oficial localiza a transação em GET /api/transactions?page=1 logo após o envio para gerar o comprovante. Falha: 400 { error: "operation failed" }.

Note: if you need the txId, either supply your own txId in the body or use the card-based endpoint. The official website finds the transaction in GET /api/transactions?page=1 right after sending to build the receipt. Failure: 400 { error: "operation failed" }.

POST/api/transfer/cardPúblicoPublic

Transfere coins usando um código de cartão. O dono é resolvido pelo hash do cartão. Pode devolver txId.

Transfers coins using a card code. Resolves the owner from the card hash. May return txId if available.

Corpo:

Body:

{
  "cardCode": "abcd-efgh-1234",
  "toId": "11111",
  "amount": 0.01
}

Resposta (com txId):

Response (if txId available):

{
  "success": true,
  "txId": "uuid-12345-abcdef",
  "date": "2025-12-07T12:00:00.000Z"
}

Resposta legada: { success: true }. Cartão não encontrado: 404 { success: false }; saldo insuficiente: 402.

Legacy fallback: { success: true }. Card not found: 404 { success: false }; insufficient funds: 402.

POST/api/card/payPúblicoPublic

Transferência cartão-para-cartão (alias de transfer_between_cards). Usado pelo site na opção "Transferir → Cartão Coin".

Card-to-card transfer (alias of transfer_between_cards). Used by the website in "Transfer → Coin card".

Corpo:

Body:

{
  "fromCard": "abcd-ef",
  "toCard": "wxyz-12",
  "amount": 0.002
}

Resposta:

Response:

{ "success": true, "txId": "…", "date": "…" }

Mesma forma de /api/transfer/card. Erros: 404 FROM_CARD_NOT_FOUND / TO_CARD_NOT_FOUND, 402 INSUFFICIENT_FUNDS.

Same as /api/transfer/card. Errors: 404 FROM_CARD_NOT_FOUND / TO_CARD_NOT_FOUND, 402 INSUFFICIENT_FUNDS.

Recompensa (claim)Claim

POST/api/claimBearer tokenBearer token

Resgata a recompensa diária (ou configurada). Respeita o cooldown definido em claimConfig.

Claims the daily (or configured) reward. Respects cooldown set in claimConfig.

Resposta (sucesso):

Response (success):

{
  "success": true,
  "claimed": 0.05
}

Resposta (cooldown):

Response (cooldown):

{
  "error": "Cooldown active",
  "nextClaimInMs": 12345,
  "cooldownMs": 86400000,
  "lastClaimTs": 1234567890
}

Dependendo de como logic.claimCoins sinaliza o cooldown, a resposta pode chegar como 500 { error: "Internal error" }; clientes devem consultar GET /api/claim/status após uma falha (o site oficial faz isso).

Depending on how logic.claimCoins signals the cooldown, the response may arrive as 500 { error: "Internal error" }; clients should query GET /api/claim/status after a failure (the official website does).

GET/api/claim/statusBearer tokenBearer token

Retorna o cooldown restante do usuário autenticado.

Returns the remaining cooldown for the authenticated user.

Resposta:

Response:

{
  "cooldownRemainingMs": 12345,
  "lastClaimTimestamp": 1234567890,
  "cooldownMs": 86400000
}

CartõesCards

POST/api/cardBearer tokenBearer token

Obtém o código do cartão do usuário autenticado.

Retrieves the card code of the authenticated user.

Resposta:

Response:

{
  "cardCode": "abc123..."
}

Sem cartão: 404 { error: "Card not found" }.

No card: 404 { error: "Card not found" }.

POST/api/card/resetBearer tokenBearer token

Gera um novo código de cartão (invalida o anterior).

Generates a new card code for the user (invalidates the old one).

Resposta:

Response:

{
  "newCode": "def456..."
}

POST/api/card/infoPúblicoPublic

Informações da conta pelo código do cartão (sem autenticação).

Get account information by card code (no authentication required).

Corpo:

Body:

{
  "cardCode": "abcdef"
}

Resposta:

Response:

{
  "success": true,
  "userId": "123",
  "coins": "0.00012345",
  "sats": 12345,
  "totalTransactions": 5,
  "lastClaimTs": 1234567890,
  "cooldownRemainingMs": 0,
  "cooldownMs": 86400000
}

Não encontrado: 404 { success: false, error: "Card not found" }.

Not found: 404 { success: false, error: "Card not found" }.

POST/api/card/claimPúblicoPublic

Resgata a recompensa usando o código do cartão (sem autenticação).

Claims reward using a card code (no auth).

Corpo:

Body:

{ "cardCode": "abcdef" }

Resposta:

Response:

{
  "success": true,
  "claimed": 0.05
}

Em cooldown: 429 com error: "COOLDOWN_ACTIVE" e nextClaimInMs. Cartão inexistente: 404 CARD_NOT_FOUND.

On cooldown: 429 with error: "COOLDOWN_ACTIVE" and nextClaimInMs. Unknown card: 404 CARD_NOT_FOUND.

BackupsBackups

POST/api/backup/createBearer tokenBearer token

Gera códigos de backup para o usuário autenticado. Até 12 códigos são criados se o usuário tiver saldo positivo.

Generates backup codes for the authenticated user. Up to 12 codes will be created if the user has a positive balance.

Resposta:

Response:

{ "success": true }

POST/api/backup/listBearer tokenBearer token

Lista os códigos de backup do usuário autenticado.

Lists the backup codes for the authenticated user.

Resposta:

Response:

{
  "backups": ["code1", "code2"]
}

POST/api/backup/restoreBearer tokenBearer token

Consome um código de backup e transfere todo o saldo do dono original para o usuário autenticado. Não é possível restaurar o próprio backup.

Consumes a backup code and transfers the entire balance of the original owner to the authenticated user. Cannot restore your own backup.

Corpo:

Body:

{ "backupId": "code" }

Resposta:

Response:

{ "success": true }

Informações e rankingInfo & rank

GET/api/totalusersPúblicoPublic

Retorna o total de usuários registrados.

Returns the total number of registered users.

Resposta:

Response:

{
  "totalUsers": 42
}

GET/api/tx/:txidPúblicoPublic

Consulta uma transação pelo ID. Retorna detalhes com valores em sats e em coins. É a fonte de dados da página pública de comprovante.

Looks up a transaction by its ID. Returns detailed information including amounts in satoshis and coins. This is the data source of the public receipt page.

Resposta (encontrada):

Response (found):

{
  "success": true,
  "tx": {
    "id": "uuid-12345",
    "date": "2025-12-07T12:00:00.000Z",
    "from": "11111",
    "to": "22222",
    "amountSats": 12345,
    "amountCoins": "0.00012345"
  }
}

Não encontrada: 404 com { error: "INVALID_TRANSACTION", message: "Transaction not found" }.

Not found: 404 with { error: "INVALID_TRANSACTION", message: "Transaction not found" }.

GET/api/transactionsBearer tokenBearer token

Lista as transações do usuário autenticado com paginação (parâmetro page). O site percorre as páginas até receber uma lista vazia para montar o extrato e o gráfico.

Lists transactions for the authenticated user with pagination (page parameter). The website walks pages until it receives an empty list to build the statement and the chart.

Query:

?page=1

Resposta:

Response:

{
  "transactions": [
    {
      "id": "tx-1",
      "date": "2025-12-07T12:00:00.000Z",
      "from_id": "11111",
      "to_id": "22222",
      "amount": "0.001"
    }
  ],
  "page": 1
}

GET/api/user/:userId/balanceBearer tokenBearer token

Retorna o saldo do usuário autenticado (o :userId da URL é ignorado; vale o da sessão).

Returns the balance of the authenticated user (the :userId in the URL is ignored; the session user is used).

Resposta:

Response:

{
  "coins": 12.345678
}

GET/api/rankBearer tokenBearer token

Retorna os 25 maiores saldos e o total de coins em circulação.

Returns the top 25 users by balance and the total coins in circulation.

Resposta:

Response:

{
  "totalCoins": 1234.56,
  "rankings": [
    { "id": "111", "username": "alice", "coins": 100.5 }
  ]
}

Cobranças (bills)Bills

POST/api/bill/createBearer tokenBearer token

Cria uma cobrança de fromId (quem paga) para toId (quem recebe). A cobrança expira após a duração informada.

Creates a bill (invoice) from fromId (payer) to a recipient toId. The bill expires after the given duration.

Corpo:

Body:

{
  "fromId": "payer_id",
  "toId": "recipient_id",
  "amount": 0.5,
  "time": "1d"
}

Resposta:

Response:

{
  "success": true,
  "billId": "bill-abc123"
}

time é opcional. O site envia fromId = devedor e toId = o próprio usuário. Parâmetros inválidos: 400.

time is optional. The website sends fromId = debtor and toId = the current user. Invalid parameters: 400.

POST/api/bill/payBearer tokenBearer token

Paga uma cobrança usando o saldo do usuário autenticado.

Pays a bill using the authenticated user's balance.

Corpo:

Body:

{ "billId": "bill-abc123" }

Resposta:

Response:

{ "success": true }

Falha: 400 { error: "operation failed" }.

Failure: 400 { error: "operation failed" }.

POST/api/bill/listBearer tokenBearer token

Lista cobranças a pagar e a receber do usuário autenticado.

Lists bills to pay (incoming) and bills to receive (outgoing) for the authenticated user.

Corpo:

Body:

{ "page": 1 }

Resposta:

Response:

{
  "toPay": [
    { "id": "b1", "from_id": "111", "to_id": "222", "amount": "0.1", "date": "..." }
  ],
  "toReceive": [
    { "id": "b2", "from_id": "333", "to_id": "222", "amount": "0.2", "date": "..." }
  ],
  "page": 1
}

POST/api/bill/list/fromBearer tokenBearer token

Lista as cobranças que o usuário autenticado deve pagar.

Lists bills that the authenticated user must pay (incoming).

Corpo:

Body:

{ "page": 1 }

Resposta:

Response:

{ "toPay": [...], "page": 1 }

POST/api/bill/list/toBearer tokenBearer token

Lista as cobranças que o usuário autenticado vai receber.

Lists bills that the authenticated user will receive (outgoing).

Corpo:

Body:

{ "page": 1 }

Resposta:

Response:

{ "toReceive": [...], "page": 1 }

POST/api/bill/create/cardPúblicoPublic

Cria uma cobrança usando códigos de cartão (os donos são resolvidos pelos cartões). Pelo menos fromCard ou toCard deve ser informado.

Creates a bill using card codes (resolves owner IDs from the cards). At least one of fromCard or toCard must be provided.

Corpo:

Body:

{
  "fromCard": "abcd-ef",
  "toCard": "wxyz-12",
  "amount": 0.5,
  "time": "1d"
}

Resposta:

Response:

{ "success": true, "billId": "..." }

POST/api/bill/pay/cardPúblicoPublic

Paga uma cobrança usando um código de cartão (o pagador é resolvido pelo cartão).

Pays a bill using a card code (the payer is resolved from the card).

Corpo:

Body:

{
  "cardCode": "abcd-ef",
  "billId": "bill-123"
}

Resposta:

Response:

{ "success": true }

Internos e saúdeInternal & health

GET/healthPúblicoPublic

Verificação de saúde do servidor. O site usa para o indicador de status e latência da API.

Server health check. The website uses it for the API status and latency indicator.

Resposta:

Response:

{ "ok": true, "uptime": 12345.67 }

GET/api/queue/infoPúblicoPublic

Estatísticas da fila (somente se EXPOSE_INTERNALS=true).

Returns queue statistics (only available if EXPOSE_INTERNALS=true).

Resposta:

Response:

{
  "queued": 3,
  "usedBytes": 1234,
  "maxBytes": 524288,
  "maxOpsPerSecond": 500
}

GET/api/queue/status/:idPúblicoPublic

Status de um item específico da fila (se exposto).

Returns the status of a specific queue item (if exposed).

Resposta:

Response:

{ "state": "done", "ts": 1234567890, "result": {...} }

5Páginas do siteWebsite pages

RotaRoute	ArquivoFile	DescriçãoDescription
`/`	`site/index.html`	Banco digital (login, cadastro, início, extrato, transferir, cartão, cobranças, recompensas, rede, conta). Rotas internas por hash: `#/home`, `#/history`, `#/transfer?to=ID&amount=1`, `#/card`, `#/bills`, `#/claim`, `#/network`, `#/account`.Digital bank (sign-in, sign-up, home, statement, transfer, card, bills, rewards, network, account). Internal hash routes: `#/home`, `#/history`, `#/transfer?to=ID&amount=1`, `#/card`, `#/bills`, `#/claim`, `#/network`, `#/account`.
`/tx.html?id=<txid>`	`site/tx.html`	Página pública do comprovante (estilo gateway), com QR code, download em PNG/PDF e botão para voltar ao site. Também aceita `/tx/<txid>` quando a rota abaixo estiver ativa.Public receipt page (gateway style) with QR code, PNG/PDF download and a back-to-site button. Also accepts `/tx/<txid>` once the route below is active.
`/terms/`	`site/terms/terms.html`	Termos de UsoTerms of Use
`/terms/privacy.html`	`site/terms/privacy.html`	Política de PrivacidadePrivacy Policy
`/terms/documentation.html`	`site/terms/documentation.html`	Esta documentaçãoThis documentation
`/favicon.ico`, `/coin-icon.png`, `/coin-bank-embed.png`	`site/`	Ícones e imagem de embed (Open Graph)Icons and embed image (Open Graph)

Rota opcional para URLs curtas de comprovante (adicione em api.js, antes do express.static). Depois, no index.html, troque CONFIG.TX_URL para /tx/${id}:

Optional route for short receipt URLs (add to api.js, before express.static). Then, in index.html, switch CONFIG.TX_URL to /tx/${id}:

app.get('/tx/:txid', (req, res) => res.sendFile(path.join(SITE_DIR, 'tx.html')));

6Novos endpoints públicos (planejados)New public endpoints (planned)

Estes endpoints ainda serão implementados no backend. O site já está pronto para eles: a aba Rede testa cada um e mostra Em breve enquanto respondem 404; assim que passarem a responder 200 com os formatos abaixo, os dados aparecem automaticamente, sem alterar o front-end. Todos são públicos (sem autenticação) e devem devolver valores em coins como string com 8 casas.

These endpoints will be implemented in the backend. The website is already prepared: the Network tab probes each one and shows Soon while they answer 404; once they return 200 with the shapes below, data appears automatically with no front-end change. All are public (no auth) and should return coin amounts as strings with 8 decimals.

GET/api/statsPúblicoPublicPlanejadoPlanned

Retrato público do sistema. Alimenta os indicadores da aba Rede.

Public system snapshot. Feeds the Network tab KPIs.

Resposta esperada:

Expected response:

{
  "totalUsers": 1283,
  "newUsers24h": 9,
  "totalCoins": "98213.12345678",
  "totalTransactions": 48211,
  "transactions24h": 312,
  "volume24h": "1543.20000000",
  "activeUsers24h": 88,
  "totalCards": 1190,
  "openBills": 14,
  "serverTime": "2026-10-12T20:00:00.000Z"
}

GET/api/stats/history?days=30PúblicoPublicPlanejadoPlanned

Série diária para o gráfico de atividade da rede (máx. sugerido: 365 dias).

Daily series for the network activity chart (suggested max: 365 days).

Resposta esperada:

Expected response:

{
  "days": [
    { "date": "2026-10-11", "transactions": 340, "volume": "1622.50000000", "newUsers": 7 },
    { "date": "2026-10-12", "transactions": 312, "volume": "1543.20000000", "newUsers": 9 }
  ]
}

GET/api/stats/recent?limit=10PúblicoPublicPlanejadoPlanned

Últimas transações públicas da rede (feed estilo exchange). Recomenda-se limitar a 50.

Latest public network transactions (exchange-style feed). Recommended cap: 50.

Resposta esperada:

Expected response:

{
  "transactions": [
    { "id": "uuid", "date": "2026-10-12T19:59:01.000Z", "from": "111…", "to": "222…", "amountSats": 150000000 }
  ]
}

GET/tx/:txidPúblicoPublicPlanejadoPlanned

Página do comprovante com URL curta (serve site/tx.html). Ver seção 5.

Short-URL receipt page (serves site/tx.html). See section 5.

Sugestão: cache de 30–60 s no servidor para /api/stats* (são consultados por todos os visitantes) e cabeçalho Cache-Control: public, max-age=30.Tip: cache /api/stats* for 30–60 s on the server (they are queried by every visitor) and send Cache-Control: public, max-age=30.

7txId: geração e quando aparece nas respostastxId: generation & when responses include it

Todo payload enfileirado recebe um payload.txId (UUID) para idempotência; o servidor só define se o cliente não enviar um.
Se a resposta HTTP inclui o txId depende do mapeamento da rota:
- legacyReturn: 'transfer' → sempre { success: true } (txId oculto).
- legacyReturn: 'transfer_card' → { success: true, txId?, date? } se o resultado tiver txId; senão { success: true }.
- Padrão → resultado do worker como está, que pode incluir txId se a função de lógica o retornar.
Para sempre receber o txId, envie-o no corpo da requisição ou altere o mapeamento em doEnqueueAndMap.
Com o txId, o comprovante público fica em /tx.html?id=<txId>.

Every enqueued payload receives a payload.txId (UUID) for idempotency; the server only sets it if the client didn't provide one.
Whether the HTTP response includes the txId depends on the route mapping:
- legacyReturn: 'transfer' → response is always { success: true } (txId hidden).
- legacyReturn: 'transfer_card' → response is { success: true, txId?, date? } if the worker result contains a txId; otherwise { success: true }.
- Default (no legacyReturn) → returns the worker result as-is, which may include txId if the underlying logic function returns it.
To always receive the txId, provide it yourself in the request body or modify doEnqueueAndMap mapping.
With the txId, the public receipt lives at /tx.html?id=<txId>.

8Erros e códigos de statusErrors & status codes

Status	SignificadoMeaning	Corpo típicoTypical body
400	Parâmetros inválidosInvalid parameters	`{ error: "Invalid parameters" }`
402	Saldo insuficiente (rotas de cartão)Insufficient funds (card routes)	`{ success: false, error: "INSUFFICIENT_FUNDS" }`
403	Falha de autenticação / sessão inválidaAuthentication failure / invalid session	`{ error: "operation failed" }`
404	Recurso não encontrado (cartão, transação)Resource not found (card, transaction)	`{ error: "INVALID_TRANSACTION" }`
409	Conflito (usuário já existe)Conflict (username already taken)	`{ success: false, error: "Username already taken" }`
429	Limite excedido, fila cheia, IP bloqueado ou cooldownRate limit exceeded, queue full, IP locked or cooldown	`{ error: "QUEUE_FULL" }` · `{ error: "RATE_LIMIT_EXCEEDED" }`
500	Erro internoInternal server error	`{ error: "Internal error" }`
504	Tempo de espera da fila esgotadoQueue wait timeout	`{ error: "QUEUE_TIMEOUT" }`

9Apêndice — nomes das operaçõesAppendix — op names

login, register, logout, account_change, account_unregister, account_update,
transfer, transfer_card, claim, claim_status, get_card, reset_card,
backup_create, backup_list, backup_restore,
get_balance, rank, total_users, tx_lookup, transactions,
bill_list, bill_list_from, bill_list_to, bill_create, bill_pay,
card_info, card_claim, transfer_between_cards,
bill_create_card, bill_pay_card

Nota para desenvolvedores: para mudar se uma rota devolve txId, edite o mapeamento de doEnqueueAndMap em api.js. Você também pode enviar seu próprio txId para manter a idempotência e correlacionar com /api/tx/:txid.

Developer note: to change whether a route returns txId, edit doEnqueueAndMap mapping in api.js. You can also supply your own txId in the request to maintain idempotency and correlate with /api/tx/:txid.

10Exemplo rápidoQuick example

# 1) login
curl -s -X POST https://bank.foxsrv.net/api/login \
  -H "Content-Type: application/json" \
  -d '{"username":"alice","password":"secret"}'

# 2) balance (use the sessionId from step 1)
curl -s https://bank.foxsrv.net/api/user/me/balance \
  -H "Authorization: Bearer <sessionId>"

# 3) transfer
curl -s -X POST https://bank.foxsrv.net/api/transfer \
  -H "Authorization: Bearer <sessionId>" -H "Content-Type: application/json" \
  -d '{"toId":"987654321","amount":0.5}'

# 4) public receipt
curl -s https://bank.foxsrv.net/api/tx/<txid>