Tổng Kho eSIM
Тестирование

Тестовый режим

Используйте ключи партнёров tke_test_ или участников tke_member_test_ на api-testing.tongkhoesim.com. Виртуальные средства и имитация eSIM изолированы от реальных денег, склада и счетов. Доступные операции зависят от владельца ключа; ограничения массовых заказов, вебхуков и рассмотрения возврата указаны в руководстве участника.

Проверьте полный процесс до работы с реальными средствами. Смотрите Подпись HMAC для формул аутентификации и Консоль API для отправки тестовых запросов из браузера.

OpenAPI для участников

Администратор открывает OpenAPI для каждого участника. В основном боковом меню откройте «Ключи API», выберите рабочий или тестовый режим и создайте ключ. Секрет показывается один раз. Лимит ключей общий для двух режимов. Отключение доступа блокирует оба режима, но ключи можно отозвать.

Рабочий режим использует реальный кошелёк участника в VND без кредита. Тест использует отдельный виртуальный кошелёк и имитацию eSIM. На тестовой странице можно пополнить баланс, создать или сбросить примеры. Тестовые заказы не попадают в историю реальных покупок.

Массовые заказы и вебхуки для участников не поддерживаются в обоих режимах. Заявки на рассмотрение возврата доступны только в рабочем режиме; отмените тестовую eSIM, чтобы проверить возврат в виртуальный кошелёк. Тест не вызывает реального провайдера и не выпускает реальные счета MISA. Неподдерживаемые операции возвращают capability.not_supported.

Эндпоинты API участников

Два хоста для двух типов ключей

Используйте хост, соответствующий типу ключа. Неверный хост отклоняется при аутентификации до выполнения бизнес-логики.

ХостБазовый URLДопустимые ключи
Рабочий режимhttps://api.tongkhoesim.com/v1tke_live_ / tke_member_live_
Тестовый режимhttps://api-testing.tongkhoesim.com/v1tke_test_ / tke_member_test_

Создание тестового ключа

В разделе «Тестовый режим» панели партнёра создайте ключ tke_test_. Секрет показывается один раз: сразу сохраните его. ПЕРВЫЙ тестовый ключ организации автоматически создаёт примеры данных через POST /v1/testmode/seed без дополнительного шага.

7 отличий рабочего и тестового режимов

АспектРабочий (хост api, tke_live_)Тестовый (хост api-testing, tke_test_)
Хостapi.tongkhoesim.comapi-testing.tongkhoesim.com — неверный хост возвращает 403
КошелёкРеальный кошелёк организацииОтдельный виртуальный кошелёк с неограниченным пополнением через панель или администратором
ЗапасРеальные esim_profilesВиртуальный запас, неограниченная выдача тестовых eSIM
ВыдачаРеальные поставщики связиДетерминированная имитация: одинаковые данные дают одинаковые ICCID/LPA (LPA:1$testmode-smdp.tongkhoesim.com$…)
Расход данныхИзмеряется операторомАвтоматический рост каждые несколько минут с уведомлениями на 75/90%
ВебхукиРеальные рабочие событияСобытия тестового режима, ручная отправка и принудительные ошибки fail-next
Реестр проводокРеальный финансовый реестрИзолированный виртуальный реестр, только добавление, без удаления и смешивания с рабочим
POST

/v1/testmode/seed

POST /v1/testmode/seed создаёт готовый набор для первых запросов без ручного оформления заказов. Идемпотентен в пределах организации: повтор не создаёт дубли и возвращает already_seeded: true.

  • Тестовый кошелёк с достаточным балансом
  • 3 заказа по 1 eSIM из 3 реальных тарифов с ценами организации
  • 3 состояния: не установлена · работает, использовано 40% · срок истёк
bash
#!/usr/bin/env bash
# Requires: bash + openssl + uuidgen.

KEY_ID="tke_test_REPLACE_WITH_YOUR_KEY_ID"
SECRET="REPLACE_WITH_YOUR_SECRET"

METHOD="POST"
REQ_PATH="/v1/testmode/seed"
BODY='{}'

TS="$(date +%s000)"                 # epoch milliseconds
NONCE="$(uuidgen)"
BODY_HASH="$(printf '%s' "$BODY" | openssl dgst -sha256 -hex | awk '{print $NF}')"
SIGNING="$METHOD"$'\n'"$REQ_PATH"$'\n'"$TS"$'\n'"$NONCE"$'\n'"$BODY_HASH"
SIG="$(printf '%s' "$SIGNING" | openssl dgst -sha256 -hmac "$SECRET" -hex | awk '{print $NF}')"

curl -sS -X "$METHOD" "https://api-testing.tongkhoesim.com$REQ_PATH" \
  -H "X-TKE-Key: $KEY_ID" \
  -H "X-TKE-Timestamp: $TS" \
  -H "X-TKE-Nonce: $NONCE" \
  -H "X-TKE-Signature: $SIG" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  --data-raw "$BODY"
json
{
  "ok": true,
  "data": {
    "seeded": true,
    "already_seeded": false,
    "orders_created": 3,
    "esims_created": 3
  }
}

Автоматический расход данных

