프로세스 생성

이것은 모든 Web & SDK 통합의 진입점입니다. 백엔드에서 이를 호출하여 프로세스를 생성하고, 프론트엔드에서 반환된 토큰을 사용하여 iFrame을 렌더링하거나, 사용자를 리디렉션하거나, 네이티브 SDK를 초기화합니다.

전체 통합 플로우는 Web & SDK 개요를 참조하세요.

엔드포인트

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

요청

헤더

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

본문 파라미터

필드	유형	필수	설명
callbackUri	string	예	여정 종료 후 사용자가 리디렉션될 URL. 콜백이 앱 내에서 처리되는 네이티브 SDK 플로우에서는 /를 사용하세요.
flow	string	예	플로우 식별자 - 실행할 기능을 결정합니다. 예: idunicodocs, idunicosign, idchecktrust, idtoken, idsmart. 사용 가능한 플로우를 참조하세요.
purpose	string	예	비즈니스 목적. 허용 값: creditprocess, biometryonboarding, carpurchase, ageverification.
person.duiType	enum	예	문서 유형. 허용 값: DUI_TYPE_BR_CPF, DUI_TYPE_MX_CURP, DUI_TYPE_US_SSN, DUI_TYPE_BR_PASSPORT, DUI_TYPE_AR_PASSPORT, DUI_TYPE_AR_DNI, DUI_TYPE_NG_NIN, DUI_TYPE_CL_RUN, DUI_TYPE_EC_NI, DUI_TYPE_US_PASSPORT, DUI_TYPE_GT_CUI, DUI_TYPE_UY_CI, DUI_TYPE_ZZ_EMAIL, DUI_TYPE_ID_NIK, DUI_TYPE_ZZ_PHONE_NUMBER, DUI_TYPE_US_DRIVER_LICENSE, DUI_TYPE_NG_BVN, DUI_TYPE_MX_RFC_PERSONA_FISICA, DUI_TYPE_CO_NIT, DUI_TYPE_PE_RUC, DUI_TYPE_CA_SIN, DUI_TYPE_DK_CPR, DUI_TYPE_GB_NINO, DUI_TYPE_PL_PESEL, DUI_TYPE_SE_PNR, DUI_TYPE_AT_STNR, DUI_TYPE_FI_HETU.
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	아니요	이 프로세스에 대한 내부 식별자 (포털에서 교차 참조를 위한 외래 키).
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 태그는 제거됩니다.

예제

cURL

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": "[email protected]"
    }
  }'

Node.js

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: '[email protected]'
    }
  })
});

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": "[email protected]",
      "notifications": []
    },
    "companyData": {
      "branchId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
      "countryCode": "BR"
    }
  }
}

필드	유형	설명
process.id	string (UUID)	프로세스 식별자. 프로세스 조회를 통해 결과를 가져오는 데 사용합니다.
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 Request

요청 페이로드의 형식이 잘못되었거나, 필수 필드가 누락되었거나, flow 값을 인식할 수 없는 경우 반환됩니다.

401 Unauthorized

Bearer 토큰이 누락되었거나, 만료되었거나, 유효하지 않습니다. 인증을 참조하세요.

429 Too Many Requests

속도 제한에 도달했습니다. 시스템이 HTTP 429 오류를 수신하면 연쇄 장애를 방지하고 제한을 악화시키지 않기 위한 메커니즘을 구현해야 합니다.

모범 사례:

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

경고

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

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

오류 코드

400 Bad Request

코드	메시지	설명
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_WHATSAPP	SMS 또는 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 set	API Key가 올바르게 구성되지 않았습니다.

401 Unauthorized

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

429 Too Many Requests

이 상태에 대한 상세 오류 코드는 제공되지 않습니다 — HTTP 상태만 제공됩니다. 모범 사례는 위의 429 Too Many Requests 섹션을 참조하세요.

500 Internal Server Error

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

다음 단계

• 사용자가 여정을 완료한 후 프로세스 조회를 호출하여 결과를 가져오거나 웹훅을 기다리세요.