Получение документов для повторного использования

MarkdownChatGPTClaude

Используйте этот эндпоинт, чтобы проверить, есть ли у пользователя уже документ, доступный для повторного использования, прежде чем начинать новый поток захвата документа. Если документ найден, его documentId можно передать напрямую в POST /processes/v1 (тип Document), чтобы пропустить этап захвата.

Эндпоинт

Среда	URL
Production	GET https://api.idcloud.unico.app/documents/v1
Sandbox	GET https://api.idcloud.uat.unico.app/documents/v1

Запрос

Заголовки

Заголовок	Значение
Authorization	Bearer <access_token> (см. Аутентификация)
APIKEY	Выделенный API-ключ с включённой возможностью «Распознавание документов и повторное использование».

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

Параметр	Тип	Обязателен	Описание
code	string	да	Идентификатор пользователя (CPF или CURP, без форматирования).
type	string	да	Тип запрашиваемого документа. Допустимые значения: BR_RG, BR_CNH, BR_CIN, BR_PASSPORT.

примечание

Значения type, указанные выше, специфичны для этого эндпоинта. Не путайте их с:

• subject.duiType в запросах POST — использует префикс DUI_TYPE_* и идентифицирует человека, а не тип документа (например, DUI_TYPE_BR_CPF).
• documentType в ответе — использует полный путь реестра (например, unico.moja.dictionary.br.cnh.v2.Cnh).

Пример

cURL

curl -X GET "https://api.idcloud.unico.app/documents/v1?code=12345678909&type=BR_CNH" \
  -H "Authorization: Bearer $TOKEN" \
  -H "APIKEY: $API_KEY"

Node.js

import fetch from 'node-fetch';

const params = new URLSearchParams({ code: '12345678909', type: 'BR_CNH' });
const res = await fetch(
  `https://api.idcloud.unico.app/documents/v1?${params}`,
  {
    headers: {
      Authorization: `Bearer ${accessToken}`,
      APIKEY: apiKey
    }
  }
);
const data = await res.json();
// data.items[0].documentId → pass to POST /processes/v1 for reuse

Ответы

200 OK

{
  "items": [
    {
      "documentType": "unico.moja.dictionary.br.cnh.v2.Cnh",
      "documentId": "doc-abc-123"
    }
  ]
}

Поле	Тип	Описание
items	array	Список документов, доступных для повторного использования, найденных для пользователя. Пустой массив, если для указанных code и type не найдено ни одного документа, доступного для повторного использования.
items[].​documentType	string	Идентификатор типа документа. Возможные значения: unico.​moja.​dictionary.​br.​rg.​v2.​Rg, unico.​moja.​dictionary.​br.​cnh.​v2.​Cnh, unico.​moja.​dictionary.​br.​cin.​v1.​Cin, unico.​moja.​dictionary.​br.​passaporte.​v1.​Passaporte.
items[].documentId	string	Идентификатор документа. Передайте это значение в document.documentId при вызове POST /processes/v1, чтобы повторно использовать документ.

Использование documentId для повторного использования

Получив documentId, передайте его в запросе процесса Document, чтобы пропустить захват:

{
  "subject": {
    "code": "12345678909",
    "name": "Luke Skywalker"
  },
  "document": {
    "purpose": "onboarding",
    "authProcessId": "<biometric-process-id>",
    "documentId": "doc-abc-123"
  }
}

Поле	Описание
document.purpose	Бизнес-цель для этого процесса с документом. Допустимые значения: creditprocess, carpurchase, paybypaycheck, onboarding, fgts. Эти значения специфичны для Document API и отличаются от перечисления purpose биометрического SDK.
document.​authProcessId	ID биометрического процесса, ранее созданного для этого пользователя (из POST /processes/v1).
document.documentId	ID документа, полученный из ответа этого эндпоинта. Если он указан, document.files можно не передавать — платформа автоматически получает ранее захваченный документ.

Коды ошибок

400 Bad Request

Код	Сообщение	Описание
20507	O parâmetro subject.code é inválido.	Некорректное или несуществующее значение идентификатора (CPF или CURP).
20002	O parâmetro APIKey não foi informado.	Отсутствует заголовок APIKEY.
20001	O parâmetro authtoken não foi informado.	Отсутствует заголовок токена аутентификации.

403 Forbidden

Bearer-токен или APIKEY отсутствует, истёк или недействителен.

Код	Сообщение	Описание
30020	The provided authorization token does not have permission to perform this action.	У токена нет прав для доступа к селфи документа.
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.

404 Not Found

Код	Сообщение	Описание
99987	Attachment not found.	Вложение, связанное с документом, не найдено.
50001	The process is not found.	Не найден документ по указанным параметрам.

429 Too Many Requests

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

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

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

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

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

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

500 Internal Server Error

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