프로세스 문서 설정POST

문서 없이 프로세스를 생성하고, 사용자가 캡처를 완료하게 한 다음, 백엔드에서 문서를 전송합니다. 그 후 프로세스가 완료됩니다.

MarkdownChatGPTClaude

생명주기

1. 백엔드가 프로세스 생성으로 person.duiType과 person.duiValue 없이 프로세스를 생성합니다. flow가 선택적 문서를 허용해야 합니다. 프로세스는 PROCESS_STATE_CREATED 상태로 시작합니다.
2. 사용자가 여정을 진행하고 캡처를 수행합니다.
3. Unico API가 프로세스를 AWAITING_FOR_DOCUMENT로 전환합니다. 이는 프로세스가 문서를 기다리는 동안 프로세스 조회가 반환하는 상태입니다. 이 시점에서 이미 duiValue에 의존하지 않는 기능의 부분 결과를 읽을 수 있습니다.
4. 백엔드가 URL에 프로세스 ID를, 본문에 문서를 담아 이 엔드포인트를 호출합니다. 그러면 Unico API가 프로세스를 완료하고, 프로세스는 PROCESS_STATE_FINISHED로 전환됩니다.

응답에는 최종 결과가 포함되지 않습니다

최종 상태와 결과는 프로세스 조회로 읽거나 webhook을 기다리세요.

엔드포인트

환경	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 (UUID)	예	프로세스 생성에서 반환된 프로세스 식별자입니다.

본문 매개변수

필드	타입	필수	설명
duiType	enum	예	문서 유형입니다. DUI_TYPE_UNSPECIFIED는 거부됩니다. 아래의 duiType 값을 참조하세요.
duiValue	string	예	서식 없는 문서 번호입니다. 최대 320자입니다.

duiType 값

국가	값	설명
AR	DUI_TYPE_AR_PASSPORT	아르헨티나 여권
AR	DUI_TYPE_AR_DNI	아르헨티나 DNI
AR	DUI_TYPE_AR_LNC	아르헨티나 운전면허증(Licencia Nacional de Conducir)
AT	DUI_TYPE_AT_STNR	오스트리아 납세자 번호(STNR)
BE	DUI_TYPE_BE_NN	벨기에 국민 번호(NN)
BR	DUI_TYPE_BR_CPF	브라질 CPF
BR	DUI_TYPE_BR_PASSPORT	브라질 여권
BR	DUI_TYPE_BR_CNPJ	브라질 CNPJ
CA	DUI_TYPE_CA_SIN	캐나다 SIN
CH	DUI_TYPE_CH_AHV	스위스 AHV/AVS 번호
CL	DUI_TYPE_CL_RUN	칠레 RUN
CL	DUI_TYPE_CL_PASSPORT	칠레 여권
CL	DUI_TYPE_CL_LICENCIA_CONDUCIR	칠레 운전면허증(Licencia de Conducir)
CO	DUI_TYPE_CO_NIT	콜롬비아 NIT
CO	DUI_TYPE_CO_PASSPORT	콜롬비아 여권
CO	DUI_TYPE_CO_LICENCIA_CONDUCCION	콜롬비아 운전면허증(Licencia de Conducción)
CO	DUI_TYPE_CO_CC	콜롬비아 시민증(Cédula de Ciudadanía)
DE	DUI_TYPE_DE_IDNR	독일 세무 식별 번호(IdNr)
DK	DUI_TYPE_DK_CPR	덴마크 CPR
EC	DUI_TYPE_EC_NI	에콰도르 NI
ES	DUI_TYPE_ES_NIE	스페인 외국인 식별 번호(NIE)
ES	DUI_TYPE_ES_DNI	스페인 국민 신분증(DNI)
FI	DUI_TYPE_FI_HETU	핀란드 개인 식별 번호(HETU)
FR	DUI_TYPE_FR_SPI	프랑스 세무 참조 번호(SPI)
GB	DUI_TYPE_GB_NINO	영국 국민보험번호(NINO)
GT	DUI_TYPE_GT_CUI	과테말라 CUI
ID	DUI_TYPE_ID_NIK	인도네시아 NIK
IE	DUI_TYPE_IE_PPSN	아일랜드 개인 공공 서비스 번호(PPSN)
IT	DUI_TYPE_IT_CF	이탈리아 세무 번호(CF)
LK	DUI_TYPE_LK_NIC	스리랑카 NIC
LU	DUI_TYPE_LU_MATRICULE	룩셈부르크 국민 식별 번호(Matricule)
MX	DUI_TYPE_MX_CURP	멕시코 CURP
MX	DUI_TYPE_MX_RFC_PERSONA_FISICA	멕시코 RFC(개인)
MX	DUI_TYPE_MX_LICENCIA_CONDUCIR	멕시코 운전면허증(Licencia de Conducir)
NG	DUI_TYPE_NG_NIN	나이지리아 NIN
NG	DUI_TYPE_NG_BVN	나이지리아 은행 인증 번호(BVN)
NG	DUI_TYPE_NG_BVN_TOKEN	나이지리아 BVN 토큰(해시)
NG	DUI_TYPE_NG_NIN_TOKEN	나이지리아 NIN 토큰(해시)
NL	DUI_TYPE_NL_BSN	네덜란드 시민 서비스 번호(BSN)
NO	DUI_TYPE_NO_FNR	노르웨이 국민 식별 번호(Fødselsnummer)
PE	DUI_TYPE_PE_RUC	페루 RUC
PE	DUI_TYPE_PE_DNI	페루 DNI
PE	DUI_TYPE_PE_PASSPORT	페루 여권
PL	DUI_TYPE_PL_PESEL	폴란드 PESEL
PT	DUI_TYPE_PT_NIF	포르투갈 납세자 번호(NIF)
SE	DUI_TYPE_SE_PNR	스웨덴 개인번호(PNR)
SE	DUI_TYPE_SE_SAMORDNINGSNUMMER	스웨덴 조정 번호(Samordningsnummer)
TR	DUI_TYPE_TR_TCKN	튀르키예 국민 식별 번호(TCKN)
US	DUI_TYPE_US_SSN	미국 SSN
US	DUI_TYPE_US_PASSPORT	미국 여권
US	DUI_TYPE_US_DRIVER_LICENSE	미국 운전면허증
US	DUI_TYPE_US_PASSPORT_CARD	미국 여권 카드
US	DUI_TYPE_US_POLYCARBONATE_PASSPORT	미국 폴리카보네이트 여권
US	DUI_TYPE_US_ID_CARD	미국 ID 카드
UY	DUI_TYPE_UY_CI	우루과이 CI
ZZ	DUI_TYPE_ZZ_EMAIL	이메일 주소
ZZ	DUI_TYPE_ZZ_PHONE_NUMBER	전화번호

