API Hopsim — документация

Авторизация

Ключ — в кабинете «Мои eSIM» → «Бизнес». Передавайте его в заголовке. Тестовый ключ (hs_test_…) делает заказы-заглушки: денег не списывает, eSIM не настоящие, ответы в том же формате. Боевой (hs_live_…) — после первого пополнения баланса. В кабинете можно ограничить доступ по IP.

curl https://hopsim.co/api/partner/v1/balance \
  -H "Authorization: Bearer hs_test_…"

Каталог и цены

Все доступные тарифы с вашей оптовой ценой. Фильтр по направлению: ISO-код страны (TR) или регион (europe, global). Каталог обновляется раз в сутки — кешируйте его у себя и обновляйте раз в день.

GET https://hopsim.co/api/partner/v1/catalog?destination=TR

{
  "currency": "USD",
  "plans": [
    {
      "id": "019c9954-5125-7209-a8f4-5cbdf017da17",
      "destination": { "key": "TR", "type": "country", "name": "Turkey", "countries": ["TR"] },
      "dataGb": 1, "unlimited": false, "dailyHighSpeedGb": null, "throttleKbps": null,
      "days": 3, "validityStarts": "first_use", "topupAvailable": true,
      "priceUsd": 1.33
    }
  ]
}

Заказ eSIM

Списывает priceUsd × quantity с баланса и выдаёт eSIM. Обычно ответ сразу со статусом ready и данными для установки; если выдача задерживается — 202 и статус processing: опросите GET /orders/{id} или дождитесь вебхука. externalId — ваш номер заказа: повтор запроса с тем же externalId вернёт тот же заказ, а не создаст второй. email — если указать, пришлём покупателю письмо с eSIM.

POST https://hopsim.co/api/partner/v1/orders
Content-Type: application/json

{ "planId": "019c9954-5125-7209-a8f4-5cbdf017da17", "quantity": 1,
  "externalId": "your-order-1042", "email": "client@mail.com" }

200 OK
{
  "id": "4uUCx29G3UQ8", "externalId": "your-order-1042", "status": "ready", "test": false,
  "planId": "019c9954-…", "destination": "TR", "quantity": 1,
  "unitPriceUsd": 1.33, "totalUsd": 1.33, "sentTo": "client@mail.com",
  "esims": [{
    "iccid": "8901…", "status": "ready",
    "installUrl": "https://esimsetup.apple.com/esim_qrcode_provisioning?carddata=LPA:1$…",
    "lpa": "LPA:1$smdp.example$ACTIVATION-CODE",
    "smdpAddress": "smdp.example", "activationCode": "ACTIVATION-CODE",
    "dataTotalGb": 1, "dataLeftGb": null, "expiresAt": null
  }]
}

Статус заказа

Добавьте ?qr=1, чтобы получить QR-код картинкой (data:image/png). installUrl — установка в одно касание на iPhone (iOS 17.4+); для Android — QR из lpa или ручной ввод smdpAddress и activationCode.

GET https://hopsim.co/api/partner/v1/orders/4uUCx29G3UQ8?qr=1

Список заказов

GET https://hopsim.co/api/partner/v1/orders?limit=20&before=4uUCx29G3UQ8

{ "orders": [ … ], "next": "Zx81…" }

Баланс

GET https://hopsim.co/api/partner/v1/balance

{ "mode": "live", "balanceUsd": 118.42, "liveEnabled": true }

Вебхуки

Укажите https-адрес в кабинете — пришлём POST при событиях order.fulfilled (eSIM выдана, в data — заказ целиком) и balance.topped_up. Подпись — HMAC SHA-256 тела запроса вашим секретом, в заголовке X-Hopsim-Signature. Если ваш сервер не ответил 2xx, повторим несколько раз с паузами.

POST https://your-site.com/hopsim-webhook
X-Hopsim-Event: order.fulfilled
X-Hopsim-Signature: sha256=5d41402abc4b2a76…

{ "event": "order.fulfilled", "createdAt": "2026-10-13T12:00:00Z", "data": { …order… } }

// Node.js — проверка подписи / signature check
const crypto = require("crypto");
const ok = req.headers["x-hopsim-signature"] ===
  "sha256=" + crypto.createHmac("sha256", process.env.HOPSIM_WEBHOOK_SECRET).update(rawBody).digest("hex");

Ошибки

409 Conflict
{ "error": "insufficient_balance" }

Пополнение баланса — в USDT (TRC20) в кабинете, от $10. Возврат за невыданную eSIM приходит на баланс автоматически.