A resposta curta: a API lê as facturas, o saldo, as encomendas e as cotações, descarrega o PDF, paga facturas com o saldo da conta, muda o ciclo da próxima renovação e regista pedidos de cancelamento. Só cobra do saldo: para pagar de outra forma, use o Meu Interweb ou o endereço url de cada factura.
As permissões
| Para |
Permissão |
| Ler facturas, encomendas e cotações, ver ciclos e obter a ligação de upgrade |
billing:read |
| Mudar o ciclo da próxima renovação |
billing:write |
| Pagar com saldo |
billing:pay (sensível) |
| Pedir o cancelamento de um serviço |
services:cancel (sensível) |
Ler facturas e descarregar o PDF
GET /v1/invoices devolve as facturas, primeiro as mais recentes, em páginas; ?status=unpaid mostra só as por pagar. GET /v1/invoices/{id} traz também as linhas.
| Campo |
O que é |
| total |
O total da factura, incluindo o que foi pago com saldo. |
| credit_applied |
O que foi pago com saldo. |
| balance_due |
O que ainda falta pagar. |
GET /v1/invoices/{id}/pdf devolve o PDF em content, em base64. Às vezes não sai pela API: pdf_available vem a false, reason diz porquê e url leva à factura no Meu Interweb. O saldo e os movimentos estão em GET /v1/billing/credit e GET /v1/billing/transactions.
Pagar uma factura com o saldo
curl https://api.interweb.co.mz/v1/invoices/3127/pay -X POST \
-H "Authorization: Bearer $RLX_API_KEY" \
-H "Idempotency-Key: 0f8fad5b-d9cb-469f-a165-70867728950e"
| 1 |
Envie sempre Idempotency-Key: repetir com a mesma chave não cobra outra vez.
|
|
| 2 |
Se o saldo não chegar, responde 402 e nada é cobrado.
|
|
| 3 |
O total conta para o limite de gastos da chave. Se o passar, responde 403 spending_limit_exceeded, antes de cobrar.
|
|
| 4 |
Confira status e amount_charged. Se a factura já tinha sido paga entretanto, amount_charged vem a 0.
|
|
Para carregar o saldo, ou pagar com outro método, veja como pagar a sua factura.
Mudar o ciclo da próxima renovação
| 1 |
Veja os ciclos à venda e o preço de cada um com GET /v1/services/{id}/billing-cycles. Aqui nada muda.
|
|
| 2 |
Peça a mudança com PUT /v1/services/{id}/billing-cycle, com o cycle e o preço que viu em expected_amount. Se o preço tiver mudado, responde 409 price_changed e nada é alterado.
|
|
A mudança vale para a próxima renovação: nada se cobra agora e a data de vencimento não muda. Não muda pela API se houver uma factura por pagar desse serviço (invoice_open), num VPS ou servidor (vps_not_supported) ou num serviço com preço próprio (custom_price). Nesses casos, can_change vem a false e blocked_reason diz porquê.
Encomendas, cotações, upgrade e cancelamentos
| Operação |
O que faz |
| GET /v1/orders, /v1/orders/{id} |
As encomendas e o que veio em cada uma. |
| GET /v1/quotes, /v1/quotes/{id} |
As cotações entregues, com a proposta e as linhas. |
| GET /v1/services/{id}/upgrade-link |
A ligação para o Meu Interweb, onde escolhe o plano novo e vê o valor antes de pagar. |
| POST /v1/services/{id}/cancellation |
Regista o cancelamento para o fim do período pago, nunca de imediato. Leva reason e, em confirm, o domínio do serviço (ou o nome do plano). |
|
O cancelamento não é imediato: o serviço continua activo até à data de service_ends_at, e as facturas por pagar desse serviço podem ser canceladas. Um serviço sem período pago em curso, como um gratuito ou um em atraso, responde 409 no_period_end: nesse caso, fale com o suporte.
|
|
Uma ideia prática: um script diário lista as facturas com ?status=unpaid, compara o balance_due com o saldo de GET /v1/billing/credit e paga as que couberem, com uma chave que só tem billing:read e billing:pay e um limite de gastos à medida.
|
|
Quer pagar facturas a partir do seu sistema? Veja a página da API e teste com uma chave Sandbox, que diz se o pagamento passaria sem cobrar nada.
Ver a página da API
|
Português
English
