Контрольный список eSIM API (2026): 12 функций, которые обязательно должны быть в Travel eSIM API — и как протестировать каждую из них

Подключить eSIM API к вашему приложению, туристической платформе или системе бронирования несложно. Сложно — это обнаружить после запуска, что API дважды списывает средства при таймауте, не может сообщить вам, когда у клиента закончились данные, или не дает возможности протестировать ошибки.

Этот чек-лист охватывает 12 функций, которые важны в продакшене, и для каждой из них указано, как ее протестировать перед регистрацией. Мы используем TripoSIM Partner API в качестве рабочего примера, но вы можете использовать этот же чек-лист для сравнения любого провайдера.

1. Безопасная аутентификация по токену

Что искать: OAuth 2.0 client credentials: вы обмениваете client ID и secret на краткосрочный access token. Секреты никогда не передаются с каждым запросом.

Как протестировать: запросите токен, а затем проверьте, истекает ли его срок действия. В TripoSIM API запрос POST /auth/token возвращает access token, действительный в течение 15 минут. Убедитесь, что ваш код обновляет его автоматически до того, как он истечет.

2. Ключи идемпотентности (без двойных списаний)

Что искать: заголовок Idempotency-Key для каждого заказа и пополнения. Если ваш запрос завершается таймаутом и вы повторяете его с тем же ключом, API должен вернуть исходный результат вместо создания второй оплаченной eSIM.

Как протестировать: отправьте один и тот же заказ дважды с одним и тем же ключом и убедитесь, что вы получили один заказ. Затем отправьте тот же ключ с другим телом запроса — хороший API отклонит его. TripoSIM требует наличия ключа для рабочих заказов и пополнений и возвращает 409 IDEMPOTENCY_KEY_REUSED, если ключ используется повторно с другим запросом.

3. Котировки цен, фиксирующие стоимость

Что искать: способ получить цену и сохранить ее на короткое время, чтобы ваш клиент заплатил именно столько, сколько вы ему показали.

Как протестировать: создайте котировку, подождите, а затем сделайте заказ с ее использованием. Котировки TripoSIM действительны в течение 10 минут; истекшая котировка возвращает 409 QUOTE_EXPIRED, чтобы вы могли запросить новую цену вместо того, чтобы списывать неожиданную сумму.

4. Чистый фид каталога

Что искать: один эндпоинт, который перечисляет все тарифы с ценой, объемом данных, сроком действия, странами покрытия, поддержкой 5G, поддержкой пополнения — а для безлимитных тарифов — ежедневный лимит на полной скорости.

Как протестировать: загрузите каталог для одной страны и сравните его с собственным сайтом провайдера. Эндпоинт TripoSIM /catalog возвращает JSON или CSV, включает региональные тарифы, покрывающие страну, и добавляет поля fair-use (fup_daily_mb, fup_throttle_kbps) для безлимитных тарифов. Узнайте [как работают ежедневные безлимитные ограничения](/blog/unlimited-esim-daily-limit-by-country-2026).

5. Мгновенная доставка заказа и QR

Что искать: ответ на заказ (или вебхук через несколько секунд) должен включать код активации в стандартном формате LPA, например, LPA:1$smdp.example.com$ACTIVATION_CODE, чтобы вы могли показать QR-код или ссылку для установки в один тап.

Как протестировать: разместите заказ в песочнице, сгенерируйте QR из строки LPA и отсканируйте его камерой телефона, чтобы убедиться, что формат корректен.

6. Подписанные вебхуки для каждого события

Что искать: push-уведомления для всего жизненного цикла eSIM, подписанные так, чтобы злоумышленники не могли их подделать.

TripoSIM отправляет восемь типов событий: order.completed, order.failed, esim.activated, esim.usage_80, esim.suspended, esim.resumed, esim.depleted и esim.expired. Каждый запрос несет заголовок X-TripoSIM-Signature — HMAC-SHA256 от временной метки и сырого тела запроса с использованием вашего секретного ключа подписи:

<pre><code>// reject requests older than 5 minutes (replay protection) if (Math.floor(Date.now() / 1000) - parseInt(timestamp) &gt; 300) throw new Error('Webhook too old'); const expected = crypto .createHmac('sha256', signingSecret) .update(timestamp + '.' + rawBody) .digest('hex'); if (!crypto.timingSafeEqual(Buffer.from(signature), Buffer.from(expected))) { throw new Error('Invalid webhook signature'); }</code></pre>

Как протестировать: зарегистрируйте вебхук, инициируйте заказ и проверьте подпись в своем коде. Затем измените один байт в теле запроса и убедитесь, что ваша проверка отклоняет его.

7. Песочница, имитирующая всю жизнь eSIM

Что искать: реальным eSIM требуются дни для активации и использования данных. Хорошая песочница позволяет «перемотать» время вперед.

Как протестировать: в песочнице TripoSIM используйте POST /sandbox/esims/{iccid}/simulate с действиями activate, usage, deplete, expire или reset. Каждый шаг вызывает соответствующий вебхук, так что вы сможете протестировать ваше письмо «ваши данные почти закончились» за считанные минуты, а не дни.

