Tổng Kho eSIM
Самостоятельная интеграция

Самостоятельная интеграция

Устанавливать официальный пакет не требуется. Материалы ниже помогут правильно подписать запрос, запустить пример и выполнить тест из готовой коллекции ещё до написания собственного кода.

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

Интеграция напрямую через аккаунт участника без создания организации или профиля вьетнамского юридического лица.

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

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

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

Счета-фактуры следуют процессу участника: по умолчанию продажа потребителю. При создании заказа можно передать invoice_buyer с корректными данными физического лица по действующим правилам проверки. Для доступа к OpenAPI профиль вьетнамского юридического лица не требуется.

Аутентификация и защита от повторных операций

Рабочий режим: https://api.tongkhoesim.com и tke_member_live_. Тест: https://api-testing.tongkhoesim.com и tke_member_test_. Оба используют HMAC-SHA256 и X-TKE-Key, X-TKE-Timestamp, X-TKE-Nonce, X-TKE-Signature. Подписывайте точный метод, путь/параметры и хеш исходного тела; не помещайте секрет в код браузера.

POST создания заказов, смены тарифа, отмены и запросов возврата требуют Idempotency-Key. При повторе одного намерения сохраняйте ключ и тело. Защита от дублей действует в пределах ключа API, поэтому не меняйте ключ API для повтора ожидающей операции. Для создания примеров и сброса тестовых данных участника также нужен Idempotency-Key; reset должен содержать тело {reason}.

Добавьте lpa в include для получения кодов установки; обычное окно отмены закрывается, когда коды действительно возвращены. qr лишь добавляет QR-изображение вместе с lpa и игнорируется в методах списка. Запрашивайте коды только перед передачей клиенту; иначе опускайте include. Запросы возврата по-прежнему подчиняются бизнес-условиям и не дают свободной отмены после раскрытия кодов.

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

Путь API: GET /v1/catalog/packages
Необходимое право: catalog:read
Путь API: GET /v1/catalog/packages/{code}
Необходимое право: catalog:read
Путь API: GET /v1/orders
Необходимое право: orders:read
Путь API: POST /v1/orders
Необходимое право: orders:write
Путь API: GET /v1/orders/{id}
Необходимое право: orders:read
Путь API: POST /v1/orders/{id}/resend
Необходимое право: orders:write
Путь API: GET /v1/esims
Необходимое право: esims:read
Путь API: GET /v1/esims/{id}
Необходимое право: esims:read
Путь API: GET /v1/esims/{id}/usage
Необходимое право: esims:read
Путь API: GET /v1/esims/{id}/plan-options
Необходимое право: esims:read
Путь API: POST /v1/esims/{id}/change-plan
Необходимое право: esims:write
Путь API: POST /v1/esims/{id}/cancel
Необходимое право: esims:write
Путь API: GET /v1/esims/{id}/refund-requests
Необходимое право: esims:read
Путь API: POST /v1/esims/{id}/refund-requests
Необходимое право: esims:write
Путь API: GET /v1/wallet/balance
Необходимое право: wallet:read

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

GET /v1/testmode/status
esims:read
POST /v1/testmode/seed
orders:write
POST /v1/testmode/reset
orders:write
POST /v1/testmode/esims/{id}/simulate
esims:write

Консоль принимает тестовые ключи партнёров tke_test_ и участников tke_member_test_ только на api-testing. Все рабочие ключи блокируются. Секрет хранится лишь в памяти страницы, не сохраняется в хранилище или журналах.

Подпись запросов

Полная формула HMAC-SHA256, примеры на 5 языках (bash/Node/Python/PHP/Go) и серверные тестовые векторы находятся на странице подписи HMAC.

bash
#!/usr/bin/env bash
# Yeu cau: openssl. Ky POST /v1/orders.
KEY_ID="tke_test_ab12cd34..."
SECRET="tke_secret_test_0123456789abcdef"
METHOD="POST"
PATH_Q="/v1/orders"
BODY='{"items":[{"package_code":"THAY-BANG-MA-GOI-CUA-BAN","quantity":2}]}'
TS="$(date +%s000)"                 # epoch milliseconds
NONCE="$(uuidgen)"

BODY_HASH="$(printf '%s' "$BODY" | openssl dgst -sha256 -hex | awk '{print $NF}')"
SIGNING="$METHOD"$'
'"$PATH_Q"$'
'"$TS"$'
'"$NONCE"$'
'"$BODY_HASH"
SIG="$(printf '%s' "$SIGNING" | openssl dgst -sha256 -hmac "$SECRET" -hex | awk '{print $NF}')"

curl -sS "https://api.tongkhoesim.com$PATH_Q"   -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"

Готовые файлы примеров

Два файла в корне репозитория (examples/sign.mjs, examples/sign.py) запускаются стандартной средой языка без установки пакетов. Оба читают /hmac-test-vectors.json, вычисляют подпись каждого вектора, сравнивают с ожидаемым результатом и выводят PASS/FAIL.

bash
node examples/sign.mjs      # стандартный Node (node:crypto), без установки пакетов
python examples/sign.py     # стандартный Python (hmac/hashlib), без установки пакетов

Готовые коллекции запросов

При сборке из openapi.json создаются две коллекции: для Postman и редакторов с поддержкой .http (VS Code REST Client, JetBrains HTTP Client). По одному запросу на метод с 4 заголовками подписи: добавьте свой ключ и вычислите подпись.

Скачать коллекцию Postman Скачать tongkhoesim.http
Использование коллекции .http
  1. Откройте tongkhoesim.http в VS Code (расширение REST Client) или JetBrains HTTP Client.
  2. Укажите @key_id и @secret вашего ключа tke_test_ в начале файла. @base_url уже указывает на api-testing.tongkhoesim.com.
  3. Вычислите timestamp/nonce/signature по примерам страницы HMAC или через examples/sign.* и вставьте в соответствующие переменные.
  4. Отправляйте запросы прямо из редактора без Postman и дополнительного кода.

Нужен SDK?

Создайте клиент из openapi.json с openapi-generator — автоматически созданный клиент соответствует спецификации:

bash
npx @openapitools/openapi-generator-cli generate \
  -i https://docs.tongkhoesim.com/openapi.json \
  -g typescript-fetch \
  -o ./tke-sdk