메인 콘텐츠로 건너뛰기

프로세스 생성

이것은 모든 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

요청​

헤더
헤더값
AuthorizationBearer <access_token> (인증 참조)
Content-Typeapplication/json
본문 파라미터
필드유형필수설명
callbackUristring예여정 종료 후 사용자가 리디렉션될 URL. 콜백이 앱 내에서 처리되는 네이티브 SDK 플로우에서는 /를 사용하세요.
flowstring예플로우 식별자 - 실행할 기능을 결정합니다. 예: idunicodocs, idunicosign, idchecktrust, idtoken, idsmart. 사용 가능한 플로우를 참조하세요.
purposestring예비즈니스 목적. 허용 값: creditprocess, biometryonboarding, carpurchase, ageverification.
person.duiTypeenum아니요문서 유형. 허용 값: DUI_TYPE_BR_CPF, DUI_TYPE_MX_CURP, DUI_TYPE_US_SSN, DUI_TYPE_BR_PASSPORT, DUI_TYPE_BR_CNPJ, DUI_TYPE_AR_PASSPORT, DUI_TYPE_AR_DNI, DUI_TYPE_AR_LNC, DUI_TYPE_NG_NIN, DUI_TYPE_CL_RUN, DUI_TYPE_CL_PASSPORT, DUI_TYPE_CL_LICENCIA_CONDUCIR, 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_US_PASSPORT_CARD, DUI_TYPE_US_POLYCARBONATE_PASSPORT, DUI_TYPE_US_ID_CARD, DUI_TYPE_NG_BVN, DUI_TYPE_NG_BVN_TOKEN, DUI_TYPE_NG_NIN_TOKEN, DUI_TYPE_MX_RFC_PERSONA_FISICA, DUI_TYPE_MX_LICENCIA_CONDUCIR, DUI_TYPE_CO_NIT, DUI_TYPE_CO_PASSPORT, DUI_TYPE_CO_LICENCIA_CONDUCCION, DUI_TYPE_CO_CC, DUI_TYPE_PE_RUC, DUI_TYPE_PE_DNI, DUI_TYPE_PE_PASSPORT, DUI_TYPE_CA_SIN, DUI_TYPE_DK_CPR, DUI_TYPE_GB_NINO, DUI_TYPE_PL_PESEL, DUI_TYPE_SE_PNR, DUI_TYPE_SE_SAMORDNINGSNUMMER, DUI_TYPE_AT_STNR, DUI_TYPE_CH_AHV, DUI_TYPE_FI_HETU, DUI_TYPE_NO_FNR, DUI_TYPE_DE_IDNR, DUI_TYPE_NL_BSN, DUI_TYPE_BE_NN, DUI_TYPE_IT_CF, DUI_TYPE_TR_TCKN, DUI_TYPE_PT_NIF, DUI_TYPE_FR_SPI, DUI_TYPE_IE_PPSN, DUI_TYPE_LU_MATRICULE, DUI_TYPE_ES_NIE, DUI_TYPE_ES_DNI.
person.duiValuestring아니요포맷팅 없는 문서 번호.
person.friendlyNamestring아니요여정 UI에 표시되는 사용자의 표시 이름. 최대 50자.
person.phonestring아니요DDI + DDD + 번호 형식의 전화번호, 구분자 없이. SMS 또는 WhatsApp으로 알림을 보내는 경우 필수.
person.emailstring아니요이메일 주소. 전자 서명이 포함된 플로우에 필수.
person.notificationsarray아니요여정 링크를 보내기 위한 알림 채널. 각 항목에는 notificationChannel: NOTIFICATION_CHANNEL_WHATSAPP, NOTIFICATION_CHANNEL_SMS 또는 NOTIFICATION_CHANNEL_EMAIL이 있습니다.
bioTokenIdstring (UUID)조건부더 이상 사용되지 않음. 대신 references를 사용하세요. 참조 생체인식 프로세스의 ID. 1:1 검증 플로우 (idtoken, idtokentrust, idtokensign) 및 스마트 재검증 (idsmart)에 필수.
referencesarray조건부bioTokenId를 대체하는 1:1 검증 및 스마트 재검증 플로우를 위한 참조 입력. 각 항목에는 referenceType (REFERENCE_TYPE_IMAGE_BASE64 또는 REFERENCE_TYPE_PROCESS_ID)과 referenceContent (base64 인코딩 이미지 또는 프로세스 UUID)가 포함됩니다.
useCasestring조건부스마트 재검증 시나리오. idsmart에 필수. 예: USE_CASE_LOGIN, USE_CASE_IDENTITY_REVALIDATION_7_DAYS, USE_CASE_FIN_TRANSACTIONS.
clientReferencestring조건부귀하의 시스템에서 사용자의 고유 식별자. 다중 계정 기능에 필수입니다. 기반 내에서 고유해야 하며, 최대 256자, 공백 없음.
companyBranchIdstring (UUID)아니요지점 ID. 서비스 계정에 둘 이상의 지점이 연결된 경우에만 필수.
expiresInstring아니요생성 시점부터의 프로세스 유효 기간. 형식: "3600s". 생략 시 기본값 7일.
flow_configobject아니요플로우별 구성 재정의.
flow_config.biometry_capture.enabled_back_cameraboolean아니요기기의 후면 카메라를 사용합니다. 문서 캡처 또는 전자 서명 플로우와 호환되지 않습니다.
contextualizationobject아니요캡처 이유를 설명하기 위해 여정 중 사용자에게 표시되는 거래 컨텍스트.
contextualization.company_namestring아니요여정 중 표시되는 회사 이름. 최대 20자.
contextualization.currencystring아니요사용자에게 표시되는 통화 코드. 허용 값: BRL, MXN, USD.
contextualization.pricenumber아니요사용자에게 표시되는 거래 금액.
contextualization.localeobject아니요여정 중 표시되는 현지화된 텍스트. 키: ptBr, enUs, esMx.
contextualization.locale.{ptBr|enUs|esMx}.reasonstring아니요여정 중 표시되는 짧은 캡처 이유. 최대 50자.
contextualization.locale.{ptBr|enUs|esMx}.titlestring아니요여정 중 표시되는 고객 안내의 제목. 최대 100자. text와 함께 제공해야 합니다. HTML 태그는 제거됩니다.
contextualization.locale.{ptBr|enUs|esMx}.textstring아니요여정 중 표시되는 고객 안내의 본문. 최대 210자. title과 함께 제공해야 합니다. HTML 태그는 제거됩니다.

