POST /apiv2/billing/limits

Crie, altere, desative e ative seus próprios limites dentro do limite de crédito definido pela Netts. Os limites definidos pela Netts não podem ser alterados com estes endpoints. Parte do faturamento pós-pago.

Endpoints

Endpoint	Descrição
POST /apiv2/billing/limits	cria seu próprio limite
PUT /apiv2/billing/limits/{id}?scope=account	altera o valor dele
POST /apiv2/billing/limits/{id}/disable?scope=account	desativa — ele deixa de ser aplicado, nada é excluído
POST /apiv2/billing/limits/{id}/enable?scope=account	ativa novamente

{id} é o id do limite de limites. scope=account é obrigatório para alterações.

Cabeçalhos da Requisição

Cabeçalho	Obrigatório	Descrição
X-API-KEY	sim	Chave de API com a permissão limits.write
X-Real-IP	sim	Um endereço da lista de permissões da chave
Idempotency-Key	sim	uma string única, de 8 a 128 caracteres, uma por alteração
Content-Type	sim	application/json

Idempotency-Key torna uma nova tentativa segura. Repita uma requisição com a mesma chave e o mesmo corpo — após um timeout, por exemplo — e você receberá a resposta original de volta; a alteração não é feita duas vezes. A mesma chave com um corpo diferente é recusada com 409 idempotency_conflict.

expectedRevision protege você contra a substituição de uma alteração que você ainda não viu. Envie a revision que você leu pela última vez (0 quando você cria um limite). Se o limite foi alterado nesse meio-tempo, a requisição é recusada com 409 revision_conflict — leia limites novamente e tente de novo.

Criar um limite

Campo	Tipo	Obrigatório	Descrição
productCode	string ou null	não	energy_1h, energy_5m, bandwidth, activation, aml_check; null ou omitido para o seu limite geral
period	string	sim	outstanding, day, week ou order
value	string	sim	a quantia, na moeda do limite da Netts, não superior a ele
expectedRevision	integer	sim	0

Você pode ter um limite próprio para cada produto e período. A moeda é obtida a partir do limite da Netts — não há campo de moeda.

curl -s -X POST 'https://netts.io/apiv2/billing/limits' \
  -H 'X-API-KEY: your-api-key' \
  -H 'X-Real-IP: 203.0.113.10' \
  -H 'Idempotency-Key: 6f1c2b8e-limit-5m-day' \
  -H 'Content-Type: application/json' \
  -d '{"productCode": "energy_5m", "period": "day", "value": "200", "expectedRevision": 0}'

{
  "success": true,
  "data": {
    "id": 5,
    "scope": "account",
    "origin": "client",
    "productCode": "energy_5m",
    "period": "day",
    "enabled": true,
    "limit": { "unit": "USD", "value": "200.000000" },
    "equivalent": { "unit": "TRX", "value": "604.514867" },
    "revision": 1,
    "fx": { "usdPerTrx": "0.33084276", "at": "2026-10-19T20:24:23.449930+00:00" },
    "fxStatus": "ok"
  },
  "timestamp": "2026-10-19T20:30:02+00:00"
}

O limite se aplica ao próximo pedido imediatamente.

Alterar um limite

curl -s -X PUT 'https://netts.io/apiv2/billing/limits/5?scope=account' \
  -H 'X-API-KEY: your-api-key' \
  -H 'X-Real-IP: 203.0.113.10' \
  -H 'Idempotency-Key: 6f1c2b8e-limit-5m-300' \
  -H 'Content-Type: application/json' \
  -d '{"value": "300", "expectedRevision": 1}'

Campo	Tipo	Obrigatório	Descrição
value	string	sim	a nova quantia, não superior ao limite da Netts
expectedRevision	integer	sim	a revision atual do limite

A resposta possui o mesmo formato mostrado acima, com a revision incrementada em um.

Desativar ou ativar um limite

curl -s -X POST 'https://netts.io/apiv2/billing/limits/5/disable?scope=account' \
  -H 'X-API-KEY: your-api-key' \
  -H 'X-Real-IP: 203.0.113.10' \
  -H 'Idempotency-Key: 6f1c2b8e-limit-5m-off' \
  -H 'Content-Type: application/json' \
  -d '{"expectedRevision": 2}'

O corpo contém apenas expectedRevision. O endpoint /enable funciona da mesma maneira. Um limite desativado permanece na lista com "enabled": false e pode ser ativado posteriormente; sua dívida e suas cobranças não são afetadas.

O que você não pode fazer

• Alterar ou desativar um limite com "origin": "netts" ou um limite de chave — 403 netts_limit_readonly, mesmo que seja para reduzi-lo.
• Definir um valor maior que o limite da Netts — 422 above_account_limit.
• Criar um segundo limite para o mesmo produto e período — 409 limit_exists; altere o existente em vez disso.
• Criar um limite antes que a Netts tenha definido o limite de crédito da sua conta — 409 no_account_limit.
• Ativar um limite cuja moeda difere do limite atual da Netts — 422 unit_mismatch; defina um novo valor primeiro.

Erros

HTTP	code	Significado
400	invalid_request, invalid_amount	um campo está ausente ou tem um formato incorreto
400	idempotency_key_required, invalid_idempotency_key	sem Idempotency-Key, ou ela não possui de 8 a 128 caracteres
401	-1, -2	a chave está ausente ou inválida, ou o IP não está na lista de permissões — respondido pelo gateway da API, consulte o formato de resposta
403	forbidden	a chave não possui a permissão limits.write
403	postpaid_disabled	o faturamento pós-pago está pausado: os limites não podem ser alterados
403	netts_limit_readonly	o limite é definido pela Netts
404	not_found	nenhum limite desse tipo na sua conta
409	revision_conflict, limit_exists, idempotency_conflict, no_account_limit	veja acima
422	above_account_limit, product_not_postpaid, unit_mismatch	valor acima do limite da Netts, produto desconhecido, moeda do limite da Netts alterada

Todos os códigos estão listados no faturamento pós-pago.