Sandbox
Um espaço de testes separado da conta real, com dados de exemplo, chaves só de teste, pagamentos que não saem para nenhum fornecedor e leituras novas a pedido com sandbox advance.
O que é uma sandbox#
Uma sandbox é uma conta de empresa de água à parte, ligada à sua conta real. Herda o país, a língua, a moeda e o fuso horário da conta real, mas não copia nenhum registo real nem a configuração dos conectores. O nome é o da conta seguido de "Sandbox".
Se o plano da conta tiver ambientes de teste, a sandbox nasce no próprio registo, e quem se regista fica como proprietário dela. No painel, entre pelo menu da conta em Mudar para sandbox e volte em Sair da sandbox; enquanto estiver lá dentro, uma faixa no topo lembra que os dados são de teste.
Dados de exemplo#
A sandbox criada no registo já vem preenchida, para poder chamar a API desde o primeiro minuto:
- zonas de serviço, tarifas e a rede (activos e topologia);
- seis clientes, cada um com conta, imóvel e ligação;
- um contador por ligação, com números de série
SBX-000001,SBX-000002e seguintes; - rotas de leitura, um ciclo de leituras com os consumos calculados e uma facturação;
- facturas em aberto, das quais no máximo metade já está paga, para ter histórico e facturas prontas a pagar.
Chaves na sandbox#
Uma sandbox só emite chaves de teste: sk_test_ (secreta) e sk_rtest_ (restrita). Pedir uma chave real numa sandbox devolve 400, e o painel mostra "No espaço de testes só se criam chaves de teste.". Ao contrário, pedir uma chave de teste numa conta real devolve 400 com "As chaves de teste criam-se no espaço de testes.".
No uso, uma chave de teste numa conta real, ou uma chave real numa sandbox, recebe 401. As permissões que movem dinheiro, como payments:write, só chegam a uma chave de teste quando o operador da instalação activou os pagamentos de teste.
Pagamentos de teste#
Com os pagamentos de teste activos, um pagamento iniciado na sandbox não chega a nenhum fornecedor real. A sessão fica pending e recebe uma referência que começa por sbx_. Passa a confirmada quando o cliente a confirma na área de cliente, com POST $CONSUMER_API/payment-sessions/{id}/sandbox/confirm, ou quando termina o atraso de confirmação automática, se o operador o configurou. A confirmação regista o pagamento, o recibo e a alocação à factura. Sem pagamentos de teste activos, essa chamada devolve 404.
Avançar a sandbox#
POST $BUSINESS_API/sandbox/advance aceita um corpo opcional com três campos:
| Campo | O que faz |
|---|---|
outcome |
Resultado a aplicar às sessões pendentes do conector de pagamento simulado: confirmed (por omissão), failed ou expired. Outro valor devolve 400. |
payment_id |
Limita a mudança à sessão com essa referência; sem ele, mudam todas as pendentes. |
readings |
Com true, regista uma leitura nova em cada contador da sandbox, 12,5 m³ acima da última. |
A resposta lista em advanced_payments as sessões que mudaram de estado (vem vazia quando não havia nenhuma pendente) e diz em generated_readings quantas leituras foram aceites.
curl -sS -X POST "$BUSINESS_API/sandbox/advance" \
-H "Authorization: Bearer $API_KEY" \
-H "Content-Type: application/json" \
-d '{"readings":true}'
{
"advanced_payments": [],
"generated_readings": 6
}
Numa conta real, o mesmo pedido devolve 403 com o título Sandbox Only.
Pela CLI#
gotactl sandbox advance faz o mesmo pedido e recusa-se a correr fora de um contexto de sandbox. Opções:
| Opção | Descrição |
|---|---|
--outcome |
Resultado a aplicar: confirmed (por omissão), failed ou expired. |
--payment |
Referência de uma sessão pendente a avançar; sem ela, avança todas. |
--readings |
Regista também uma leitura nova em cada contador. |
gotactl events trigger provoca eventos reais na sandbox activa (gotactl events trigger --list mostra os tipos suportados), e gotactl webhooks listen só aceita um contexto real com --live e --confirm-live.