프로세스 문서 설정

문서 없이 생성된 프로세스에 신분 증명 문서 (CPF, CURP, SSN 또는 기타 duiType)를 설정합니다. 설정 후 문서는 변경할 수 없습니다.

Custom Flow에서 문서 없이 생성을 허용하는 프로세스에만 사용할 수 있습니다. 즉, AWAITING_FOR_DOCUMENT 상태의 프로세스입니다.

엔드포인트

환경	URL
프로덕션	`POST https://api.idcloud.unico.app/client/v1/process/{processId}/document`
샌드박스	`POST https://api.idcloud.uat.unico.app/client/v1/process/{processId}/document`

요청

헤더

헤더	값
`Authorization`	`Bearer <access_token>` (인증 참조)
`Content-Type`	`application/json`

경로 파라미터

필드	유형	필수	설명
`processId`	string	예	생성 시 `process.id`로 반환된 프로세스 ID.

본문 파라미터

필드	유형	필수	설명
`duiType`	enum	예	문서 유형. 값: `DUI_TYPE_BR_CPF`, `DUI_TYPE_MX_CURP`, `DUI_TYPE_US_SSN`. 이 엔드포인트는 프로세스 생성에서 허용하는 문서 유형의 하위 집합을 지원합니다. 선택적 문서 생성을 허용하는 Custom Flow는 현재 이 좁은 목록에 대해 검증됩니다.
`duiValue`	string	예	포맷팅 없는 문서 번호. 최대 320자 (인코딩되거나 복합 식별자를 수용합니다; CPF 또는 CURP와 같은 표준 문서 번호는 훨씬 짧습니다).

예제

cURL
Node.js

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"
  }'

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 오류를 수신하면 연쇄 장애를 방지하고 제한을 악화시키지 않기 위한 메커니즘을 구현해야 합니다.

모범 사례:

쿨다운 기간 (백오프): 시스템에서 후속 요청을 즉시 중지하거나 조절하세요. 실패한 요청을 타이트한 루프에서 지속적으로 재시도하지 마세요.
큐잉 및 조절: 발신 요청을 버퍼링하거나 큐에 넣어 다시 보내기 전에 트래픽 흐름을 제어하세요.
지터를 포함한 지수 백오프: 재시도할 때 시도 간 대기 시간을 지수적으로 늘리고 (예: 1초, 2초, 4초, 8초) 작은 랜덤 지연("지터")을 추가하여 큐에 있는 모든 요청이 정확히 같은 밀리초에 재시도하는 허드 효과를 방지하세요.

경고

백오프 없이 속도 제한된 엔드포인트에 지속적으로 요청하면 제한 기간이 연장되고 시스템의 운영 처리량에 심각한 영향을 줄 수 있습니다. 요청을 적절히 조절하면 더 부드럽고 탄력적인 통합을 보장할 수 있습니다.

기본 제한, 요청 증가 및 추가 세부사항은 속도 제한을 참조하세요.

오류 코드

400 Bad Request
401 Unauthorized
404 Not Found
429 Too Many Requests
500 Internal Server Error

코드	메시지	설명
`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`	프로세스에서 실행하는 플로우에서 문서가 필수입니다.

메시지	설명
Jwt header is an invalid JSON	사용된 액세스 토큰에 잘못된 문자가 포함되어 있습니다.
Jwt is expired	사용된 액세스 토큰이 만료되었습니다.

코드	메시지	설명
`5`	`error getting process: rpc error: code = NotFound desc = process not found`	프로세스 ID를 찾을 수 없습니다.

코드	메시지	설명
`99999`	`Internal failure! Try again later`	내부 오류가 발생했습니다.

다음 단계

문서를 설정한 후 프로세스는 파이프라인을 계속합니다. 프로세스 조회를 호출하여 결과를 가져오거나 웹훅을 기다리세요.

엔드포인트​

요청​

예제​

응답​

오류 코드​

다음 단계​

엔드포인트

요청

예제

응답

오류 코드

다음 단계