Документация Open API
Open API доступен партнёрам и участникам, которым администратор предоставил доступ. Ваша система обращается к /v1 для просмотра каталога, создания и чтения заказов, получения профилей eSIM (ICCID + коды установки LPA), проверки расхода трафика и сверки через периодические REST-запросы. Оплата списывается с кошелька владельца ключа: организации или участника. Вебхуки предназначены для организаций; цены и счета-фактуры участников следуют процессу, описанному в разделе OpenAPI для участников руководства по интеграции.
Возможности API
Количество операций: 30
Групп: 6; Каталог · Заказы · eSIM · Кошелёк · Вебхуки · Тестовый режим.
Единая аутентификация
HMAC-SHA256 с 4 заголовками X-TKE-* даже для GET-запросов. Нельзя пропустить подпись или передать секрет ключа в заголовке.
Единый формат ответа
{ ok, data } или { ok, error } с соответствующим HTTP-статусом. Ошибки никогда не возвращаются со статусом 200.
Опубликованных кодов ошибок: 91
У каждого кода есть HTTP-статус и явный признак возможности повтора из серверного реестра.
Событий вебхуков: 8
Настройка через POST /v1/webhooks, отдельные секреты подписи, доставка как минимум один раз и полный журнал для переотправки.
Тестовый режим на отдельном хосте
Хост api-testing.tongkhoesim.com принимает только ключи tke_test_: виртуальные кошелёк и запас, детерминированная выдача тестовых eSIM и автоматический расход данных. Для работы с реальными данными смените хост и ключ на tke_live_, код менять не нужно.
text
https://api.tongkhoesim.com/v1 # Рабочий режим
https://api-testing.tongkhoesim.com/v1 # Тестовый режимРабочее окружение: api.tongkhoesim.com / tke_live_ (партнёры) или tke_member_live_ (одобренные участники). Тестовое: api-testing.tongkhoesim.com / tke_test_ / tke_member_test_ (партнёры / участники).
Начало работы: 4 шага
1. Создайте тестовый ключ
В разделе «Тестовый режим» панели партнёра создайте ключ с префиксом tke_test_. Секрет показывается один раз: сразу сохраните его в безопасном месте. Первый тестовый ключ организации автоматически создаёт примеры данных (3 заказа в 3 состояниях). Тестовый кошелёк можно пополнять без ограничений.
2. Создайте заказ на тестовом хосте
Подпишите запрос HMAC и вызовите POST https://api-testing.tongkhoesim.com/v1/orders. Тестовый хост сразу выдаст тестовые eSIM (ICCID начинается с 8999), не затрагивая реальные запас и средства. Попробуйте в браузере или скачайте коллекцию Postman.
3. Зарегистрируйте вебхук и вызовите тестовые события
Вызовите POST /v1/webhooks с вашим URL (при создании обработчик должен ответить 2xx на CHECK_HEALTH). Затем вызовите POST /v1/testmode/webhooks/fire для тестового события или POST /v1/testmode/webhooks/fail-next для проверки повторов.
4. Перейдите на рабочий ключ
Создайте ключ с префиксом tke_live_, сохранив тот же код, смените хост (api-testing → api), key_id и secret. Отдельно зарегистрируйте вебхуки для рабочего ключа: настройки изолированы по api_key_id.
Важные особенности интеграции: 3
Изучите эти три особенности до начала разработки. Ошибки могут проявиться только при списании реальных денег или сверке данных, даже если код работает и тесты проходят.
Idempotency-Key действует в пределах API-ключа
Защита от повторов ограничена одним api_key_id. Один Idempotency-Key с двумя разными ключами, даже одной организации, означает две команды: два заказа и два списания. Используйте постоянный ключ в процессе заказа или включайте в него key_id.
В REST поле называется id, а в вебхуках — order_item_id
В REST (/v1/esims и items[] заказа) собственный ключ eSIM — id; order_id лишь ссылается на родительский заказ. Вебхуки order.completed и esim.delivered передают тот же UUID в order_item_id. Сопоставляйте значения, не предполагая одинаковые имена полей. Храните и ищите eSIM по id/order_item_id, никогда по ICCID: оператор может повторно использовать ICCID, а этот идентификатор уникален и постоянен. Если известен только ICCID, вызовите GET /v1/esims?iccid=… для получения id. Передайте external_ref при заказе для связи с вашей системой: он возвращается в каждом блоке eSIM REST и каждом вебхуке eSIM вместе с order_id. GET /v1/esims?external_ref=… вернёт все eSIM заказа.
Правильно завершайте курсорную пагинацию
GET /v1/orders и GET /v1/esims используют курсорную пагинацию. Неверный курсор не вызывает ошибку: сервер возвращается к началу. Проверка только next_cursor !== null создаёт бесконечный цикл. Завершайте обход, если next_cursor отсутствует или равен текущему курсору.
Следующие шаги
Готовые примеры, коллекция Postman, набор .http и создание собственного клиента из openapi.json.
Точная каноническая формула подписи и серверные тестовые векторы для проверки реализации.
Все методы: параметры, схемы, варианты ответов и готовые примеры вызовов.
Каталог событий, проверка подписи, интервалы повторов и сверка через запросы.