Обновить расход трафика eSIM

POST/api/partner/v1/esim/orders/{id}/usage-refresh

Scope: esim:read

Запрашивает у провайдера текущий расход трафика и возвращает заказ.

Не чаще раза в минуту на заказ: внутри этого окна возвращается сохранённое значение с refreshed: false. Деньги не двигаются, Idempotency-Key не нужен.

Каждый вызов идёт к провайдеру, поэтому тратит и отдельный лимит ключа — 30 вызовов в минуту (или ваш общий лимит, если он ниже) на все заказы вместе; сверх него — 429 rate_limited.

Параметры пути

Параметр	Тип	Обяз.	Описание
`id`	string (uuid)	да	—

Пример запроса

TS=$(date +%s)
SIG=$(printf '%s\n%s\n%s\n%s' "$TS" "POST" "/api/partner/v1/esim/orders/7e6d5c4b-3a29-4180-9f7e-6d5c4b3a2918/usage-refresh" "" \
  | openssl dgst -sha256 -hmac "$PP_SECRET" -hex | awk '{print $NF}')

curl -sS -X POST "https://api.plativputi.com/api/partner/v1/esim/orders/7e6d5c4b-3a29-4180-9f7e-6d5c4b3a2918/usage-refresh" \
  -H "X-Key-Id: $PP_KEY_ID" \
  -H "X-Timestamp: $TS" \
  -H "X-Signature: $SIG"

const res = await pp("POST", "/esim/orders/7e6d5c4b-3a29-4180-9f7e-6d5c4b3a2918/usage-refresh");

res = pp("POST", "/esim/orders/7e6d5c4b-3a29-4180-9f7e-6d5c4b3a2918/usage-refresh")

$res = pp('POST', '/esim/orders/7e6d5c4b-3a29-4180-9f7e-6d5c4b3a2918/usage-refresh');

pp() — функция-обёртка с подписью из раздела Аутентификация и подпись.

Ответ

200 OK — EsimOrderDTO

Поле	Тип	Обяз.	Описание
`created_at`	string	да	—
`error_code`	string	нет	provider_rejected \| refunded \| needs_review \| order_expired \| unknown_order_status
`external_id`	string	нет	—
`id`	string	да	Наш идентификатор заказа eSIM
`operation_id`	string	да	Операция, держащая ваши деньги, — тот же id, что приходит в событиях
`operation_status`	string	да	processing \| succeeded \| failed \| needs_review — судьба вашего резерва
`package`	EsimPackageDTO	нет	Пакет в его текущем виде; price_usd выше — то, что вы заплатили
`package.countries`	array<string>	да	ISO alpha-2 коды стран, которые покрывает пакет. Пусто, если провайдер не опубликовал список.
`package.currency`	string	нет	—
`package.data_gb`	string	да	Объём трафика в ГБ, десятичная строка. Не имеет смысла, если unlimited = true.
`package.has_5g`	boolean	да	true, если в опубликованной сети упомянут 5G. false означает и «не указано».
`package.id`	string	да	Идентификатор пакета — передайте его как package_id в POST /esim/orders
`package.network`	string	нет	Поколение сети / операторы, как их опубликовал провайдер, если известны
`package.price_usd`	string	нет	Сколько покупка этого пакета спишет с вашего баланса, USD
`package.region_code`	string	да	ISO 3166-1 alpha-2 для пакета одной страны, иначе код региона (EUROPE, ASIA, GLOBAL, …)
`package.region_name`	string	да	—
`package.sms`	integer	нет	Включённые SMS, если они есть в пакете
`package.title`	string	да	—
`package.unlimited`	boolean	да	—
`package.validity_days`	integer	да	—
`package.voice_minutes`	integer	нет	Включённые минуты звонков, если они есть в пакете
`price_usd`	string	да	Сколько эта покупка резервирует / списала с вашего баланса, USD
`profile`	EsimProfileDTO	нет	Появляется, когда eSIM выпущена И покупка списана (operation_status succeeded)
`profile.activation_code`	string	да	Полная строка LPA (LPA:1$<SM-DP+>$<matching id>). Секрет: кто им владеет, тот может установить eSIM. Не пишите его в логи и не храните открытым текстом.
`profile.apn`	string	нет	—
`profile.iccid`	string	да	—
`profile.matching_id`	string	нет	—
`profile.qr_payload`	string	да	Строка для QR-кода установки (совпадает с activation_code). Картинку рисуете вы.
`profile.smdp_address`	string	нет	—
`refreshed`	boolean	нет	Только у usage-refresh. false: отдано сохранённое значение (обновляли меньше минуты назад или спрашивать провайдера пока не о чем)
`settled_at`	string	нет	—
`status`	string	да	processing \| active \| exhausted \| expired \| needs_review \| failed \| refunded
`usage`	EsimUsageDTO	нет	—
`usage.activated_at`	string	нет	—
`usage.data_remaining_gb`	string	нет	Последнее показание. Обновить — POST /esim/orders/{id}/usage-refresh.
`usage.data_total_gb`	string	нет	—
`usage.expires_at`	string	нет	—
`usage.unlimited`	boolean	да	—

Примеры ответа

{
  "id": "7e6d5c4b-3a29-4180-9f7e-6d5c4b3a2918",
  "operation_id": "c1d2e3f4-a5b6-4c7d-8e9f-0a1b2c3d4e5f",
  "external_id": "order-1001",
  "status": "active",
  "operation_status": "succeeded",
  "price_usd": "5.26",
  "package": {
    "id": "5b2f7c1a-3d4e-4f60-8a71-9c0d1e2f3a4b",
    "title": "Turkey · 5GB 30 days",
    "region_code": "TR",
    "region_name": "Turkey",
    "countries": [
      "TR"
    ],
    "data_gb": "5",
    "unlimited": false,
    "validity_days": 30,
    "network": "4G/5G",
    "has_5g": true
  },
  "profile": {
    "iccid": "8990011234567890123",
    "activation_code": "LPA:1$rsp.example.com$ABCD-1234",
    "smdp_address": "rsp.example.com",
    "matching_id": "ABCD-1234",
    "apn": "internet",
    "qr_payload": "LPA:1$rsp.example.com$ABCD-1234"
  },
  "usage": {
    "data_total_gb": "5",
    "data_remaining_gb": "3.5",
    "unlimited": false,
    "activated_at": "2026-10-07T09:13:41Z",
    "expires_at": "2026-11-06T09:13:41Z"
  },
  "created_at": "2026-10-07T09:13:02Z",
  "settled_at": "2026-10-07T09:13:45Z",
  "refreshed": true
}

Ошибки

HTTP	Код	Когда
404	`not_found`	Заказа нет или он принадлежит другому аккаунту.
429	`rate_limited`	Обновления потребления упираются в отдельный лимит ключа: не больше 30 в минуту (или ваш общий лимит, если он ниже).
502	`provider_unavailable`	Провайдер eSIM не ответил. Повторите позже.

Плюс общие ошибки подписи и лимитов — см. Ошибки.