Установка документа процесса

Устанавливает документ удостоверения личности (CPF, CURP, SSN или другой duiType) для процесса, созданного без него. После установки документ становится неизменяемым.

Доступно только для процессов, чей Custom Flow допускает создание без документа, т.е. процессов в состоянии AWAITING_FOR_DOCUMENT.

Эндпоинт

Окружение	URL
Production	POST https://api.idcloud.unico.app/client/v1/process/{processId}/document
Sandbox	POST https://api.idcloud.uat.unico.app/client/v1/process/{processId}/document

Запрос

Заголовки

Заголовок	Значение
Authorization	Bearer <access_token> (см. Аутентификация)
Content-Type	application/json

Параметры пути

Поле	Тип	Обязательный	Описание
processId	string	да	ID процесса, возвращённый в process.id при создании.

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

Поле	Тип	Обязательный	Описание
duiType	enum	да	Тип документа. Значения: DUI_TYPE_BR_CPF, DUI_TYPE_MX_CURP, DUI_TYPE_US_SSN. Этот эндпоинт поддерживает подмножество типов документов, принимаемых Созданием процесса -- Custom Flow, допускающие опциональное создание документа, в настоящее время валидируются по этому более узкому списку.
duiValue	string	да	Номер документа, без форматирования. Максимум 320 символов (для поддержки кодированных или составных идентификаторов; стандартные номера документов, такие как CPF или CURP, значительно короче).

Пример

cURL

curl -X POST https://api.idcloud.unico.app/client/v1/process/abc-123/document \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "duiType": "DUI_TYPE_BR_CPF",
    "duiValue": "12345678901"
  }'

Node.js

import fetch from 'node-fetch';

const res = await fetch(
  'https://api.idcloud.unico.app/client/v1/process/abc-123/document',
  {
    method: 'POST',
    headers: {
      'Authorization': `Bearer ${process.env.UNICO_ACCESS_TOKEN}`,
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({
      duiType: 'DUI_TYPE_BR_CPF',
      duiValue: '12345678901',
    }),
  }
);

const { process: proc } = await res.json();
// proc.id, proc.person.duiType, proc.person.duiValue

Ответы

200 OK

{
  "process": {
    "id": "abc-123",
    "person": {
      "duiType": "DUI_TYPE_BR_CPF",
      "duiValue": "12345678901"
    }
  }
}

Поле	Тип	Описание
process.id	string	Идентификатор процесса.
process.person.duiType	string	Тип документа, установленный для процесса.
process.person.duiValue	string	Значение документа, установленное для процесса.

400 Bad Request

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

401 Unauthorized

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

404 Not Found

Процесс не найден.

429 Too Many Requests

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

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

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

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

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

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

Коды ошибок

400 Bad Request

Код	Сообщение	Описание
3	process id is invalid	Когда ID процесса недействителен.
3	dui_type is required	Когда тип документа не указан.
3	dui_value is required	Когда номер документа не указан.
3	dui_value exceeds maximum length	Когда номер документа превышает максимально допустимую длину.
9	process is not awaiting for document	Когда указанный процесс не принимает отправку документа.
9	process expired	Когда срок действия указанного процесса истёк.
9	document already set, cannot be modified	Когда процесс уже имеет привязанный документ.
9	process already finished	Когда процесс уже завершён.
9	flow does not allow optional document	Когда документ обязателен для потока, выполняемого процессом.

401 Unauthorized

Сообщение	Описание
Jwt header is an invalid JSON	Когда используемый access-token содержит некорректные символы.
Jwt is expired	Когда используемый access-token истёк.

404 Not Found

Код	Сообщение	Описание
5	error getting process: rpc error: code = NotFound desc = process not found	Когда ID процесса не найден.

429 Too Many Requests

Для данного статуса подробный код ошибки не предоставляется — только HTTP-статус. Лучшие практики см. в разделе 429 Too Many Requests выше.

500 Internal Server Error

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

Что дальше

• После установки документа процесс продолжает свой конвейер. Вызовите Получение процесса для получения результата или дождитесь вебхука.