PT EN

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"

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"
}

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"
}

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"
}

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

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#