Faturamento pós-pago

Com o faturamento pós-pago, você solicita Energy, Bandwidth, ativação e verificações AML sem precisar fazer uma recarga de depósito antes. Os serviços são precificados utilizando a tarifa específica aplicável ao cliente, incluindo descontos aplicáveis. Cobranças, pagamentos e ajustes são refletidos em sua fatura sob os termos de faturamento e pagamento do seu contrato.

O pós-pago é ativado pela Netts mediante solicitação para contas corporativas. Os endpoints desta seção respondem apenas para contas com faturamento pós-pago; outras contas recebem 403 postpaid_required.

Como funciona

1. Você faz pedidos normalmente. Os mesmos endpoints de pedidos, a mesma API key. Uma conta pós-paga não precisa de saldo de depósito para esses pedidos. O preço é o preço sob seu contrato, incluindo seus descontos.
2. Serviços fornecidos são registrados como cobranças. Um pedido aceito não é por si só um serviço fornecido. Uma cobrança aparece em uso assim que o serviço ou uma parte cobrável separadamente do pedido for fornecida — isso pode ocorrer depois da resposta do pedido.
3. O preço e a taxa são fixados e mantidos. Uma cotação válida fixa o preço sob seu contrato para aquele pedido. Sem uma cotação, aplica-se o preço sob seu contrato quando o pedido é feito, e o valor na moeda do seu contrato é calculado na taxa do momento em que o serviço é fornecido. Os valores registrados não são recalculados quando você consulta o uso, recebe uma fatura ou efetua um pagamento.
4. Você recebe e paga sua fatura. O período de faturamento e os termos de pagamento são aqueles acordados em seu contrato. Uma fatura mostra os serviços do período, os pagamentos e ajustes aplicados, e o valor ainda a pagar; um pagamento não exclui os registros de serviço. Veja faturas e pagamentos. A moeda de pagamento, a rede e o prazo de pagamento são mostrados em settlement em conta. Um pagamento a maior permanece em sua conta como crédito e é utilizado para as próximas cobranças.

Tarifa, cotação e taxa de câmbio registrada

Uma cotação (freezePrice) fixa o preço sob seu contrato por um minuto. Faça o pedido com quoteId e os mesmos parâmetros dentro desse minuto, e ele será faturado pelo preço cotado, mesmo que o preço mude ou o serviço seja fornecido mais tarde. Uma cotação é opcional; veja Energy de 1 hora e Energy de 5 minutos para os campos de requisição.

Sem uma cotação, o valor na moeda do seu contrato é calculado na taxa do momento em que o serviço é fornecido, não quando você consultou um preço ou a sua conta. A taxa atual — a sua taxa e a exibida nas respostas da conta — serve apenas para comparação; não é uma promessa da taxa de um pedido futuro.

Verificações AML são precificadas em dólares americanos e registradas na moeda do seu contrato; o equivalente em TRX é calculado na taxa do momento em que a verificação é concluída. Não recalcule uma cobrança de AML a partir de seu valor arredondado em TRX.

Os valores são mostrados em TRX e na moeda do seu contrato; seus limites são contabilizados na moeda do seu contrato. usdPerTrx é a taxa de TRX para a moeda do seu contrato. Você paga na moeda e rede do seu contrato, mostradas em settlement.

Um pedido pode ter mais de uma cobrança, por exemplo, Energy e uma ativação cobrada separadamente. Cada cobrança tem sua própria hora e taxa. Os valores são arredondados uma única vez para seis casas decimais, arredondamento bancário (half-even); uma cotação mantém seus valores cotados. Concilie um pedido por suas cobranças, e não aplicando uma taxa atual ao seu total.

Todos os horários estão em UTC. Todos os valores são strings decimais, por exemplo "30000.000000" — processe-os com um tipo decimal, não ponto flutuante.

Limite de crédito

A Netts define o limite de crédito da sua conta: o valor máximo que você pode dever a qualquer momento. Ele é exibido em conta e limites com "origin": "netts". Você pode visualizá-lo, mas não pode alterá-lo ou desativá-lo — fale com seu gerente da Netts se precisar de um limite diferente.

Produtos e API keys compartilham esse limite de crédito único no nível da conta. Cada novo pedido é verificado contra todos os limites aplicáveis. Quando essa verificação constatar crédito disponível insuficiente, o pedido é recusado antes da execução:

{
  "detail": {
    "code": 1004,
    "msg": "Postpaid credit limit reached.",
    "paymentMode": "postpaid",
    "reason": "limit_reached",
    "product": "*",
    "period": "outstanding",
    "limitId": 1
  }
}

O endpoint de pedido responde com 402. Um pagamento libera o limite novamente. Se a verificação estiver temporariamente indisponível, o endpoint de pedido responde 503 com o código 5036 — tente novamente mais tarde, nada foi cobrado pela tentativa rejeitada. Um valor disponível mostrado por uma requisição de leitura é o número atual, não uma reserva para um pedido posterior; outros pedidos aceitos podem alterá-lo.

