# Vender crédito pré-pago

Active um contador como pré-pago, calcule quantos litros um valor compra e venda crédito ao balcão, com o token STS e o recibo na mesma resposta.


## O que vai construir

Uma venda ao balcão completa, feita pela Business API: escolhe um contador já ligado a uma conta, inscreve-o como pré-pago, pede uma cotação para saber quantos litros o valor compra e regista a venda. Numa única chamada, o servidor regista o pagamento, credita e debita a carteira do contador, gera o token e lança a venda na contabilidade. No fim, descarrega o recibo em PDF para entregar ao cliente.

As compras feitas pelos próprios moradores com dinheiro móvel seguem outro caminho (`POST $CONSUMER_API/prepaid/purchases`): a venda fica em `pending_payment` e o token só é emitido quando o pagamento é confirmado. Esse fluxo está no guia da app para moradores.

## Pré-requisitos

- Uma sandbox e uma chave de teste com estas permissões: `business:meters:read` (operação `listMeters`), `business:prepaid:manage` (`enrollPrepaidMeter`), `business:prepaid:read` (`quotePrepaidVend`, `getPrepaidVend`, `getPrepaidVendReceipt`) e `business:prepaid:vend` (`createPrepaidVend`).
- Um contador ligado a uma conta com tarifa. Um contador sem conta é recusado com `400`.
- Uma instalação capaz de gerar tokens STS. No ambiente de desenvolvimento, o servidor instala um gerador de teste cujos tokens começam por `DEV-STUB-` e chegam com `token_is_dev_stub` a `true`. Onde não há gerador instalado, a venda devolve `503` antes de se cobrar qualquer valor.

## 1. Encontrar o contador

Liste os contadores da empresa e anote o `id` (começa por `mtr_`) de um que tenha `account_id`.

```bash
curl -sS "$BUSINESS_API/meters?limit=5" \
  -H "Authorization: Bearer $API_KEY"
```

✓ Checkpoint: a resposta tem um array `data`; cada contador traz o seu `id` e a conta a que está ligado.

## 2. Inscrever o contador como pré-pago

```bash
curl -sS -X POST "$BUSINESS_API/prepaid/meters" \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"meter_id":"mtr_2pK8vN3qXw7LcR5tBz9hYm1dFgA"}'
```

```json
{
  "id": "ppm_2pL4rT8yHn2WqX6vCk1bZs9mJeD",
  "tenant_id": "ten_2jR5wQ8nLm3KxT9vB6cYpZ1dHgF",
  "meter_id": "mtr_2pK8vN3qXw7LcR5tBz9hYm1dFgA",
  "meter_serial": "04112233445",
  "account_id": "act_2nF7cJ4pVb9RtK2xLw6qHm3sZyE",
  "account_number": "CTA-000044",
  "customer_id": "cus_2kFq9AbN4yPdS8uMqX5iZc0tEfB",
  "tariff_id": "trf_2mC9xL3kRb7NwT5vQp1hYd8gFsJ",
  "status": "active",
  "balance_cents": 0,
  "created_at": "2026-11-19T09:12:04Z",
  "updated_at": "2026-11-19T09:12:04Z"
}
```

✓ Checkpoint: o estado HTTP é `201`, o `id` começa por `ppm_` e `status` é `active`. A partir daqui, as operações pré-pagas usam este `id` da inscrição e não o `id` do contador. Repetir a inscrição devolve `409`.

## 3. Pedir uma cotação

A cotação converte o valor no maior número inteiro de litros que ele compra com a tarifa do contador. Conta o volume já vendido no mês e, na primeira compra do mês, inclui a taxa fixa do período. Não cobra nada nem gera token.

```bash
curl -sS -X POST "$BUSINESS_API/prepaid/meters/ppm_2pL4rT8yHn2WqX6vCk1bZs9mJeD/quote" \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"amount_cents":50000}'
```

```json
{
  "litres": 1850,
  "net_cents": 39830,
  "sanitation_cents": 3980,
  "tax_cents": 6070,
  "remainder_cents": 120,
  "currency": "MZN",
  "tariff_id": "trf_2mC9xL3kRb7NwT5vQp1hYd8gFsJ"
}
```

✓ Checkpoint: `litres` é maior que zero e `net_cents`, `sanitation_cents`, `tax_cents` e `remainder_cents` somam o valor pedido. Um valor tão baixo que não compra água devolve `400`.

## 4. Vender ao balcão

