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

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

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

Эндпоинт​

СредаURL
ProductionGET https://api.id.unico.app/documents/v1
SandboxGET https://api.id.uat.unico.app/documents/v1

Запрос​

Заголовки
ЗаголовокЗначение
AuthorizationBearer <access_token> (см. Аутентификация)
APIKEYПредоставленный API-ключ с включённой функцией Распознавание документов и повторное использование.
Параметры запроса
ПараметрТипОбязательныйОписание
codestringдаИдентификатор пользователя (CPF или CURP, без форматирования).
typestringдаТип документа для запроса. Допустимые значения: 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 -X GET "https://api.id.unico.app/documents/v1?code=12345678909&type=BR_CNH" \
  -H "Authorization: Bearer $TOKEN" \
  -H "APIKEY: $API_KEY"

Ответы​

200 OK
{
  "items": [
    {
      "documentType": "unico.moja.dictionary.br.cnh.v2.Cnh",
      "documentId": "doc-abc-123"
    }
  ]
}
ПолеТипОписание
itemsarrayСписок документов, доступных для повторного использования. Пустой массив, если для указанных code и type документ не найден.
items[].documentTypestringИдентификатор типа документа. Возможные значения: 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[].documentIdstringИдентификатор документа. Передайте это значение в document.documentId при вызове POST /processes/v1, чтобы повторно использовать документ.
403 Forbidden

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

429 Too Many Requests

Rate limit reached. When your system receives an HTTP 429 error, you must implement mechanisms to prevent cascading failures and avoid worsening the restriction.

Best practices:

  • Cool-down period (backoff): Immediately halt or throttle subsequent requests from your system. Do not continuously retry failed requests in a tight loop.
  • Queueing & throttling: Buffer or queue outgoing requests on your end to control the traffic flow before re-sending them.
  • Exponential backoff with jitter: When retrying, increase the waiting time exponentially between attempts (e.g., 1 s, 2 s, 4 s, 8 s) and add a small random delay ("jitter") to prevent a herd effect where all queued requests retry at the exact same millisecond.
предупреждение

Continuously hitting a rate-limited endpoint without backing off can prolong the restriction period and severely impact your system's operational throughput. Properly throttling requests on your side ensures a smoother, more resilient integration.

For default limits, increase requests and additional details, see Rate Limits.

Использование 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.authProcessIdID биометрического процесса, ранее созданного для этого пользователя (из POST /processes/v1).
document.documentIdID документа, полученный из ответа этого эндпоинта. При указании этого параметра document.files можно опустить — платформа автоматически извлечёт ранее захваченный документ.

Полную схему запроса процесса Document см. в разделе Создание процесса Document.

Коды ошибок​

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