non-voipnon-voip
Справочник API

API для мерчантов non-voip v1

Публичный клиентский API для интеграций сервер-сервер. Внутренние client и admin API сюда не входят.

Открыть Swagger UIУсловия использования

Базовый URL и аутентификация

Базовый URL

https://non-voip-api.0246864.xyz/api/v1

Используйте этот хост для всех запросов Merchant API.

Аутентификация

Все эндпоинты требуют API-ключ. Храните его на сервере и передавайте в заголовке каждого запроса.

X-Api-Key: YOUR_MERCHANT_API_KEY

Быстрый старт

  1. Создайте Merchant API-ключ в API Dashboard и храните его на сервере. Создание, ротация и использование ключа требуют активного тарифа merchant.
  2. Передавайте X-Api-Key с каждым запросом.
  3. Прочитайте каталог, затем создайте верификацию с его productServiceId и уникальным Idempotency-Key.
  4. Опрашивайте верификацию, пока в data.messages не появится код. Одноразовые SMS обычно переходят в completed, а не otp_received.
export NV_API_KEY='nvr_live_...'
API='https://non-voip-api.0246864.xyz/api/v1'

PRODUCT_SERVICE_ID=$(curl --fail-with-body --silent --show-error   "$API/catalog?test=true"   -H "X-Api-Key: $NV_API_KEY" | jq -r '.data[0].productServiceId')

VERIFICATION_ID=$(curl --fail-with-body --silent --show-error   -X POST "$API/verifications?test=true"   -H "X-Api-Key: $NV_API_KEY"   -H "Idempotency-Key: $(uuidgen)"   -H "Content-Type: application/json"   -d "{"productServiceId":"$PRODUCT_SERVICE_ID"}" | jq -r '.data.verificationId')

for _ in $(seq 20); do
  curl --fail-with-body --silent --show-error --max-time 15     "$API/verifications/$VERIFICATION_ID?test=true"     -H "X-Api-Key: $NV_API_KEY" | jq -e '.data.messages[0].code' && break
  sleep 5
done

Основы production-интеграции

Только на сервере

Храните API-ключи в backend или serverless-функциях. Не помещайте их в браузерный JavaScript или мобильные приложения.

Версионированные ответы

Все пути начинаются с /api/v1. Успешные данные находятся в data; при ошибках обрабатывайте HTTP-статус и код приложения.

Повторы и лимиты

Передавайте Idempotency-Key для записей и повторно используйте его при ретраях. Учитывайте заголовки X-RateLimit-* и Retry-After.

Тестовый режим (без реальных списаний)

Добавьте ?test=true для детерминированных данных production-формата без вызовов провайдера и списаний. Аутентификация, журналирование и лимиты запросов продолжают действовать.

Вебхуки

Настройте HTTPS URL и нужные события в API Dashboard. Доступны verification.created, verification.otp_received, verification.completed, verification.expired, verification.cancelled и verification.failed.

Коды одноразовых SMS приходят в verification.completed. Для multi-SMS перед завершением может приходить verification.otp_received. Здесь чаще всего ошибаются: подписавшись только на verification.otp_received, интеграция с одноразовыми SMS может не получить вообще ничего, поэтому всегда подписывайтесь и на verification.completed.

Проверяйте X-Webhook-Signature как HMAC-SHA256 в нижнем регистре от исходного тела и отвечайте 2xx за 10 секунд. Каждая доставка выполняется не более чем за 5 попыток с экспоненциальной задержкой — одна отправка и четыре повтора. Тело собирается заново на каждой попытке, поэтому timestamp и X-Webhook-Signature каждый раз разные; никогда не кэшируйте и не переиспользуйте подпись между попытками. А вот X-Webhook-Delivery остаётся неизменным, поэтому дубли следует устранять именно по нему.

Следите за доступностью эндпоинта. После 5 подряд доставок, исчерпавших все попытки, non-voip автоматически отключает вебхук и очищает URL, секрет подписи и подписку на события. Вы получите уведомление, но доставок больше не будет, пока вы заново не укажете URL в API Dashboard и не создадите новый секрет: длительный простой стоит вам самой конфигурации, а не только пропущенных событий.

Пример payload

{
  "event": "verification.completed",
  "timestamp": "2026-08-27T10:00:00.000Z",
  "balance": 124.5,
  "data": {
    "subscriptionId": "550e8400-e29b-41d4-a716-446655440000",
    "phoneNumber": "+15550001234",
    "otpCode": "483920",
    "messages": [
      {
        "code": "483920",
        "message": "Your verification code is 483920",
        "receivedAt": "2026-08-27T09:59:58.000Z"
      }
    ],
    "status": "completed",
    "productServiceId": "0f1a5a6c-1c2d-4f2b-9a1e-3c9d4b7e2f10"
  }
}

Merchant — Balance

Merchant — Catalog

Merchant — Verifications

Ресурсы

Панель API

Создавайте API-ключи и управляйте настройками webhook.

Swagger UI

Интерактивный справочник только публичного Merchant API v1; внутренние client и admin API исключены.

Поддержка

Нужна помощь с интеграцией? Напишите в поддержку: support@non-voip.com.