프로세스 문서 설정

문서 없이 생성된 프로세스에 신원 확인 문서(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

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 상태만 제공됩니다.

오류 코드

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	사용된 액세스 토큰에 잘못된 문자가 포함된 경우.
Jwt is expired	사용된 액세스 토큰이 만료된 경우.

404 Not Found

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

429 Too Many Requests

이 상태에 대한 상세 오류 코드가 제공되지 않습니다 — HTTP 상태 코드만 제공됩니다.

500 Internal Server Error

코드	메시지	설명
99999	Internal failure! Try again later	내부 오류가 발생했을 때.

다음 단계

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