Создание процесса

MarkdownChatGPTClaude

Этот эндпоинт обрабатывает три продукта, которые имеют один и тот же путь, но отличаются параметрами тела запроса, возможностями и полями ответа:

• Онбординг -- проверяет, кто является пользователем, сравнивая его лицо с базой идентификации Unico (требуются subject.duiType + subject.code).
• Транзакционный -- проверяет, что это тот же человек из предыдущего процесса, сравнивая лицо с лицом (требуется referenceProcessId ИЛИ массив references с селфи / ID процесса).
• Cardholder Verification -- подтверждает, что карта принадлежит заявленному держателю, без захвата селфи (требуются subject.code + card). Опционально повторно использует ранее проверенный процесс через referenceProcessId для запуска проверки повторного использования (gate); без этого поля ответ по умолчанию — unsure. См. возможность Cardholder Verification.

Активный продукт определяется APIKEY, отправленным в заголовке запроса.

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

Эндпоинт

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

Запрос

Заголовки

Заголовок	Значение
Authorization	Bearer <access_token> (см. Аутентификация)
APIKEY	Предоставленный API-ключ -- определяет активный продукт и включённые возможности.
Content-Type	application/json

Параметры тела запроса

Онбординг

Поле	Тип	Обязательный	Описание
subject.duiType	integer	да	Идентификатор типа документа. См. значения duiType ниже.
subject.code	string	да	Значение идентификатора в соответствии с subject.duiType. Без точек и дефисов.
subject.name	string	нет	Полное имя.
subject.gender	string	нет	M или F.
subject.birthDate	string (ISO 8601)	нет	Дата рождения (YYYY-MM-DD).
subject.email	string	нет	Адрес электронной почты.
subject.phone	string	нет	Номер телефона в формате E.164.
subject.clientReference	string	условно	Уникальный идентификатор пользователя в вашей системе. Обязателен для возможности Мультиаккаунт. Уникален в вашей базе, максимум 256 символов, без пробелов.
useCase	string	нет	Контекст операции, например Onboarding.
subsidiaryId	string	нет	Идентификатор филиала — требуется только при наличии нескольких филиалов.
imageBase64	string	да	Селфи, захваченное вашим фронтендом, в формате base64.

Транзакционный

Поле	Тип	Обязательный	Описание
references	array	условно	Входные данные для потоков валидации 1:1. Каждый элемент содержит referenceType (REFERENCE_TYPE_IMAGE_BASE64 или REFERENCE_TYPE_PROCESS_ID) и referenceContent (base64-изображение или UUID процесса).
referenceProcessId	string	условно	Устарело. Используйте references вместо этого. ID ссылочного процесса онбординга для сравнения. Если ссылка представляет собой процесс by-Unico, используйте authenticationInfo.authenticationId.
imageBase64	string	да	Селфи, захваченное вашим фронтендом, в формате base64.
subject	object	нет	Контейнер информации о пользователе.
subject.duiType	string	нет	Тип идентификатора. Возможные значения: DUI_TYPE_AR_DNI, DUI_TYPE_BR_CPF, DUI_TYPE_ID_NIK, DUI_TYPE_MX_CURP, DUI_TYPE_NG_NIN, DUI_TYPE_US_SSN.
subject.code	string	нет	Значение идентификатора в соответствии с subject.duiType. Без точек и дефисов.
subject.name	string	нет	Полное имя пользователя.
subject.gender	string	нет	M или F.
subject.birthDate	string (ISO 8601)	нет	Дата рождения (YYYY-MM-DD).
subject.email	string	нет	Адрес электронной почты.
subject.phone	string	нет	Номер телефона в формате E.164.
useCase	string	нет	Контекст операции, например Transactional.
subsidiaryId	string	нет	ID филиала -- обязателен только при наличии нескольких филиалов.

информация

Для этого продукта невозможна оркестрация с Риск-скором. Результат всегда возвращается синхронно в ответе POST.

Cardholder Verification