Seus próprios limites

Dentro do limite da Netts, você pode definir seus próprios limites mais baixos — para manter os gastos sob controle ou restringir produtos individuais:

• Seu próprio limite geral — o total que você se permite dever, abaixo do limite da Netts.
• Um limite de produto — quanto um produto pode usar, por exemplo energy_5m.

Seus limites nunca acrescentam crédito. Os limites de produtos não se acumulam: com um limite da Netts de 50 USD, limites de produto de 50 USD para energy_1h e 50 USD para energy_5m ainda compartilham 50 USD de crédito no nível da conta. A verificação do pedido aplica todos os limites relevantes, e limites mostra para cada produto quanto pode ser gasto no momento.

Um limite pode contabilizar:

period	O que é contabilizado
outstanding	cobranças não pagas, mais pedidos aceitos ainda não registrados
day	cobranças do dia UTC atual, incluídas as pagas, mais pedidos aceitos ainda não registrados
week	cobranças da semana UTC atual a partir de segunda-feira 00:00 UTC, incluídas as pagas, mais pedidos aceitos ainda não registrados
order	o valor de um único novo pedido

Um pagamento reduz sua dívida, mas não zera o uso do dia ou da semana. O crédito de um pagamento a maior é exibido como creditApplied e conta uma vez contra sua dívida geral; ele não é adicionado ao limite de cada produto.

Seus limites estão na moeda do limite da Netts e não podem ser maiores do que ele. Se a Netts reduzir o limite dela abaixo de um dos seus, a restrição aplicável mais baixa permanece em vigor.

Produtos: energy_1h, energy_5m, bandwidth, activation, aml_check.

Permissões de API key

Cada API key precisa de uma permissão para esta seção. Seu gerente da Netts a concede por chave:

Permissão	Permite
billing.read	conta, taxa, limites, uso, faturas e pagamentos
limits.write	criar, alterar, desativar e ativar seus próprios limites

Sem a permissão, o endpoint responde 403 com billing_read_required ou forbidden. A lista de permissões de IP da chave se aplica como para qualquer outro endpoint. Esses endpoints permanecem disponíveis quando o saldo de depósito é zero.

Endpoints

Endpoint	O que faz
GET /apiv2/billing/account	limite de crédito, dívida e o que está disponível agora
GET /apiv2/billing/rate	a sua taxa atual de TRX para a moeda do seu contrato
GET /apiv2/billing/limits	todos os limites com valores usados e disponíveis, disponível por produto
POST /apiv2/billing/limits	criar, alterar, desativar e ativar seus próprios limites
GET /apiv2/billing/usage	componentes de cobrança, vinculados aos seus pedidos
GET /apiv2/billing/invoices	faturas, uma fatura com suas cobranças
GET /apiv2/billing/payments	pagamentos e crédito

Formato de resposta

{ "success": true, "data": { }, "timestamp": "2026-10-19T20:12:30+00:00" }

Um erro do serviço:

{
  "success": false,
  "error": { "code": "postpaid_required", "message": "this account has no postpaid billing" },
  "timestamp": "2026-10-19T20:12:30+00:00"
}

Uma chave ausente ou inválida, ou uma requisição de um IP fora da lista de permissões da chave, é recusada pelo gateway de API antes de chegar ao serviço, com 401:

{ "detail": { "code": -1, "msg": "Invalid or missing API key" } }

O código -2 com "Invalid API key or IP not in whitelist" significa que o IP não está na lista de permissões da chave. Mais de 10 requisições por segundo ou 300 por minuto a partir de um IP são recusadas com 429 e {"message": "API rate limit exceeded"}.

HTTP	code	Significado
400	invalid_request, invalid_amount, idempotency_key_required, invalid_idempotency_key	um parâmetro está ausente ou tem formato incorreto
403	postpaid_required	a conta não tem faturamento pós-pago
403	postpaid_disabled	o faturamento pós-pago está pausado: você pode ler, mas não alterar limites
403	billing_read_required, forbidden	a chave não possui billing.read ou limits.write
403	netts_limit_readonly	o limite é definido pela Netts e não pode ser alterado
404	not_found	nenhum limite ou fatura desse tipo na sua conta
409	revision_conflict	o limite foi alterado enquanto isso — leia-o novamente
409	limit_exists	você já tem um limite para este produto e período
409	idempotency_conflict	a Idempotency-Key foi usada com outra requisição
409	no_account_limit	a conta ainda não tem limite de crédito definido pela Netts
422	above_account_limit	o valor é maior do que o limite da Netts
422	product_not_postpaid	o produto não está disponível no pós-pago
422	unit_mismatch	a moeda do limite da Netts foi alterada — defina um novo valor antes de ativar seu limite
503	unavailable	temporariamente indisponível — tente novamente mais tarde
503	rate_unavailable	a sua taxa está temporariamente indisponível — tente novamente mais tarde