O corpo exige `prepaid_meter_id`, `amount_cents` (de 1 a 100000000) e `idempotency_key`. O campo `method` é opcional e fica `cash` quando omitido. Seja qual for o método, `cash` incluído, tem de constar dos meios de pagamento disponíveis na empresa, que `GET $BUSINESS_API/payment-methods` lista. Repetir a mesma `idempotency_key` devolve a venda já existente em vez de cobrar duas vezes.

```bash
curl -sS -X POST "$BUSINESS_API/prepaid/vends" \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"prepaid_meter_id":"ppm_2pL4rT8yHn2WqX6vCk1bZs9mJeD","amount_cents":50000,"idempotency_key":"balcao-0419-a7"}'
```

```json
{
  "id": "vnd_2pM6sW1zKc8YqB4nDf7tXh3rLuG",
  "prepaid_meter_id": "ppm_2pL4rT8yHn2WqX6vCk1bZs9mJeD",
  "meter_id": "mtr_2pK8vN3qXw7LcR5tBz9hYm1dFgA",
  "account_id": "act_2nF7cJ4pVb9RtK2xLw6qHm3sZyE",
  "status": "issued",
  "amount_cents": 50000,
  "net_cents": 39830,
  "sanitation_cents": 3980,
  "tax_cents": 6070,
  "remainder_cents": 120,
  "litres": 1850,
  "currency": "MZN",
  "token": "DEV-STUB-9F3A61C2-NAO-E-TOKEN-STS",
  "token_provider": "dev-stub",
  "token_is_dev_stub": true,
  "payment_id": "pay_2pM6sX4bNd2ZrC8kEg5vYj7tMwH",
  "method": "cash",
  "idempotency_key": "balcao-0419-a7",
  "receipt_number": "RCP-000318",
  "issued_at": "2026-11-19T09:14:37Z",
  "created_at": "2026-11-19T09:14:36Z",
  "updated_at": "2026-11-19T09:14:37Z"
}
```

✓ Checkpoint: o estado HTTP é `201`, `status` é `issued` e o campo `token` tem o código a introduzir no contador. Mostre-o ao cliente só depois de verificar `token_is_dev_stub`: um token de teste não funciona num contador real. O `remainder_cents` fica na carteira e soma-se à compra seguinte.

## 5. Descarregar o recibo

```bash
curl -sS "$BUSINESS_API/prepaid/vends/vnd_2pM6sW1zKc8YqB4nDf7tXh3rLuG/receipt.pdf?layout=mobile" \
  -H "Authorization: Bearer $API_KEY" -o recibo.pdf
```

✓ Checkpoint: o ficheiro `recibo.pdf` é um PDF. O parâmetro `layout` aceita `a4` (por omissão) ou `mobile`; vendas em `pending_payment` ou `failed` não têm recibo e devolvem `404`.

## Erros a tratar

- `409` com `code` `CONFLICT`: o contador está suspenso (`POST $BUSINESS_API/prepaid/meters/{id}/status` com `{"status":"active"}` reactiva-o).
- `503` com `code` `INTEGRATION_UNAVAILABLE`: não há gerador de tokens pronto; nada foi cobrado.
- Se o pagamento não puder ser registado (por exemplo, com um método que a empresa não configurou), ou se o token falhar depois disso, a venda passa a `failed` e `failure_reason` indica o passo que falhou; consulte-a com `GET $BUSINESS_API/prepaid/vends/{id}`.

## Testar

Abra o painel da sandbox em **Pré-pago**. A venda aparece na secção **Vendas** com os litros e a coluna **Token**, e o contador aparece em **Contadores** com o saldo da carteira; o botão **Recibo** do detalhe descarrega o mesmo PDF. O pagamento registado pela venda dispara o evento `payment.received`. Para o ver chegar ao seu servidor local:

```bash
gotactl webhooks listen --events payment.received --forward-to http://localhost:3000/hook
```

A flag `--events` limita os tipos de evento reencaminhados e `--forward-to` indica o URL local que recebe os POST. Pode também confirmar a venda pela CLI com `gotactl api GET business:/prepaid/vends -f status=issued`.

## Próximos passos

- [Receber pagamentos por qualquer conector](/docs/guides/receive-payments)
- [Construir a app para moradores, com compras por dinheiro móvel](/docs/guides/resident-app)
- [Ouvir eventos com webhooks](/docs/guides/listen-webhooks)
- [Repetir pedidos com segurança](/docs/getting-started/idempotency)
- [Todas as operações pré-pagas na referência da Business API](/docs/api/business)

