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

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

За 10 минут вы:

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

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

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

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

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

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

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

Схематически токен выглядит так:

tn_live_aB3kP9qX_h7nZk2Xc1Yv4uG8wRsT5jLpM6oNqEi
        └─8 симв.┘ └────────── секрет ──────────┘

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

В дашборде: Webhooks → Rotate secret. Секрет формата whsec_… тоже показывается один раз — сохраните его. Он нужен для проверки подписи входящих вебхуков (см. 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",
    "info": "Подписка Pro, заказ #4811",
    "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",
        "info": "Подписка Pro, заказ #4811",
        "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",
        info: "Подписка Pro, заказ #4811",
        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);

Ответ 201 Created:

{
    "verification_id": "ver_01HXYZ4K9P2N3M8R7Q5S6T0V1W",
    "phone": "+79991234567",
    "dial_number": "+74951234567",
    "client_ref": "user-42",
    "info": "Подписка Pro, заказ #4811",
    "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. Звонок будет принят и сразу завершён — вешать трубку самому не обязательно. Важен сам факт звонка с правильного номера (Caller-ID).

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

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

{
    "type": "verification.completed",
    "verification_id": "ver_01HXYZ4K9P2N3M8R7Q5S6T0V1W",
    "phone": "+79991234567",
    "dial_number": "+74951234567",
    "client_ref": "user-42",
    "info": "Подписка Pro, заказ #4811",
    "completed_at": "2026-05-26T12:30:18+00:00",
    "caller_id": "+79991234567"
}

Заголовки:

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

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

Что дальше