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 лимита из лимитов. 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 — прочитайте лимиты заново и повторите попытку.

Создание лимита

Поле	Тип	Обязательное	Описание
productCode	string или null	нет	energy_1h, energy_5m, bandwidth, activation, aml_check; null или опущено для общего лимита
period	string	да	outstanding, day, week или order
value	string	да	сумма в валюте лимита Netts, не превышающая его
expectedRevision	integer	да	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	string	да	новая сумма, не превышающая лимит Netts
expectedRevision	integer	да	текущая 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

Все коды перечислены в разделе постоплатный биллинг.