--- title: 프로세스 생성 description: 검증 프로세스를 생성합니다. Unico에서 호스팅하는 캡처 경험으로 사용자를 안내하는 여정 URL과 SDK 토큰을 반환합니다. canonical: https://developer.unico.io/ko/dual-api/developers/api-reference/web-sdk/post-process locale: ko generated_by: markdown-export --- - [/ko/](/ko/) - [API 레퍼런스](/ko/dual-api/developers/api-reference/) - [Web & 네이티브](/ko/dual-api/developers/api-reference/web-sdk/) - Create Process **이 페이지에서# 프로세스 생성 이것은 모든 Web & SDK 통합의 진입점입니다. 백엔드에서 이를 호출하여 프로세스를 생성하고, 프론트엔드에서 반환된 토큰을 사용하여 iFrame을 렌더링하거나, 사용자를 리디렉션하거나, 네이티브 SDK를 초기화합니다. 전체 통합 플로우는 [Web & SDK 개요](/ko/dual-api/developers/api-reference/web-sdk/)를 참조하세요. ### 엔드포인트​ 환경URL**프로덕션**`POST https://api.idcloud.unico.app/client/v1/process`**샌드박스**`POST https://api.idcloud.uat.unico.app/client/v1/process` ### 요청​ 헤더 헤더값`Authorization``Bearer ` ([인증](/ko/dual-api/developers/api-reference/authentication) 참조)`Content-Type``application/json` 본문 파라미터 필드유형필수설명`callbackUri`string예여정 종료 후 사용자가 리디렉션될 URL. 콜백이 앱 내에서 처리되는 네이티브 SDK 플로우에서는 `/`를 사용하세요.`flow`string예플로우 식별자 - 실행할 기능을 결정합니다. 예: `idunicodocs`, `idunicosign`, `idchecktrust`, `idtoken`, `idsmart`. [사용 가능한 플로우](/ko/dual-api/capabilities/available-flows)를 참조하세요.`purpose`string예비즈니스 목적. 허용 값: `creditprocess`, `biometryonboarding`, `carpurchase`, `ageverification`.`person.duiType`enum아니요문서 유형. 허용 값: `DUI_TYPE_AR_PASSPORT`, `DUI_TYPE_AR_DNI`, `DUI_TYPE_AR_LNC`, `DUI_TYPE_AT_STNR`, `DUI_TYPE_BE_NN`, `DUI_TYPE_BR_CPF`, `DUI_TYPE_BR_PASSPORT`, `DUI_TYPE_BR_CNPJ`, `DUI_TYPE_CA_SIN`, `DUI_TYPE_CH_AHV`, `DUI_TYPE_CL_RUN`, `DUI_TYPE_CL_PASSPORT`, `DUI_TYPE_CL_LICENCIA_CONDUCIR`, `DUI_TYPE_CO_NIT`, `DUI_TYPE_CO_PASSPORT`, `DUI_TYPE_CO_LICENCIA_CONDUCCION`, `DUI_TYPE_CO_CC`, `DUI_TYPE_DE_IDNR`, `DUI_TYPE_DK_CPR`, `DUI_TYPE_EC_NI`, `DUI_TYPE_ES_NIE`, `DUI_TYPE_ES_DNI`, `DUI_TYPE_FI_HETU`, `DUI_TYPE_FR_SPI`, `DUI_TYPE_GB_NINO`, `DUI_TYPE_GT_CUI`, `DUI_TYPE_ID_NIK`, `DUI_TYPE_IE_PPSN`, `DUI_TYPE_IT_CF`, `DUI_TYPE_LU_MATRICULE`, `DUI_TYPE_MX_CURP`, `DUI_TYPE_MX_RFC_PERSONA_FISICA`, `DUI_TYPE_MX_LICENCIA_CONDUCIR`, `DUI_TYPE_NG_NIN`, `DUI_TYPE_NG_BVN`, `DUI_TYPE_NG_BVN_TOKEN`, `DUI_TYPE_NG_NIN_TOKEN`, `DUI_TYPE_NL_BSN`, `DUI_TYPE_NO_FNR`, `DUI_TYPE_PE_RUC`, `DUI_TYPE_PE_DNI`, `DUI_TYPE_PE_PASSPORT`, `DUI_TYPE_PL_PESEL`, `DUI_TYPE_PT_NIF`, `DUI_TYPE_SE_PNR`, `DUI_TYPE_SE_SAMORDNINGSNUMMER`, `DUI_TYPE_TR_TCKN`, `DUI_TYPE_US_SSN`, `DUI_TYPE_US_PASSPORT`, `DUI_TYPE_US_DRIVER_LICENSE`, `DUI_TYPE_US_PASSPORT_CARD`, `DUI_TYPE_US_POLYCARBONATE_PASSPORT`, `DUI_TYPE_US_ID_CARD`, `DUI_TYPE_UY_CI`, `DUI_TYPE_ZZ_EMAIL`, `DUI_TYPE_ZZ_PHONE_NUMBER`.`person.duiValue`string아니요포맷팅 없는 문서 번호.`person.friendlyName`string아니요여정 UI에 표시되는 사용자의 표시 이름. 최대 50자.`person.phone`string아니요DDI + DDD + 번호 형식의 전화번호, 구분자 없이. SMS 또는 WhatsApp으로 알림을 보내는 경우 필수.`person.email`string아니요이메일 주소. 전자 서명이 포함된 플로우에 필수.`person.notifications`array아니요여정 링크를 보내기 위한 알림 채널. 각 항목에는 `notificationChannel`: `NOTIFICATION_CHANNEL_WHATSAPP`, `NOTIFICATION_CHANNEL_SMS` 또는 `NOTIFICATION_CHANNEL_EMAIL`이 있습니다.`bioTokenId`string (UUID)조건부**더 이상 사용되지 않음.** 대신 `references`를 사용하세요. 참조 생체인식 프로세스의 ID. 1:1 검증 플로우 (`idtoken`, `idtokentrust`, `idtokensign`) 및 스마트 재검증 (`idsmart`)에 필수.`references`array조건부`bioTokenId`를 대체하는 1:1 검증 및 스마트 재검증 플로우를 위한 참조 입력. 각 항목에는 `referenceType` (`REFERENCE_TYPE_IMAGE_BASE64` 또는 `REFERENCE_TYPE_PROCESS_ID`)과 `referenceContent` (base64 인코딩 이미지 또는 프로세스 UUID)가 포함됩니다.`useCase`string조건부스마트 재검증 시나리오. `idsmart`에 필수. 예: `USE_CASE_LOGIN`, `USE_CASE_IDENTITY_REVALIDATION_7_DAYS`, `USE_CASE_FIN_TRANSACTIONS`.`clientReference`string조건부귀하의 시스템에서 사용자의 고유 식별자. **[다중 계정](/ko/capabilities/multi-accounts) 기능에 필수입니다.** 기반 내에서 고유해야 하며, 최대 256자, 공백 없음.`companyBranchId`string (UUID)아니요지점 ID. 서비스 계정에 둘 이상의 지점이 연결된 경우에만 필수.`expiresIn`string아니요생성 시점부터의 프로세스 유효 기간. 형식: `"3600s"`. 생략 시 기본값 7일.`flow_config`object아니요플로우별 구성 재정의.`flow_config.biometry_capture.enabled_back_camera`boolean아니요기기의 후면 카메라를 사용합니다. 문서 캡처 또는 전자 서명 플로우와 호환되지 않습니다.`contextualization`object아니요캡처 이유를 설명하기 위해 여정 중 사용자에게 표시되는 거래 컨텍스트.`contextualization.company_name`string아니요여정 중 표시되는 회사 이름. 최대 20자.`contextualization.currency`string아니요사용자에게 표시되는 통화 코드. 허용 값: `BRL`, `MXN`, `USD`.`contextualization.price`number아니요사용자에게 표시되는 거래 금액.`contextualization.locale`object아니요여정 중 표시되는 현지화된 텍스트. 키: `ptBr`, `enUs`, `esMx`.`contextualization.locale.{ptBr|enUs|esMx}.reason`string아니요여정 중 표시되는 짧은 캡처 이유. 최대 50자.`contextualization.locale.{ptBr|enUs|esMx}.title`string아니요여정 중 표시되는 고객 안내의 제목. 최대 100자. `text`와 함께 제공해야 합니다. HTML 태그는 제거됩니다.`contextualization.locale.{ptBr|enUs|esMx}.text`string아니요여정 중 표시되는 고객 안내의 본문. 최대 210자. `title`과 함께 제공해야 합니다. HTML 태그는 제거됩니다. ### 예제​ cURLNode.js``` curl -X POST https://api.idcloud.unico.app/client/v1/process \ -H "Authorization: Bearer $TOKEN" \ -H "Content-Type: application/json" \ -d '{ "callbackUri": "https://app.client.com/callback", "flow": "idunicodocs", "purpose": "biometryonboarding", "person": { "duiType": "DUI_TYPE_BR_CPF", "duiValue": "12345678909", "friendlyName": "Luke Skywalker", "phone": "5511912345678", "email": "luke@example.com" } }' ``` ``` import fetch from 'node-fetch';const res = await fetch('https://api.idcloud.unico.app/client/v1/process', { method: 'POST', headers: { 'Authorization': `Bearer ${process.env.UNICO_ACCESS_TOKEN}`, 'Content-Type': 'application/json' }, body: JSON.stringify({ callbackUri: 'https://app.client.com/callback', flow: 'idunicodocs', purpose: 'biometryonboarding', person: { duiType: 'DUI_TYPE_BR_CPF', duiValue: '12345678909', friendlyName: 'Luke Skywalker', phone: '5511912345678', email: 'luke@example.com' } })});const { process: proc } = await res.json();// proc.userRedirectUrl, proc.token, proc.webAppToken ``` ### 응답​ 200 OK ``` { "process": { "id": "53060f52-f146-4c12-a234-5bb5031f6f5b", "state": "PROCESS_STATE_CREATED", "flow": "idunicosign", "purpose": "biometryonboarding", "callbackUri": "https://app.client.com/callback", "clientReference": "your-internal-id-123", "companyBranchId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890", "userRedirectUrl": "https://cadastro.unico.app/process/53060f52-f146-4c12-a234-5bb5031f6f5b", "token": "eyJhbGciOiJSUzI1NiIs...", "webAppToken": "eyJhbGciOiJSUzI1NiIs...", "createdAt": "2023-10-09T09:15:25.417105Z", "expiresAt": "2023-10-09T16:15:25.417105Z", "capacities": [], "authenticationInfo": {}, "person": { "duiType": "DUI_TYPE_BR_CPF", "duiValue": "12345678909", "friendlyName": "Luke Skywalker", "phone": "5511912345678", "email": "luke@example.com", "notifications": [] }, "companyData": { "branchId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890", "countryCode": "BR" } }} ``` 필드유형설명`process.id`string (UUID)프로세스 식별자. [프로세스 조회](/ko/dual-api/developers/api-reference/web-sdk/get-process)를 통해 결과를 가져오는 데 사용합니다.`process.state`enum`PROCESS_STATE_CREATED` - 프로세스가 생성됨, 여정이 아직 시작되지 않음. `PROCESS_STATE_FAILED` - 프로세스 생성 실패.`process.flow`string생성 시 전송된 플로우 식별자.`process.purpose`string생성 시 전송된 비즈니스 목적.`process.callbackUri`string생성 시 전송된 콜백 URI.`process.clientReference`string생성 시 전송된 내부 식별자. 요청에서 제공된 경우에만 존재합니다.`process.companyBranchId`string (UUID)지점 ID. 요청에서 제공된 경우에만 존재합니다.`process.userRedirectUrl`string사용자를 리디렉션할 URL (Web Redirect 및 iFrame 통합). 이 URL을 수정하지 마세요.`process.token`string**Web SDK iFrame**을 초기화하기 위한 JWT.`process.webAppToken`string**네이티브 SDK** (Android, iOS, Flutter)를 초기화하기 위한 JWT.`process.createdAt`string (date-time)프로세스가 생성된 타임스탬프.`process.expiresAt`string (date-time)프로세스가 만료되어 더 이상 완료할 수 없는 타임스탬프.`process.capacities`array이 프로세스에 구성된 기능.`process.authenticationInfo`object프로세스의 인증 정보 (생성 시에는 비어 있음).`process.person`object생성 시 전송된 `person` 객체의 에코.`process.companyData.branchId`string (UUID)프로세스와 연결된 지점 ID.`process.companyData.countryCode`string지점과 연결된 국가 코드 (예: `BR`, `MX`). ### 오류 코드​ 400 Bad Request401 Unauthorized429 Too Many Requests500 Internal Server Error코드메시지설명`3`invalid flow지정된 플로우가 존재하지 않습니다.`3`invalid person: friendly name exceeds 50 characters.표시 이름이 50자를 초과합니다.`3`invalid purpose제공된 목적이 유효하지 않습니다.`3`invalid callbackUri: unable to parse callbackUri: parse "": empty url, invalid callbackUri: url:제공된 callbackUri가 유효하지 않습니다.`3`invalid person: email required for notification channel NOTIFICATION_CHANNEL_EMAIL, invalid email address for notification channel NOTIFICATION_CHANNEL_EMAIL이메일 알림이 구성되었으나 제공된 이메일이 유효하지 않습니다.`3`invalid person: phone number required for notification channel NOTIFICATION_CHANNEL_WHATSAPP, phone number does not contain 13 chars for notification channel NOTIFICATION_CHANNEL_WHATSAPPSMS 또는 WhatsApp 알림이 구성되었으나 제공된 전화번호가 유효하지 않습니다.`3`idnsv2/GetPublicID request error: rpc error: code = InvalidArgument desc = invalid dui value제공된 식별자 (duiValue)가 유효하지 않습니다.`3`invalid expiresIn argument`expiresIn` 값이 유효하지 않습니다.`3`invalid company_name argument in process contextualization, max length is 20`contextualization.company_name`이 20자를 초과하는 경우.`3`title and text must be provided together in process contexts로케일에서 `title` 또는 `text` 중 하나만 제공된 경우.`3`invalid title argument in process contexts, max length is 100로케일 `title`이 100자를 초과하는 경우.`3`invalid text argument in process contexts, max length is 210로케일 `text`가 210자를 초과하는 경우.`3`invalid reason argument in process contexts, max length is 50로케일 `reason`이 50자를 초과하는 경우.`9`XX ID Apikeys are not setAPI Key가 올바르게 구성되지 않았습니다.Bearer 토큰이 누락되었거나, 만료되었거나, 유효하지 않습니다. [인증](/ko/dual-api/developers/api-reference/authentication)을 참조하세요.메시지설명Jwt header is an invalid JSON사용된 액세스 토큰에 잘못된 문자가 포함되어 있습니다.Jwt is expired사용된 액세스 토큰이 만료되었습니다.속도 제한에 도달했습니다. 시스템이 HTTP 429 오류를 수신하면 연쇄 장애를 방지하고 제한을 악화시키지 않기 위한 메커니즘을 구현해야 합니다.**모범 사례:** **쿨다운 기간 (백오프):** 시스템에서 후속 요청을 즉시 중지하거나 조절하세요. 실패한 요청을 타이트한 루프에서 지속적으로 재시도하지 마세요. **큐잉 및 조절:** 발신 요청을 버퍼링하거나 큐에 넣어 다시 보내기 전에 트래픽 흐름을 제어하세요. **지터를 포함한 지수 백오프:** 재시도할 때 시도 간 대기 시간을 지수적으로 늘리고 (예: 1초, 2초, 4초, 8초) 작은 랜덤 지연("지터")을 추가하여 큐에 있는 모든 요청이 정확히 같은 밀리초에 재시도하는 허드 효과를 방지하세요. 경고백오프 없이 속도 제한된 엔드포인트에 지속적으로 요청하면 **제한 기간이 연장**되고 시스템의 운영 처리량에 심각한 영향을 줄 수 있습니다. 요청을 적절히 조절하면 더 부드럽고 탄력적인 통합을 보장할 수 있습니다.기본 제한, 요청 증가 및 추가 세부사항은 [속도 제한](/ko/dual-api/developers/api-reference/rate-limits)을 참조하세요.코드메시지설명`99999`Internal failure! Try again later내부 오류가 발생했습니다. ### 다음 단계​ 사용자가 여정을 완료한 후 [프로세스 조회](/ko/dual-api/developers/api-reference/web-sdk/get-process)를 호출하여 결과를 가져오거나 [웹훅](/ko/developers/webhooks-and-events)을 기다리세요. 모든 레시피 조합과 가능한 결과 값을 확인하려면 [플로우](/ko/dual-api/developers/api-reference/web-sdk/flows)를 참조하세요. 마지막 업데이트 2026년 10월 8일**에