# 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

- [Guia de testes](/docs/testing)
- [Testar webhooks com a CLI e o painel](/docs/webhooks/testing)
- [O que muda ao passar para produção](/docs/go-live)

