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çãolistMeters),business:prepaid:manage(enrollPrepaidMeter),business:prepaid:read(quotePrepaidVend,getPrepaidVend,getPrepaidVendReceipt) ebusiness: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 comtoken_is_dev_stubatrue. Onde não há gerador instalado, a venda devolve503antes 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.
curl -sS "$BUSINESS_API/meters?limit=5" \
-H "Authorization: Bearer $API_KEY"
2. Inscrever o contador como pré-pago#
curl -sS -X POST "$BUSINESS_API/prepaid/meters" \
-H "Authorization: Bearer $API_KEY" \
-H "Content-Type: application/json" \
-d '{"meter_id":"mtr_2pK8vN3qXw7LcR5tBz9hYm1dFgA"}'
{
"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.
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}'
{
"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.
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"}'
{
"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#
curl -sS "$BUSINESS_API/prepaid/vends/vnd_2pM6sW1zKc8YqB4nDf7tXh3rLuG/receipt.pdf?layout=mobile" \
-H "Authorization: Bearer $API_KEY" -o recibo.pdf
Erros a tratar#
409comcodeCONFLICT: o contador está suspenso (POST $BUSINESS_API/prepaid/meters/{id}/statuscom{"status":"active"}reactiva-o).503comcodeINTEGRATION_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
failedefailure_reasonindica o passo que falhou; consulte-a comGET $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:
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.