У включённых тестовых eSIM расход растёт циклически (по умолчанию каждые 5 минут) до исчерпания данных или срока. На 75% и 90% отправляются esim.usage_threshold. Это имитирует активного абонента без ручных вызовов simulate. GET /v1/testmode/status показывает состояние функции и интервал.

Методы /v1/testmode/*

Доступны только на api-testing.tongkhoesim.com с ключом tke_test_. Псевдонимов по старым путям нет.

МетодПутьНазначение
GET/v1/testmode/statusГотовность, проверки, число тестовых ключей/заказов/eSIM, кошелёк, вебхуки и автоматический расход
POST/v1/testmode/seedСоздание примеров данных (идемпотентно для организации)
POST/v1/testmode/resetМягкое удаление тестовых заказов/eSIM и обнуление кошелька компенсирующей проводкой
POST/v1/testmode/esims/{order_item_id}/simulateСимуляция расхода, состояния, истечения срока, ограничения скорости или отказа следующего вызова поставщика
POST/v1/testmode/webhooks/fireНемедленная отправка примера события ({event_type}) на URL вебхука тестового ключа
POST/v1/testmode/webhooks/fail-nextПринудительная ошибка 503 для следующих N доставок, чтобы проверить повторы
Источники изменения состояния (via)
viaКогда используетсяЗначение ref_id
open_apiПрямой вызов /v1 с тестовым ключом: оформление, пополнение, отмена или симуляцияapi_keys.id ключа запроса
simulateЗапуск симулятора панели участником организации или администратором от его имениID пользователя или администратора
seedСоздание примеров через /v1/testmode/seed без ручного заказаПусто
POST

/v1/testmode/esims/{id}/simulate

test-mode-only

POST /v1/testmode/esims/{order_item_id}/simulate имитирует изменения eSIM: задаёт расход и состояние, завершает срок сейчас или в заданное время, ограничивает скорость либо однократно отклоняет следующее пополнение/отмену через тестового поставщика.

bash
#!/usr/bin/env bash
KEY_ID="tke_test_REPLACE_WITH_YOUR_KEY_ID"
SECRET="REPLACE_WITH_YOUR_SECRET"
ORDER_ITEM_ID="REPLACE_WITH_ORDER_ITEM_ID"

METHOD="POST"
REQ_PATH="/v1/testmode/esims/$ORDER_ITEM_ID/simulate"
BODY='{"data_used_mb":4096,"status":"enabled"}'

TS="$(date +%s000)"
NONCE="$(uuidgen)"
BODY_HASH="$(printf '%s' "$BODY" | openssl dgst -sha256 -hex | awk '{print $NF}')"
SIGNING="$METHOD"$'\n'"$REQ_PATH"$'\n'"$TS"$'\n'"$NONCE"$'\n'"$BODY_HASH"
SIG="$(printf '%s' "$SIGNING" | openssl dgst -sha256 -hmac "$SECRET" -hex | awk '{print $NF}')"

curl -sS -X "$METHOD" "https://api-testing.tongkhoesim.com$REQ_PATH" \
  -H "X-TKE-Key: $KEY_ID" \
  -H "X-TKE-Timestamp: $TS" \
  -H "X-TKE-Nonce: $NONCE" \
  -H "X-TKE-Signature: $SIG" \
  -H "Content-Type: application/json" \
  --data-raw "$BODY"
# No Idempotency-Key required: state mutation is intrinsically idempotent.
json
{
  "ok": true,
  "data": {
    "order_item_id": "018f2b00-0000-7000-8000-000000000001",
    "esim_state": "enabled",
    "running_package_code": "TKE-VN-30D-X3K9F",
    "running_started_at": "2026-07-11T07:00:00Z",
    "running_expires_at": "2026-08-10T07:00:00Z",
    "data_bytes": 5368709120,
    "used_bytes": 4294967296,
    "remaining_bytes": 1073741824,
    "throttled": false,
    "via": "simulate",
    "last_via": "simulate",
    "mode": "test",
    "updated_at": "2026-07-11T09:15:00Z"
  }
}

Ошибки тестового режима

Код ошибкиHTTPПричина и решение
testmode.live_key_forbidden403Вызов /v1/testmode/* с рабочим ключом. Используйте тестовый ключ tke_test_ той же организации
testmode.invalid_scenario422Пустое тело, нет полей или status вне released/installed/enabled/disabled
testmode.not_test_item422order_item_id не относится к тестовому заказу: симуляция рабочих данных запрещена
testmode.no_sellable_package422У организации нет тарифа с ценой для создания примеров. Ключ создаётся, но примеры не создаются
partner.wrong_host403Тестовый ключ использован на рабочем хосте или наоборот. Перейдите на хост, указанный в теле ошибки

Полный каталог — на странице кодов ошибок . Стандартная /v1 аутентификация выполняется до логики тестового режима.

Тестовые вебхуки: отправка и fail-next

POST /v1/testmode/webhooks/fire сразу отправляет тестовое событие на URL вебхука тестового ключа без реального заказа. Тело: { "event_type": "order.completed", "data": {...} }. Если опустить data, система создаст пример сама.

POST /v1/testmode/webhooks/fail-next { "count": 1 } вызывает тестовую ошибку 503 у следующих N доставок, затем отключается. Проверьте повторы, не останавливая реальный обработчик.