Обзор API¶

Base URL¶

https://app.truenum.ru/api/v1/

Все эндпоинты — над HTTPS. HTTP-вариант недоступен (любой запрос получает 301 Moved Permanently на https).

Версионирование¶

Текущая версия — v1. Все эндпоинты префиксируются /api/v1/. При выпуске несовместимых изменений будет введена /api/v2/; v1 останется работать как минимум 12 месяцев после анонса v2.

Совместимые изменения (новые опциональные поля в запросах и дополнительные поля в ответах) выкатываются в v1 без объявления новой версии. Ваш код должен игнорировать незнакомые поля в JSON.

Формат запроса¶

Content-Type: application/json; charset=utf-8
Тело — валидный JSON-объект
Все строки в UTF-8
Телефоны — в E.164 (с ведущим + и кодом страны), пример: +79991234567

Формат ответа¶

Content-Type: application/json
Тело — JSON-объект
Временные метки — ISO 8601 с таймзоной (+00:00 или Z)
ID верификаций — строка ver_<26 alphanumeric> (ULID)

Список публичных эндпоинтов:

Метод	Путь	Описание
`POST`	`/api/v1/verifications/`	Создать запрос на верификацию
`GET`	`/api/v1/verifications/{id}/`	Получить статус верификации

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

Все запросы публичного API требуют Bearer-токен:

Authorization: Bearer tn_live_<prefix>_<secret>

Подробнее: Аутентификация.

Интерактивная документация (Swagger UI)¶

Для разработки и отладки

Полная OpenAPI-схема и интерактивная Swagger UI с возможностью отправлять запросы «вживую» доступны по адресу:

https://app.truenum.ru/api/docs/

Авторизация — тем же Bearer-токеном. Сырая OpenAPI 3.0 JSON-схема: https://app.truenum.ru/api/schema/ (удобно для генерации SDK через openapi-generator).

Идемпотентность¶

POST /api/v1/verifications/ не идемпотентен — повторный одинаковый запрос создаст новую верификацию и заберёт новый DID. Используйте client_ref чтобы в своей системе сопоставить запрос с пользователем.

Часовые пояса¶

Все временные метки в ответах — UTC. На стороне клиента конвертируйте в нужную таймзону при отображении пользователю.