프로세스 생성

이것은 모든 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.
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) 및 Smart Revalidation(idsmart)에 필수.
references	array	조건부	1:1 검증 및 Smart Revalidation 플로우를 위한 참조 입력으로, bioTokenId를 대체합니다. 각 항목에는 referenceType(REFERENCE_TYPE_IMAGE_BASE64 또는 REFERENCE_TYPE_PROCESS_ID)과 referenceContent(base64 인코딩된 이미지 또는 프로세스 UUID)가 포함됩니다.
useCase	string	조건부	Smart Revalidation 사용 사례. 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.currency	string	아니오	사용자에게 표시되는 통화 코드. 허용 값: BRL, MXN, USD.
contextualization.price	number	아니오	사용자에게 표시되는 트랜잭션 금액.
contextualization.locale	object	아니오	현지화된 이유 텍스트. 키: ptBr, enUs, esMx — 각각 여정 중 표시되는 reason 문자열 포함.

예시

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 리디렉션 및 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

요청 한도에 도달했습니다. 응답 헤더에 표시된 간격 후 재시도하세요.

오류 코드

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 값이 유효하지 않을 때.
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 상태만 제공됩니다.

500 Internal Server Error

코드	메시지	설명
99999	Internal failure! Try again later	내부 오류가 발생한 경우.

다음 단계

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