예제​

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]"
    }
  }'

응답​

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.idstring (UUID)프로세스 식별자. 프로세스 조회를 통해 결과를 가져오는 데 사용합니다.
process.stateenumPROCESS_STATE_CREATED - 프로세스가 생성됨, 여정이 아직 시작되지 않음. PROCESS_STATE_FAILED - 프로세스 생성 실패.
process.flowstring생성 시 전송된 플로우 식별자.
process.purposestring생성 시 전송된 비즈니스 목적.
process.callbackUristring생성 시 전송된 콜백 URI.
process.clientReferencestring생성 시 전송된 내부 식별자. 요청에서 제공된 경우에만 존재합니다.
process.companyBranchIdstring (UUID)지점 ID. 요청에서 제공된 경우에만 존재합니다.
process.userRedirectUrlstring사용자를 리디렉션할 URL (Web Redirect 및 iFrame 통합). 이 URL을 수정하지 마세요.
process.tokenstringWeb SDK iFrame을 초기화하기 위한 JWT.
process.webAppTokenstring네이티브 SDK (Android, iOS, Flutter)를 초기화하기 위한 JWT.
process.createdAtstring (date-time)프로세스가 생성된 타임스탬프.
process.expiresAtstring (date-time)프로세스가 만료되어 더 이상 완료할 수 없는 타임스탬프.
process.capacitiesarray이 프로세스에 구성된 기능.
process.authenticationInfoobject프로세스의 인증 정보 (생성 시에는 비어 있음).
process.personobject생성 시 전송된 person 객체의 에코.
process.companyData.branchIdstring (UUID)프로세스와 연결된 지점 ID.
process.companyData.countryCodestring지점과 연결된 국가 코드 (예: BR, MX).

오류 코드​

코드메시지설명
3invalid flow지정된 플로우가 존재하지 않습니다.
3invalid person: friendly name exceeds 50 characters.표시 이름이 50자를 초과합니다.
3invalid purpose제공된 목적이 유효하지 않습니다.
3invalid callbackUri: unable to parse callbackUri: parse "": empty url, invalid callbackUri: url:제공된 callbackUri가 유효하지 않습니다.
3invalid person: email required for notification channel NOTIFICATION_CHANNEL_EMAIL, invalid email address for notification channel NOTIFICATION_CHANNEL_EMAIL이메일 알림이 구성되었으나 제공된 이메일이 유효하지 않습니다.
3invalid person: phone number required for notification channel NOTIFICATION_CHANNEL_WHATSAPP, phone number does not contain 13 chars for notification channel NOTIFICATION_CHANNEL_WHATSAPPSMS 또는 WhatsApp 알림이 구성되었으나 제공된 전화번호가 유효하지 않습니다.
3idnsv2/GetPublicID request error: rpc error: code = InvalidArgument desc = invalid dui value제공된 식별자 (duiValue)가 유효하지 않습니다.
3invalid expiresIn argumentexpiresIn 값이 유효하지 않습니다.
3invalid company_name argument in process contextualization, max length is 20contextualization.company_name이 20자를 초과하는 경우.
3title and text must be provided together in process contexts로케일에서 title 또는 text 중 하나만 제공된 경우.
3invalid title argument in process contexts, max length is 100로케일 title이 100자를 초과하는 경우.
3invalid text argument in process contexts, max length is 210로케일 text가 210자를 초과하는 경우.
3invalid reason argument in process contexts, max length is 50로케일 reason이 50자를 초과하는 경우.
9XX ID Apikeys are not setAPI Key가 올바르게 구성되지 않았습니다.

다음 단계​

  • 사용자가 여정을 완료한 후 프로세스 조회를 호출하여 결과를 가져오거나 웹훅을 기다리세요.
  • 모든 레시피 조합과 가능한 결과 값을 확인하려면 플로우를 참조하세요.
마지막 업데이트 에