8. Симуляция ошибок

Что искать: способ намеренно вызвать ошибки, чтобы вы знали, что ваше приложение умеет с ними справляться.

Как протестировать: отправьте заголовок X-Sandbox-Simulate с такими режимами, как insufficient_balance, price_changed, rate_limit, provider_unavailable или timeout, и проверьте, показывает ли ваше приложение четкое сообщение и делает ли повторные попытки только тогда, когда это нужно.

9. Пополнение той же самой eSIM

Что искать: клиенты, у которых закончились данные, должны иметь возможность добавить еще, не устанавливая новую eSIM.

Как протестировать: вызовите POST /esims/{iccid}/topup в песочнице (с ключом идемпотентности), а затем проверьте новый баланс данных. Также проверьте, какие тарифы поддерживают пополнение — об этом должен сообщить каталог.

10. Данные об использовании и статусе

Что искать: эндпоинт для получения данных об использованных данных, оставшихся данных и сроке действия, чтобы ваша служба поддержки и приложение могли ответить на вопрос «сколько данных у меня осталось?».

Как протестировать: вызовите GET /esims/{iccid}/usage после имитации события использования данных. TripoSIM кэширует использование в течение 5 минут, поэтому используйте вебхуки (esim.usage_80, esim.depleted) для уведомлений в реальном времени.

11. Приостановка и возобновление

Что искать: способ приостановить eSIM — например, когда платеж оспаривается или клиент сообщает об утере телефона — и возобновить ее позже.

Как протестировать: приостановите eSIM в песочнице, подтвердите получение вебхука esim.suspended, затем возобновите ее и подтвердите получение esim.resumed.

12. Четкие лимиты запросов, коды ошибок и журнал изменений

Что искать: документированные лимиты, коды ошибок, которые говорят вам, стоит ли повторять запрос, и публичный журнал изменений (changelog), чтобы обновления никогда не заставали вас врасплох.

Как протестировать: прочитайте список ошибок и сопоставьте каждый код с действием «повторить» или «не повторять» в вашем коде. TripoSIM позволяет делать 120 запросов в минуту на один партнерский аккаунт (вы можете установить более низкие лимиты для отдельных API-ключей), возвращает заголовок Retry-After при ответах 429, помечает каждый код ошибки как допускающий повтор или нет и публикует эндпоинт с журналом изменений.

Простой план запуска

1. День 1: получите ключи для песочницы, пройдите аутентификацию, загрузите каталог.
2. День 2: разместите заказы в песочнице с ключами идемпотентности и отобразите QR-коды.
3. День 3: добавьте вебхуки, запустите симуляторы жизненного цикла и ошибок.
4. День 4: добавьте пополнение и использование данных, затем протестируйте на реальном телефоне с одной живой eSIM.
5. День 5: выходите в продакшен.

Большинство команд подключаются менее чем за неделю. Читайте полную [документацию API](https://docs.triposim.com) или смотрите наше пошаговое [руководство по интеграции eSIM API](/blog/esim-reseller-api-how-to-integrate-travel-esim-sales-into-your-platform).

Часто задаваемые вопросы

Что должен включать в себя travel eSIM API?

Как минимум: аутентификацию по токену, ключи идемпотентности, котировки цен, фид каталога, мгновенные QR/коды активации, подписанные вебхуки, песочницу с симуляторами жизненного цикла и ошибок, пополнение баланса, данные об использовании, приостановку/возобновление, а также документированные лимиты запросов и коды ошибок.

Почему ключи идемпотентности важны для eSIM API?

Каждый заказ eSIM стоит реальных денег. Если запрос завершается таймаутом и ваша система повторяет его, ключ идемпотентности гарантирует, что повторная попытка вернет первый результат, а не купит вторую eSIM.

Как протестировать eSIM API, не покупая eSIM?

Используйте песочницу. Хорошая песочница имитирует заказы, активацию, использование данных, исчерпание и истечение срока действия — а также позволяет принудительно вызывать ошибки — не списывая деньги с вашего кошелька.

Сколько времени занимает интеграция eSIM API?

При наличии хорошо документированного API и полноценной песочницы большинство команд выходят в продакшен за 3–5 рабочих дней.

Поддерживает ли TripoSIM API доставку white-label?

Да. Вы получаете код активации и данные QR, поэтому вы можете предоставлять eSIM внутри своего собственного приложения или в письмах под своим брендом. См. [API program](/api-program).

Итог

Цена имеет значение, но для eSIM API реальная разница проявляется после запуска: повторные попытки, которые никогда не ведут к двойному списанию, вебхуки, которым можно доверять, и песочница, которая позволяет протестировать все заранее. Проверьте любого провайдера по этому чек-листу, прежде чем принимать решение — и [начните с нашей песочницы](/api-program), чтобы увидеть, как справляется TripoSIM Partner API.