PT EN

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-000002 e 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.

bash
curl -sS -X POST "$BUSINESS_API/sandbox/advance" \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"readings":true}'
json
{
  "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.

Próximos passos#