Поле	Тип	Обязательный	Описание
subject.duiType	integer	да	Идентификатор типа документа. См. значения duiType ниже. На данный момент только DUI_TYPE_BR_CPF.
subject.code	string	да	CPF держателя карты, который проверяется. Без точек и дефисов.
card.bin	string	условно	Первые 6 или 8 цифр карты (BIN). Обязателен совместно с card.last4.
card.last4	string	условно	Последние 4 цифры карты. Обязателен совместно с card.bin.
card.name	string	нет	Имя держателя карты, как указано на карте.
referenceProcessId	string (UUID)	нет	ID ранее проверенного процесса для повторного использования — процесса с одобренным результатом Проверки личности или Проверки живости для того же CPF. Текущая версия этой возможности основана на повторном использовании: без этого поля проверка (gate) никогда не запускается, и ответ по умолчанию — стандартный результат unsure; сам запрос при этом никогда не завершается ошибкой.
useCase	string	нет	Контекст операции, например CardholderVerification.
subsidiaryId	string	нет	Идентификатор филиала — требуется только при наличии нескольких филиалов.

информация

Для этого продукта не отправляется imageBase64 — Cardholder Verification выполняется полностью на backend, без этапа захвата селфи.

Значения duiType

Страна	Код	Описание
AR	6	Аргентинский паспорт
AR	7	Аргентинский DNI
AR	49	Аргентинское водительское удостоверение (Licencia Nacional de Conducir)
AT	34	Австрийский налоговый номер (STNR)
BE	36	Бельгийский национальный номер (NN)
BR	1	Бразильский CPF
BR	5	Бразильский паспорт
BR	14	Бразильский CNPJ
CA	28	Канадский SIN
CH	33	Швейцарский номер AHV/AVS
CL	9	Чилийский RUN
CL	52	Чилийский паспорт
CL	57	Чилийское водительское удостоверение (Licencia de Conducir)
CO	26	Колумбийский NIT
CO	53	Колумбийский паспорт
CO	55	Колумбийское водительское удостоверение (Licencia de Conducción)
CO	56	Колумбийское удостоверение личности гражданина (Cédula de Ciudadanía)
DE	41	Немецкий налоговый идентификационный номер (IdNr)
DK	29	Датский CPR
EC	10	Эквадорский NI
ES	50	Испанский номер иностранца (NIE)
ES	51	Испанский национальный документ, удостоверяющий личность (DNI)
FI	35	Финский код личной идентификации (HETU)
FR	46	Французский налоговый справочный номер (SPI)
GB	30	Британский номер национального страхования (NINO)
GT	12	Гватемальский CUI
ID	16	Индонезийский NIK
IE	47	Ирландский номер социального страхования (PPSN)
IT	37	Итальянский налоговый код (Codice Fiscale, CF)
LU	48	Люксембургский национальный идентификационный номер (Matricule)
MX	2	Мексиканский CURP
MX	25	Мексиканский RFC (физическое лицо)
MX	58	Мексиканское водительское удостоверение (Licencia de Conducir)
NG	8	Нигерийский NIN
NG	20	Нигерийский номер верификации банковского счёта (BVN)
NG	43	Токен BVN Нигерии (хешированный)
NG	44	Токен NIN Нигерии (хешированный)
NL	42	Голландский идентификационный номер гражданина (BSN)
NO	39	Норвежский национальный идентификационный номер (Fødselsnummer)
PE	27	Перуанский RUC
PE	40	Перуанский DNI
PE	54	Перуанский паспорт
PL	31	Польский PESEL
PT	45	Португальский налоговый идентификационный номер (NIF)
SE	32	Шведский личный номер (PNR)
SE	38	Шведский координационный номер (Samordningsnummer)
TR	24	Турецкий идентификационный номер (TCKN)
US	4	SSN США
US	11	Паспорт США
US	18	Водительское удостоверение США
US	21	Паспортная карта США
US	22	Поликарбонатный паспорт США
US	23	Идентификационная карта США
UY	13	Уругвайский CI
ZZ	15	Адрес электронной почты
ZZ	17	Номер телефона
—	0	Не указано
—	3	Внутренний идентификатор Unico

Требования к изображению

• Минимальное разрешение: 640 x 480 (стандарт HD)
• Максимальный размер файла: 800 КБ (рекомендуется сжатие JPEG92)
• Допустимые форматы: PNG, JPEG, WebP
• JWT-токены из SDK истекают через 10 минут и могут быть использованы только один раз

