POST /apiv2/billing/limits

Створюйте, змінюйте, вимикайте та вмикайте власні ліміти в межах кредитного ліміту, встановленого Netts. Ліміти, встановлені Netts, не можна змінити за допомогою цих кінцевих точок. Частина післяоплатної тарифікації.

Кінцеві точки

Кінцева точка	Дія
POST /apiv2/billing/limits	створити власний ліміт
PUT /apiv2/billing/limits/{id}?scope=account	змінити його значення
POST /apiv2/billing/limits/{id}/disable?scope=account	вимкнути його — він перестає застосовуватися, нічого не видаляється
POST /apiv2/billing/limits/{id}/enable?scope=account	увімкнути його знову

{id} — це id ліміту з limits. Для змін обов'язковим є scope=account.

Заголовки запиту

Заголовок	Обов'язковий	Опис
X-API-KEY	так	API-ключ із дозволом limits.write
X-Real-IP	так	Адреса з білого списку ключа
Idempotency-Key	так	унікальний рядок, 8–128 символів, один на зміну
Content-Type	так	application/json

Idempotency-Key робить повторні спроби безпечними. Повторіть запит із тим самим ключем і тим самим тілом — наприклад, після тайм-ауту — і ви отримаєте початкову відповідь; зміна не буде застосована двічі. Той самий ключ із іншим тілом відхиляється з помилкою 409 idempotency_conflict.

expectedRevision захищає вас від перезапису зміни, яку ви не бачили. Надішліть revision, яку ви зчитали останньою (0 під час створення ліміту). Якщо ліміт тим часом змінився, запит відхиляється з помилкою 409 revision_conflict — зчитайте limits знову і повторіть спробу.

Створення ліміту

Поле	Тип	Обов'язкове	Опис
productCode	рядок або null	ні	energy_1h, energy_5m, bandwidth, activation, aml_check; null або пропущено для вашого загального ліміту
period	рядок	так	outstanding, day, week або order
value	рядок	так	сума у валюті ліміту Netts, не вища за нього
expectedRevision	ціле число	так	0

Ви можете мати один власний ліміт для кожного продукту та періоду. Валюта береться з ліміту Netts — поле валюти відсутнє.

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

Ліміт починає застосовуватися до наступного замовлення негайно.

Зміна ліміту

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

Поле	Тип	Обов'язкове	Опис
value	рядок	так	нова сума, не вища за ліміт Netts
expectedRevision	ціле число	так	поточна revision ліміту

Відповідь має такий самий формат, як вище, зі значенням revision, збільшеним на одиницю.

Вимкнення або увімкнення ліміту

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

Тіло запиту містить лише expectedRevision. /enable працює так само. Вимкнений ліміт залишається у списку з "enabled": false і може бути увімкнений пізніше; це не впливає на вашу заборгованість та нарахування.

Чого ви не можете робити

• Змінювати або вимикати ліміт із "origin": "netts" чи ліміт ключа — 403 netts_limit_readonly, навіть для його зменшення.
• Встановлювати значення, вище за ліміт Netts — 422 above_account_limit.
• Створювати другий ліміт для одного й того ж продукту та періоду — 409 limit_exists; замість цього змініть існуючий.
• Створювати ліміт до того, як Netts встановить кредитний ліміт вашого акаунта — 409 no_account_limit.
• Вмикати ліміт, валюта якого відрізняється від поточної валюти ліміту Netts — 422 unit_mismatch; спочатку встановіть нове значення.

Помилки

HTTP	code	Значення
400	invalid_request, invalid_amount	поле відсутнє або має неправильний формат
400	idempotency_key_required, invalid_idempotency_key	немає Idempotency-Key або довжина не 8–128 символів
401	-1, -2	ключ відсутній або недійсний, або IP немає у білому списку — відповідь API-шлюзу, див. формат відповіді
403	forbidden	ключ не має дозволу limits.write
403	postpaid_disabled	післяоплатну тарифікацію призупинено: ліміти не можна змінювати
403	netts_limit_readonly	ліміт встановлено Netts
404	not_found	такий ліміт відсутній на вашому акаунті
409	revision_conflict, limit_exists, idempotency_conflict, no_account_limit	див. вище
422	above_account_limit, product_not_postpaid, unit_mismatch	значення перевищує ліміт Netts, невідомий продукт, змінилася валюта ліміту Netts

Усі коди перелічені в розділі післяоплатна тарифікація.