Перейти к содержанию

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

За 10 минут вы:

  1. Зарегистрируете аккаунт.
  2. Создадите API-ключ.
  3. Сделаете тестовую верификацию и получите webhook.

1. Регистрация

Откройте https://app.truenum.ru/signup, заполните email и пароль. После регистрации войдите в дашборд и подтвердите email (ссылка приходит на почту).

2. Создание API-ключа

В дашборде: Keys → New key → задайте метку (например, dev-laptop).

Секрет показывается один раз

Полный токен формата tn_live_<8 символов префикса>_<секрет> отображается только в момент создания. Сохраните его в менеджере паролей или env vars. Повторно получить нельзя — только создать новый ключ и удалить старый.

Пример валидного токена (схематически):

tn_live_aB3kP9qX_h7nZk2Xc1Yv4uG8wRsT5jLpM6oNqEi
        └─8 chars┘ └────── секрет (≥32 chars) ──────┘

3. Получение webhook secret

В дашборде: Webhooks → Rotate secret. Аналогично API-ключу секрет показывается один раз. Сохраните.

Этот секрет нужен для верификации подписи входящих webhook-уведомлений (см. Webhooks: подпись).

4. Подготовка webhook-приёмника

Для тестов проще всего использовать https://webhook.site — она выдаст вам уникальный URL и покажет входящие запросы в реальном времени.

В продакшене: ваш эндпоинт должен принимать POST с JSON-телом и возвращать 2xx в течение 10 секунд. Подробнее — Webhooks: обзор.

5. Создание верификации

curl -X POST https://app.truenum.ru/api/v1/verifications/ \
  -H 'Authorization: Bearer tn_live_<prefix>_<secret>' \
  -H 'Content-Type: application/json' \
  -d '{
    "phone": "+79991234567",
    "webhook_url": "https://webhook.site/<your-uuid>",
    "client_ref": "user-42",
    "ttl_seconds": 300
  }'

import requests

resp = requests.post(
    "https://app.truenum.ru/api/v1/verifications/",
    headers={"Authorization": "Bearer tn_live_<prefix>_<secret>"},
    json={
        "phone": "+79991234567",
        "webhook_url": "https://webhook.site/<your-uuid>",
        "client_ref": "user-42",
        "ttl_seconds": 300,
    },
    timeout=10,
)
resp.raise_for_status()
data = resp.json()
print(data["dial_number"], data["expires_at"])

const resp = await fetch("https://app.truenum.ru/api/v1/verifications/", {
    method: "POST",
    headers: {
        "Authorization": "Bearer tn_live_<prefix>_<secret>",
        "Content-Type": "application/json",
    },
    body: JSON.stringify({
        phone: "+79991234567",
        webhook_url: "https://webhook.site/<your-uuid>",
        client_ref: "user-42",
        ttl_seconds: 300,
    }),
});
if (!resp.ok) throw new Error(`HTTP ${resp.status}`);
const data = await resp.json();
console.log(data.dial_number, data.expires_at);

Ответ:

{
    "verification_id": "ver_01HXYZABC...",
    "phone": "+79991234567",
    "dial_number": "+74951234567",
    "client_ref": "user-42",
    "status": "pending",
    "ttl_seconds": 300,
    "created_at": "2026-05-26T12:30:00+00:00",
    "expires_at": "2026-05-26T12:35:00+00:00",
    "completed_at": null,
    "caller_id_received": ""
}

6. Совершите звонок

С телефона, номер которого вы передали в phone, позвоните на возвращённый dial_number. Телефон коротко прозвонит — мы ответим SIP-кодом 486 Busy Here, и звонок прервётся. Это нормально.

7. Получение webhook

Через 1–2 секунды на ваш webhook_url придёт POST:

{
    "type": "verification.completed",
    "verification_id": "ver_01HXYZABC...",
    "phone": "+79991234567",
    "dial_number": "+74951234567",
    "client_ref": "user-42",
    "caller_id": "+79991234567",
    "completed_at": "2026-05-26T12:30:18+00:00"
}

В HTTP-заголовках:

X-Truenum-Signature: t=1748255418,v1=<hex_sha256>
User-Agent: TrueNum/1.0
Content-Type: application/json

Проверьте, что caller_id совпадает с phone — это и есть факт верификации. Подпись X-Truenum-Signature обязательно проверяйте в продакшене: инструкция.

Что дальше

  • API: верификации — все поля запроса/ответа, опциональные параметры, статусы.
  • Webhooks: подпись — примеры верификации на Python, Node, Go, PHP.
  • Ошибки — каталог HTTP-кодов и тел ответов.
  • Лимиты — 120 req/min на ключ, заголовки ответа.