호출이 수락되는 조건

• 프로세스가 AWAITING_FOR_DOCUMENT 상태입니다: 사용자가 이미 캡처를 완료했습니다.
• 프로세스가 만료되지 않았습니다.
• flow가 선택적 문서를 허용합니다.

문서는 변경할 수 없습니다. 프로세스가 더 이상 문서를 기다리지 않으므로 두 번째 호출은 실패합니다.

예제

cURL

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

Node.js

import fetch from 'node-fetch';

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

응답

200 OK

{
  "processId": "3116552c-6a3e-4c1f-9d2b-8f0e7a5b4c21",
  "duiType": "DUI_TYPE_BR_CPF",
  "duiValue": "12345678909"
}

필드	타입	설명
processId	string (UUID)	프로세스 식별자입니다.
duiType	enum	프로세스에 등록된 문서 유형입니다.
duiValue	string	프로세스에 등록된 문서 번호입니다.

예제 값은 자리 표시자입니다.

오류 코드

400 Bad Request

코드	설명
3	processId가 누락되었거나 유효하지 않거나, duiType이 지정되지 않았거나, duiValue가 비어 있거나 320자를 초과합니다.
9	프로세스가 문서를 기다리고 있지 않거나(이미 문서가 설정된 경우 포함), 만료되었거나 완료되었거나, flow가 선택적 문서를 허용하지 않습니다.

401 Unauthorized

코드	메시지	설명
—	Jwt header is an invalid JSON	사용된 액세스 토큰에 잘못된 문자가 포함된 경우입니다.
—	Jwt is expired	사용된 액세스 토큰이 만료된 경우입니다.

403 Forbidden

코드	설명
7	자격 증명에 프로세스 생성에 필요한 권한이 없습니다.

404 Not Found

코드	설명
5	프로세스가 존재하지 않거나 귀사에 속하지 않습니다.

429 Too Many Requests

레이트 리밋에 도달했습니다. 시스템이 HTTP 429 오류를 수신하면 연쇄적인 장애를 방지하고 제한이 악화되지 않도록 메커니즘을 구현해야 합니다.

모범 사례:

• 쿨다운 기간(backoff): 시스템에서 후속 요청을 즉시 중지하거나 줄이세요. 실패한 요청을 촘촘한 루프에서 지속적으로 재시도하지 마세요.
• 큐잉 및 스로틀링(Queueing & throttling): 재전송하기 전에 발신 요청을 버퍼링하거나 대기열에 넣어 트래픽 흐름을 제어하세요.
• 지터를 포함한 지수 백오프(Exponential backoff with jitter): 재시도 시 시도 간 대기 시간을 기하급수적으로 늘리고(예: 1초, 2초, 4초, 8초) 작은 무작위 지연("지터")을 추가하여 대기열의 모든 요청이 정확히 같은 밀리초에 재시도하는 허드 효과를 방지하세요.

경고

백오프 없이 레이트 리밋이 적용된 엔드포인트에 지속적으로 요청을 보내면 제한 기간이 연장되고 시스템의 운영 처리량에 심각한 영향을 미칠 수 있습니다. 요청을 적절히 스로틀링하면 더 원활하고 탄력적인 통합이 보장됩니다.

기본 제한, 요청 증가 및 추가 세부 정보는 레이트 리밋을 참조하세요.

500 Internal Server Error

코드	설명
13	문서를 저장할 수 없습니다.

참고

문서는 저장되기 전에 신원 서비스에 등록됩니다. 해당 등록이 실패하면 호출은 그 실패의 상태를 반환합니다.

다음 단계

• 최종 상태와 결과를 읽으려면 프로세스 조회를 참조하세요.
• 프로세스가 완료될 때 알림을 받으려면 Webhooks and Events를 참조하세요.