Сжатые запросы

API поддерживает отправку сжатого тела запроса с помощью стандартного HTTP-заголовка Content-Encoding. Это опционально и полностью обратно совместимо: клиенты, которые не отправляют этот заголовок, продолжают работать точно так же, как и раньше.

Поддерживаемые форматы

Кодирование	Заголовок Content-Encoding	Статус
Gzip	gzip	✅ Рекомендуется
Deflate	deflate	✅ Поддерживается
Без сжатия	(заголовок отсутствует)	✅ Поддерживается (поведение по умолчанию)

Рекомендация

Используйте gzip. Он имеет наиболее универсальную поддержку среди языков и HTTP-библиотек, что избавляет от неоднозначностей реализации, присущих другим форматам.

Сжатие рекомендуется для запросов с большим телом (например, объёмные JSON-полезные нагрузки, загрузка изображений в base64, пакетная отправка данных). Для небольших запросов накладные расходы на сжатие могут не принести существенной выгоды.

Как отправить сжатый запрос

1. Сжмите тело запроса (например, сериализованный JSON) выбранным алгоритмом.
2. Отправьте сжатое тело как бинарные байты в запросе.
3. Включите заголовок Content-Encoding с соответствующим значением (gzip или deflate).
4. Оставьте Content-Type, описывающий исходный формат содержимого (например, application/json), а не транспортное кодирование.

cURL

echo '{"subject":{"code":"12345678909"},"useCase":"Onboarding","imageBase64":"/9j/4AAQSkZJR..."}' | gzip > body.json.gz

curl -X POST https://api.id.unico.app/processes/v1 \
  -H "Authorization: Bearer $TOKEN" \
  -H "APIKEY: $API_KEY" \
  -H "Content-Type: application/json" \
  -H "Content-Encoding: gzip" \
  --data-binary @body.json.gz

Python (requests)

import gzip
import json
import requests

payload = {
    "subject": {"code": "12345678909"},
    "useCase": "Onboarding",
    "imageBase64": capturedImage,
}
compressed_body = gzip.compress(json.dumps(payload).encode("utf-8"))

response = requests.post(
    "https://api.id.unico.app/processes/v1",
    data=compressed_body,
    headers={
        "Authorization": f"Bearer {token}",
        "APIKEY": api_key,
        "Content-Type": "application/json",
        "Content-Encoding": "gzip",
    },
)

.NET (C#, HttpClient)

using System.IO.Compression;
using System.Text;
using System.Text.Json;

var json = JsonSerializer.Serialize(payload);
var jsonBytes = Encoding.UTF8.GetBytes(json);

using var outputStream = new MemoryStream();
using (var gzipStream = new GZipStream(outputStream, CompressionMode.Compress, leaveOpen: true))
{
    await gzipStream.WriteAsync(jsonBytes, 0, jsonBytes.Length);
}
outputStream.Position = 0;

var content = new ByteArrayContent(outputStream.ToArray());
content.Headers.ContentType = new MediaTypeHeaderValue("application/json");
content.Headers.ContentEncoding.Add("gzip");

using var client = new HttpClient();
client.DefaultRequestHeaders.Add("Authorization", $"Bearer {token}");
client.DefaultRequestHeaders.Add("APIKEY", apiKey);

var response = await client.PostAsync("https://api.id.unico.app/processes/v1", content);

совет

Для примера на Python используйте параметр data=, а не json=. Параметр json= автоматически сериализует полезную нагрузку, но не сжимает её.

Использование deflate: процесс, описанный выше, идентичен — меняются только вызов сжатия и значение Content-Encoding.

Язык	deflate
Bash / cURL	zlib-flate -compress < body.json > body.json.deflate (из qpdf), затем -H "Content-Encoding: deflate"
Python	zlib.compress(data) вместо gzip.compress(data)
.NET (C#)	System.IO.Compression.DeflateStream вместо GZipStream

deflate неоднозначен на практике

Кодирование содержимого deflate в HTTP определено как поток zlib (RFC 1950), но некоторые клиенты и серверы исторически используют или ожидают необработанный DEFLATE (RFC 1951). Этот API ожидает стандартный поток, обёрнутый в zlib, — тот же результат, который zlib.compress() (Python) или DeflateStream (.NET) выдают по умолчанию. Если не уверены, отдавайте предпочтение gzip, у которого такой неоднозначности нет.

Поведение при ошибке

Если Content-Encoding отправлен с неподдерживаемым значением, либо тело повреждено или недействительно для заявленного кодирования, API возвращает 400 Bad Request с сообщением о том, что не удалось распаковать тело запроса.

FAQ

Нужно ли что-то менять, если я не хочу использовать сжатие? Нет. Поддержка Content-Encoding является дополнительной — запросы без этого заголовка продолжают обрабатываться как обычно.

Влияет ли это на ответ API? Нет. Эта функциональность касается только тела, отправляемого клиентом (запроса). Сжатие ответа (то, что возвращает API) регулируется отдельно заголовком Accept-Encoding.

Какой формат следует выбрать? Используйте gzip, если только особые ограничения вашей среды не требуют другого формата.

Пример

Онбординг -- cURL

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": {
      "duiType": 1,
      "code": "12345678909",
      "name": "Luke Skywalker",
      "gender": "M",
      "birthDate": "2000-05-20",
      "email": "[email protected]",
      "phone": "5519725570707"
    },
    "useCase": "Onboarding",
    "imageBase64": "/9j/4AAQSkZJR..."
  }'

