Visão geral
Os cartões presente, passes de crédito em loja e carteiras pré-pagas de circuito fechado na Passinstance assentam num livro-razão imutável de partida dobrada (modelos prepaid account e prepaid ledger entry) em vez de um campo de texto desprotegido. Todos os montantes monetários são armazenados e calculados em unidades inteiras na subunidade monetária mínima (balanceMinor, como cêntimos), com bloqueio estrito ao nível da linha e invariantes de saldo não negativo (disallowNegativeBalance: true).
Importante: As deduções de valor armazenado falham de forma segura (fail closed) com
decision: "FAILED"ereasonCode: "OUT_OF_BALANCE"sempre que a dedução solicitada excederbalanceMinornuma conta configurada comdisallowNegativeBalance: true. Nunca calcule saldos no cliente; submeta sempre a variação da transação e deixe o livro-razão de backend confirmar o novo saldo.
Arquitetura do Livro-Razão de Valor Armazenado
Superfícies de Resgate e Ajuste de Valor Armazenado
Consoante a sua configuração física de caixa ou fluxo de trabalho na consola de suporte, pode deduzir ou recarregar saldos pré-pagos através de quatro endpoints dedicados:
| Superfície | Endpoint | Autenticação | Caso de Utilização Principal | |||||
|---|---|---|---|---|---|---|---|---|
| Scanner Móvel / Web | POST /api/v1/scans | x-scanner-key | Aplicação scanner da equipa configurada com StoredValueOperation (`NONE | ADD | SUBTRACT | SET) e StoredValueAmountSource (FIXED | OPERATOR | MECHANIC`). |
| Leitor NFC de Hardware | POST /api/v1/reader/redeem | X-Reader-Secret | Orquestração servidor-para-leitor que submete request payload (customerId, passId, amount, idempotencyKey). (Utilize POST /api/v1/reader/validate para verificação de entrada por código de barras.) | |||||
| Terminal POS de Retalho | POST /v1/pos/redeem | Token do Terminal POS / Bearer | Caixas registadoras integradas que executam PosOperation.DEDUCT_VALUE com passRef (serialNumber, código de barras ou externalId) e clientTxRef. | |||||
| Carregamento no Painel / Admin | POST /api/v1/passes/:id/adjust-value | JWT do Espaço de Trabalho / Chave API (pass:manage) | Carregamentos manuais de cartão presente (action: "CREDIT"), reembolsos ou correções administrativas (action: "DEBIT"). |
1. Débito no Scanner de Balcão (POST /api/v1/scans)
Quando uma ScannerConfiguration utiliza StoredValueOperation.SUBTRACT e StoredValueAmountSource.OPERATOR, o operador de caixa introduz o total da compra e submete:
/api/v1/scans
{
"scannedBarcodeValue": "PI-GFT-901244",
"scannerConfigurationId": "scfg_giftcard_debit",
"validationData": {
"amount": 24.50,
"currency": "EUR"
},
"operatorId": "emp_cashier_04"
}
Resposta (200 OK):
{
"decision": "SUCCESS",
"status": "ACCEPTED",
"remainingBalance": "75.50",
"effects": {
"oldBalance": "100.00",
"newBalance": "75.50",
"transactionAmount": 24.50,
"currency": "EUR",
"amountBalanceBehavior": "ADD_VALUE"
},
"passSnapshot": {
"id": "pass_gft_901244",
"templateId": "tmpl_giftcard_eur",
"serialNumber": "PI-GFT-901244",
"externalId": "shopify_gift_901244",
"status": "ACTIVE",
"storedValue": "75.50"
},
"display": {
"title": "€24.50 Deducted",
"subtitle": "Remaining Balance: €75.50",
"color": "success"
}
}
2. Orquestração de Leitores de Hardware (POST /api/v1/reader/redeem)
Os gateways de leitores óticos e sem contacto do lado do servidor autenticam-se com o cabeçalho X-Reader-Secret (reader integration secret) e submetem request payload diretamente para /api/v1/reader/redeem (quando amount é omitido, o motor executa VALIDATE; quando fornecido, executa DEBIT):
/api/v1/reader/redeem
{
"customerId": "c1a2b3c4-d5e6-4f7a-8b9c-0123456789ab",
"passId": "f9e8d7c6-b5a4-4321-9876-543210fedcba",
"amount": "15.00",
"idempotencyKey": "nfc-01:tx-883920",
"operatorId": "nfc_gate_berlin_01"
}
Resposta (200 OK):
{
"success": true,
"resultingValue": "60.50"
}
3. Integração POS de Retalho (POST /v1/pos/redeem)
Os sistemas de ponto de venda executam deduções atómicas com POST /v1/pos/redeem (montado sob /v1/pos, fora de /api/v1). passRef corresponde a qualquer token de passe, código de barras, serialNumber ou ao seu externalId de origem:
{
"idempotencyKey": "tenant_01:reg_03:tx_994812",
"passRef": "PI-GFT-901244",
"terminalId": "reg_03",
"operation": "DEDUCT_VALUE",
"amount": 15.00,
"currency": "EUR",
"clientTxRef": "POS-INV-2026-994812"
}
Os valores PosOperation suportados são DISCOUNT, ADD_POINTS, DEDUCT_VALUE, ADD_STAMPS, VOID e CUSTOM. A resposta devolve walletPropagation (PosWalletPropagationStatus: QUEUED ou SKIPPED) quando as atualizações push em tempo real são colocadas em fila para APNs/Google Wallet.
4. Carregamentos Manuais e Correções (POST /api/v1/passes/:id/adjust-value)
Para reembolsos, créditos de apoio ao cliente ou carregamentos de cartões presente a partir do Painel ou de uma integração ERP, chame POST /api/v1/passes/:id/adjust-value com Idempotency-Key:
{
"action": "CREDIT",
"amount": "25.00",
"reason": "Customer return store credit",
"operatorId": "support_lead_02",
"idempotencyKey": "adj-20261116-0041"
}
As ações de ajuste suportadas são CREDIT (adicionar saldo) e DEBIT (subtrair saldo).
Modelo de Livro-Razão de Partida Dobrada (prepaid account e prepaid ledger entry)
Cada passe de valor armazenado mantém um registo prepaid account emparelhado com linhas só de acréscimo (append-only) prepaid ledger entry:
| Campo | Modelo | Tipo | Descrição |
|---|---|---|---|
balanceMinor | prepaid account | Int | Saldo atual na subunidade monetária mínima (ex.: 7550 = €75.50). |
currency | prepaid account | String | Código de moeda ISO 4217 de 3 letras (EUR, USD, GBP, CHF). |
disallowNegativeBalance | prepaid account | Boolean | Predefinido como true; impõe balanceMinor >= 0 na camada de transação da base de dados. |
deltaMinor | prepaid ledger entry | Int | Variação inteira com sinal (-2450 para débito, +5000 para carregamento). |
balanceAfterMinor | prepaid ledger entry | Int | Instantâneo de balanceMinor imediatamente após o lançamento. |
idempotencyKey | prepaid ledger entry | String | Chave única de transação que evita débitos duplicados em repetições de rede. |
Para auditar todos os débitos históricos, carregamentos e referências de operadores, consulte GET /api/v1/mechanics/:mechanicId/passes/:passId/ledger ou GET /api/v1/balance-changes. Saiba mais em Cartões Presente e Cartões Pré-Pagos e Leitores NFC Compatíveis.
