Перейти к основному содержимому

Проверка возраста

Полный поток интеграции см. в Обзор API.

Эндпоинт​

ОкружениеURL
ProductionPOST https://api.id.unico.app/processes/v1
SandboxPOST https://api.id.uat.unico.app/processes/v1

Запрос​

Заголовки
ЗаголовокЗначение
AuthorizationBearer <access_token> (см. Аутентификация)
APIKEYПредоставленный API-ключ -- должен иметь включённые возможности проверки возраста.
Content-Typeapplication/json
Параметры тела запроса
ПолеТипОбязательныйОписание
subjectobjectдаКонтейнер информации о пользователе.
subject.codestringусловноCPF (BR) или CURP (MX), без форматирования. Обязателен, когда поток включает проверку живости или проверку личности (см. Возможность «Проверка возраста»); не требуется для потоков, ограниченных только проверкой возраста.
subject.namestringнетПолное имя пользователя.
subject.genderstringнетM для мужского или F для женского пола.
subject.birthDatestring (ISO 8601)нетДата рождения (YYYY-MM-DD).
subject.emailstringнетАдрес электронной почты пользователя.
subject.phonestringнетНомер телефона: код страны + код региона + номер, без разделителей (например, 5519725570707).
useCasestringнетИдентификатор варианта использования операции.
subsidiaryIdstringнетID филиала -- обязателен только при наличии нескольких филиалов.
imageBase64stringдаЗашифрованный вывод SDK или base64-изображение (PNG, JPEG, WebP).
Требования к изображению
  • Минимальное разрешение: 640 x 480 (стандарт HD)
  • Максимальный размер файла: 800 КБ (рекомендуется сжатие JPEG92)
  • JWT-токены из SDK истекают через 10 минут и могут быть использованы только один раз

Пример​

curl -X POST https://api.id.unico.app/processes/v1 \
  -H "Authorization: Bearer $TOKEN" \
  -H "APIKEY: $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "subject": {
      "code": "12345678909",
      "name": "Luke Skywalker",
      "birthDate": "2000-05-20",
      "email": "[email protected]",
      "phone": "5519725570707"
    },
    "useCase": "AgeVerification",
    "imageBase64": "/9j/4AAQSkZJR..."
  }'

Ответы​

200 OK

Возвращаемые поля ответа зависят от того, какие возможности включены для вашего APIKEY.

Только проверка возраста (без проверки живости, без проверки личности):

{
  "id": "80371b2a-3ac7-432e-866d-57fe37896ac6",
  "status": 3,
  "idAge": { "result": "yes" }
}

Проверка возраста + Проверка живости + Проверка личности:

{
  "id": "80371b2a-3ac7-432e-866d-57fe37896ac6",
  "status": 3,
  "unicoId": { "result": "yes" },
  "idAge": { "result": "yes" },
  "liveness": 1
}
ПолеТипОписание
idstring (UUID)Идентификатор процесса. Используйте с Получением процесса для повторных запросов.
statusinteger3 (завершён успешно), 5 (ошибка). Используйте только status = 3 для бизнес-решений. Все возможные значения см. в Получении процесса.
idAge.resultstringyes, no, inconclusive -- результат проверки возраста. Присутствует во всех ответах.
unicoId.resultstringyes, no, inconclusive -- присутствует только при включённой проверке личности.
livenessinteger1 (пройдено), 2 (не пройдено) -- присутствует только при включённой проверке живости.
400 Bad Request

Тело запроса содержит ошибки, изображение недействительно или обязательные поля отсутствуют.

403 Forbidden

Bearer-токен или APIKEY отсутствует, истёк или недействителен. См. Аутентификация.

409 Conflict

Указанный processId уже существует для данного тенанта. См. Коды ошибок ниже.

429 Too Many Requests

Достигнут лимит запросов. Когда ваша система получает ошибку HTTP 429, необходимо реализовать механизмы для предотвращения каскадных сбоев и ухудшения ограничения.

Лучшие практики:

  • Период ожидания (backoff): Немедленно остановите или ограничьте последующие запросы из вашей системы. Не повторяйте неудачные запросы непрерывно в плотном цикле.
  • Очередь и ограничение: Буферизуйте или ставьте в очередь исходящие запросы на вашей стороне для управления потоком трафика перед повторной отправкой.
  • Экспоненциальный backoff с jitter: При повторных попытках увеличивайте время ожидания экспоненциально между попытками (например, 1 с, 2 с, 4 с, 8 с) и добавляйте небольшую случайную задержку ("jitter"), чтобы предотвратить эффект стада, когда все поставленные в очередь запросы повторяются в один и тот же момент.
предупреждение

Непрерывные запросы к эндпоинту с ограничением без отступления могут продлить период ограничения и серьёзно повлиять на операционную пропускную способность вашей системы. Правильное ограничение запросов на вашей стороне обеспечивает более плавную и устойчивую интеграцию.

Для получения информации о лимитах по умолчанию, увеличении запросов и дополнительных деталях см. Лимиты запросов.

500 Internal Server Error

Непредвиденная ошибка сервера.

Коды ошибок​

КодСообщениеОписание
20900O base64 informado não é válido.Недействительный параметр base64; возможная проблема с изображением или попытка инъекции.
20807A imagem precisa estar no padrão HD ou possuir uma resolução superior a 640 x 480.Разрешение изображения ниже минимального порога.
20509The subject.name field is invalid.subject.name содержит недопустимые символы.
20508The subject.gender field is invalid.subject.gender должен быть M или F.
20507O parâmetro subject.code é inválido.Некорректный или несуществующий идентификатор. Срабатывает только при включении проверки живости или проверки личности -- не требуется для потоков, ограниченных только проверкой возраста.
20506O base64 informado é muito grande. O tamanho máximo suportado é até 800kb.Размер данных превышает 800 КБ; сожмите до JPEG92.
20505O base64 informado não é suportado. Os formatos aceitos são png, jpeg e webp.Неподдерживаемый формат или недействительный префикс base64.
20062The useCase field is invalid.Нераспознанное значение в поле useCase.
20021The subject.phone field is invalid.Формат subject.phone недействителен (IDD + код региона + номер, 13 символов).
20019The subject.birthDate field is invalid.subject.birthDate не соответствует формату ISO 8601 (YYYY-MM-DD).
20009O parâmetro imagebase64 não foi informado.Отсутствует параметр изображения селфи.
20008The subject.email field is invalid.Недействительный формат email в subject.email.
20005O parâmetro subject.code não foi informado.Отсутствует параметр subject.code. Срабатывает только при включении проверки живости или проверки личности -- не требуется для потоков, ограниченных только проверкой возраста.
20004O parâmetro subject não foi informado.Отсутствует объект subject.
20003The request body is missing or invalid.Пустое или некорректное тело запроса.
20002O parâmetro APIKey não foi informado.Отсутствует заголовок APIKEY.
20001O parâmetro authtoken não foi informado.Отсутствует заголовок токена аутентификации.
10508The JWT with the captured face has already been used.JWT может быть использован только один раз.
10507The JWT with the captured face is expired.JWT превысил 10-минутное окно действия.
10506The imageBase64 field is not a valid JWT from SDK.imageBase64 не является действительным JWT, сгенерированным SDK.

Что дальше​

Последнее обновление