Онбординг -- Node.js

import fetch from 'node-fetch';

const res = await fetch('https://api.id.unico.app/processes/v1', {
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${process.env.UNICO_ACCESS_TOKEN}`,
    'APIKEY': process.env.UNICO_API_KEY,
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    subject: {
      duiType: 1,
      code: '12345678909',
      name: 'Luke Skywalker',
      gender: 'M',
      birthDate: '2000-05-20',
      email: '[email protected]',
      phone: '5519725570707'
    },
    useCase: 'Onboarding',
    imageBase64: capturedImage
  })
});

const result = await res.json();

Транзакционный -- cURL

curl -X POST https://api.id.unico.app/processes/v1 \
  -H "Authorization: Bearer $TOKEN" \
  -H "APIKEY: $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "references": [
      {
        "referenceType": "REFERENCE_TYPE_PROCESS_ID",
        "referenceContent": "4f00b35f-69d4-415a-a843-d975cefcb169"
      }
    ],
    "useCase": "Transactional",
    "imageBase64": "/9j/4AAQSkZJR..."
  }'

Транзакционный -- Node.js

import fetch from 'node-fetch';

const res = await fetch('https://api.id.unico.app/processes/v1', {
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${process.env.UNICO_ACCESS_TOKEN}`,
    'APIKEY': process.env.UNICO_API_KEY,
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    references: [
      {
        referenceType: 'REFERENCE_TYPE_PROCESS_ID',
        referenceContent: '4f00b35f-69d4-415a-a843-d975cefcb169'
      }
    ],
    useCase: 'Transactional',
    imageBase64: capturedImage
  })
});

const result = await res.json();

Cardholder Verification -- cURL

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": {
      "duiType": 1,
      "code": "12345678909"
    },
    "card": {
      "bin": "12345678",
      "last4": "4321",
      "name": "Luke Skywalker"
    },
    "referenceProcessId": "4f00b35f-69d4-415a-a843-d975cefcb169",
    "useCase": "CardholderVerification"
  }'

Cardholder Verification -- Node.js

import fetch from 'node-fetch';

const res = await fetch('https://api.id.unico.app/processes/v1', {
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${process.env.UNICO_ACCESS_TOKEN}`,
    'APIKEY': process.env.UNICO_API_KEY,
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    subject: {
      duiType: 1,
      code: '12345678909'
    },
    card: {
      bin: '12345678',
      last4: '4321',
      name: 'Luke Skywalker'
    },
    referenceProcessId: '4f00b35f-69d4-415a-a843-d975cefcb169',
    useCase: 'CardholderVerification'
  })
});

const result = await res.json();

Ответы

Онбординг

200 OK

Контракт единый — поле idCloud.result содержит консолидированный вердикт используемых возможностей.

Unico консолидирует результаты выполненных возможностей в единое поле idCloud.result, готовое для принятия решения о следующем шаге вашего флоу — без необходимости оркестрировать отдельные результаты.

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

Поле	Тип	Описание
id	string (UUID)	Идентификатор процесса. Используйте с Получением процесса для повторных запросов.
status	integer	1 (обработка), 3 (завершён успешно), 5 (ошибка).

Возможные значения результата

idCloud.result	Значение	Рекомендуемое действие
approved	Реальный человек и подтверждённая личность.	Продолжить флоу.
denied	Личность не подтверждена, проверка живости не пройдена или выявлен экстремальный риск.	Завершить флоу или перенаправить на альтернативный флоу.
critical-risk	Выявлен критический уровень риска.	Завершить флоу или направить на ручную проверку.
high-risk	Выявлен высокий уровень риска.	Направить на ручную проверку или альтернативный флоу.
retry	Недостаточно данных захвата или скора для оценки.	Запросить у пользователя новый захват.
inconclusive	Недостаточно доказательств для вынесения вердикта.	Направить на ручную проверку или альтернативный флоу.

Возвращаемые значения зависят от рецепта, настроенного в вашем APIKey. См. Потоки — значения результата, которые может вернуть каждый рецепт.

Клиенты в Бразилии могут получать ответ по возможностям

Общая структура ответа остаётся прежней — единый результат используется по умолчанию.

Интеграции в Бразилии могут получать открытые результаты по каждой возможности отдельно. Каждая возможность, включённая в APIKey, добавляет свой блок в ответ — поля для отключённых возможностей отсутствуют.

{
  "id": "80371b2a-3ac7-432e-866d-57fe37896ac6",
  "status": 3,
  "unicoId": { "result": "yes" },
  "riskLevel": { "result": "inconclusive" },
  "idFace": {
    "personId": "a1b2c3d4e5f67890a1b2c3d4e5f67890a1b2c3d4e5f67890a1b2c3d4e5f67890",
    "result": "FOUND"
  },
  "government": { "serpro": 87 },
  "liveness": 1
}

Поля ответа зависят от вашего APIKey

Приведённый выше пример содержит все возможные поля возможностей. В реальном ответе будут только поля для возможностей, включённых в конфигурации вашего APIKey — поля для отключённых возможностей полностью отсутствуют. Свяжитесь с вашим менеджером проекта Unico для включения или изменения возможностей.

Поле	Тип	Описание
unicoId.result	string	yes, no, inconclusive -- см. Проверка личности.
riskLevel.result	string	approved, reproved, risk-critical, risk-high, inconclusive -- см. возможные значения ниже или Классификация рисков мошенничества.
idFace.result	string	FOUND — см. Идентификатор лица.
idFace.personId	string	Стабильный непрозрачный идентификатор лица, возвращается вместе с idFace.result = FOUND. Если лицо не удаётся идентифицировать на изображении, запрос завершается ошибкой 20532 вместо возврата блока idFace.
identityFraudsters.result	string	Устарело. Используйте вместо него riskLevel. Клиенты с текущими интеграциями могут продолжать использовать это поле, согласовывая миграцию с командой проекта.
government.serpro	integer	Оценка сходства Serpro (0--100, -1, -2). Доступно только в Бразилии. См. Результат проверки сходства Serpro.
liveness	integer	1 (пройдено), 2 (не пройдено) -- см. Проверка живости.

riskLevel.result — возможные значения

Значение	Описание
approved	Это лицо владельца удостоверения личности, и никаких признаков мошенничества не обнаружено.
reproved	Рекомендуется отказ, поскольку обнаружено несколько индикаторов мошенничества.
risk-critical	Рекомендуется отказ, однако окончательное решение остаётся за вами. Критический риск означает, что обнаружено не менее 2 веских признаков мошенничества.
risk-high	Отказ также рекомендуется, однако решение остаётся за вами. Высокий риск означает, что обнаружен как минимум один весомый признак мошенничества.
inconclusive	Веских признаков мошенничества не обнаружено. Поэтому невозможно сделать однозначный вывод о наличии существенного риска.

информация

Когда unicoId.result = inconclusive и оркестрация Риск-скора активна, процесс может вернуть status: 1 (обработка). Опрашивайте Получение процесса или используйте вебхуки для получения финального результата.

Клиенты в Мексике могут получать блок RENAPO Verification

Структура ответа остаётся прежней, добавляется блок idGov.

Интеграции в Мексике с включённой RENAPO Verification получают дополнительный блок idGov с записью, которую RENAPO хранит по CURP пользователя. Это отдельный ответ, не связанный с результатом проверки личности.

{
  "id": "11111111-2222-3333-4444-555555555555",
  "status": 3,
  "idCloud": { "result": "approved" },
  "idGov": {
    "government_valid": true,
    "curp": "PUEA880304MDFRJN04",
    "government_name": "ANA PRUEBA EJEMPLO",
    "date_of_birth": "1988-03-04",
    "age": 38,
    "gender": "F",
    "deceased": false,
    "is_mexican": true,
    "citizenship": "MEXICO",
    "state_of_birth": "Ciudad de México",
    "state_iso": "MX-CMX",
    "issuing_entity_code": "DF",
    "municipality_registration": ""
  }
}

Поле	Тип	Описание
idGov	object	Запись RENAPO по CURP. Отсутствует, если возможность не включена. {}, если RENAPO не ответил. Только Мексика. См. RENAPO Verification.

Транзакционный

200 OK

Контракт единый — поле idCloud.result содержит консолидированный вердикт используемых возможностей.

Unico консолидирует результаты выполненных возможностей в единое поле idCloud.result, готовое для принятия решения о следующем шаге вашего флоу — без необходимости оркестрировать отдельные результаты.

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

Поле	Тип	Описание
id	string (UUID)	Идентификатор процесса.
status	integer	3 (завершён успешно), 5 (ошибка). Все возможные значения см. в Получении процесса.

Возможные значения результата

idCloud.result	Значение	Рекомендуемое действие
approved	Реальный человек и подтверждённая личность.	Продолжить флоу.
denied	Личность не подтверждена, проверка живости не пройдена или выявлен экстремальный риск.	Завершить флоу или перенаправить на альтернативный флоу.
critical-risk	Выявлен критический уровень риска.	Завершить флоу или направить на ручную проверку.
high-risk	Выявлен высокий уровень риска.	Направить на ручную проверку или альтернативный флоу.
retry	Недостаточно данных захвата или скора для оценки.	Запросить у пользователя новый захват.
inconclusive	Недостаточно доказательств для вынесения вердикта.	Направить на ручную проверку или альтернативный флоу.

Возвращаемые значения зависят от рецепта, настроенного в вашем APIKey. См. Потоки — значения результата, которые может вернуть каждый рецепт.

Клиенты в Бразилии могут получать ответ по возможностям

Общая структура ответа остаётся прежней — единый результат используется по умолчанию.

Интеграции в Бразилии могут получать открытые результаты по каждой возможности отдельно. Каждая возможность, включённая в APIKey, добавляет свой блок в ответ — поля для отключённых возможностей отсутствуют.

{
  "id": "80371b2a-3ac7-432e-866d-57fe37896ac6",
  "status": 3,
  "biometryToken": { "result": true },
  "liveness": 1
}

Поле	Тип	Описание
biometryToken.result	boolean	true, если переданное лицо совпадает с ссылочным процессом; false в противном случае.
liveness	integer	1 (пройдено), 2 (не пройдено) -- см. Проверка живости.

Cardholder Verification

200 OK

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

Поле	Тип	Описание
id	string (UUID)	Идентификатор процесса.
status	integer	1 (обработка), 3 (завершён успешно), 5 (ошибка). Все возможные значения см. в Получении процесса.
cardholderVerification.result	string	approved — CPF и карта принадлежат одному и тому же человеку. unsure — либо условие повторного использования не было выполнено, либо сама проверка оказалась неубедительной. Отсутствует, пока status не станет равным 3. См. Cardholder Verification.

Коды ошибок

400 Bad Request

Код	Сообщение	Описание
40221	This flow does not support reusing a prior process (referenceProcessId or bioTokenId) without an image; send an image (imageBase64, or references[0] with type IMAGE_BASE64) instead.	Поток повторного использования (referenceProcessId/bioTokenId, без изображения) был отклонён, поскольку повторное использование процесса не включено для этого API-ключа.
20900	O base64 informado não é válido.	Параметр base64 недействителен. Возможные причины: это не изображение или попытка инъекции.
20807	A imagem precisa estar no padrão HD ou possuir uma resolução superior a 640 x 480.	Разрешение загруженного изображения слишком низкое.
20532	No face detected in image.	Не удалось обнаружить лицо на отправленном изображении.
20513	The referenced process was not found.	referenceProcessId указывает на процесс, который не существует или более недоступен.
20512	The referenced process is not available for reuse.	Ссылочный процесс существует, но недоступен для повторного использования.
20509	The subject.name field is invalid.	subject.name содержит недопустимые символы.
20508	The subject.gender field is invalid.	subject.gender должен быть M или F.
20507	O parâmetro subject.code é inválido.	Нестандартный или несуществующий CPF.
20506	O base64 informado é muito grande. O tamanho máximo suportado é até 800kb.	Размер изображения превышает 800 КБ; сожмите до JPEG92.
20505	O base64 informado não é suportado. Os formatos aceitos são png, jpeg e webp.	Формат base64 недействителен или не поддерживается.
20065	The referenceProcessId field is invalid.	referenceProcessId не является действительным UUID.
20062	The useCase field is invalid.	Нераспознанное значение в поле useCase.
20024	The referenceProcessId field is missing.	Параметр referenceProcessId не указан, и references не отправлен в качестве альтернативы. Не применяется к Cardholder Verification — его referenceProcessId никогда не проверяется как обязательный; при невыполненном условии повторного использования возвращается unsure.
20533	The card field is missing.	Cardholder Verification: объект card не был предоставлен.
20534	The card.bin field is missing.	Cardholder Verification: card.bin не был предоставлен.
20535	The card.last4 field is missing.	Cardholder Verification: card.last4 не был предоставлен.
20536	The card data is invalid.	Cardholder Verification: данные карты были отклонены как недействительные.
20021	The subject.phone field is invalid.	Формат subject.phone недействителен (IDD + код региона + номер, 13 символов).
20019	The subject.birthDate field is invalid.	subject.birthDate не соответствует формату ISO 8601 (YYYY-MM-DD).
20009	O parâmetro imagebase64 não foi informado.	Отсутствует параметр изображения селфи.
20008	The subject.email field is invalid.	Недействительный формат email в subject.email.
20006	O parâmetro subject.name não foi informado.	Отсутствует параметр subject.name.
20005	O parâmetro subject.code não foi informado.	Отсутствует параметр subject.code.
20004	O parâmetro subject não foi informado.	Отсутствует параметр subject.
20003	The request body is missing or invalid.	Пустое или некорректное тело запроса.
20002	O parâmetro APIKey não foi informado.	Параметр APIKEY отсутствует в заголовке запроса.
20001	O parâmetro authtoken não foi informado.	Параметр токена интеграции отсутствует в заголовке запроса.
10508	The JWT with the captured face has already been used.	JWT может быть использован только один раз.
10507	The JWT with the captured face is expired.	JWT истёк; должен быть отправлен в течение 10 минут.
10506	The imageBase64 field is not a valid JWT from SDK.	imageBase64 не является действительным JWT, сгенерированным SDK.

403 Forbidden

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

Код	Сообщение	Описание
30017	User does not have permission to perform this action.	Некорректный JWT или пользователь без разрешения на выполнение этой операции.
10502	O token informado está expirado.	Access-token истёк.
10501	O token informado é inválido.	Токен аутентификации недействителен.
10201	O AppKey informado é inválido.	APIKEY недействителен или не существует.

409 Conflict

Код	Сообщение	Описание
20073	The processID already exists.	Указанный processId уже существует для данного тенанта.

429 Too Many Requests

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

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

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

предупреждение

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

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

500 Internal Server Error

Код	Сообщение	Описание
99999	Internal failure! Try again later	Внутренняя ошибка.

Что дальше

• Для запроса результата процесса онбординга см. Получение процесса.
• Чтобы увидеть все комбинации рецептов и их возможные значения результата, см. Потоки.
• Для операций с документами и проверкой возраста см. соответствующие страницы в этом разделе.