프로세스 생성

이 엔드포인트는 동일한 경로를 공유하지만 본문 파라미터, 기능 및 응답 필드가 다른 두 가지 유스케이스를 처리합니다:

• 온보딩 - Unico의 신원 데이터베이스와 얼굴을 비교하여 사용자가 누구인지 검증합니다 (subject.duiType + subject.code 필수).
• 트랜잭션 - 이전 프로세스의 얼굴과 비교하여 동일 인물인지 확인합니다 (referenceProcessId 또는 셀피/프로세스 ID가 포함된 references 배열 필수).

활성 유스케이스는 요청 헤더에 전송된 APIKEY에 의해 결정됩니다.

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

엔드포인트

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

요청

헤더

헤더	값
Authorization	Bearer <access_token> (인증 참조)
APIKEY	프로비저닝된 API 키 - 활성 유스케이스와 활성화된 기능을 정의합니다.
Content-Type	application/json

본문 파라미터

온보딩

필드	유형	필수	설명
subject.duiType	integer	예	문서 유형 식별자. 아래 duiType 값을 참조하세요.
subject.code	string	예	subject.duiType에 정의된 식별자 값. 점이나 대시 없이 입력하세요.
subject.name	string	아니요	전체 이름.
subject.gender	string	아니요	M 또는 F.
subject.birthDate	string (ISO 8601)	아니요	생년월일 (YYYY-MM-DD).
subject.email	string	아니요	이메일 주소.
subject.phone	string	아니요	E.164 전화번호.
useCase	string	아니요	작업 컨텍스트, 예: Onboarding.
subsidiaryId	string	아니요	지점 ID — 여러 지점이 있는 경우에만 필요합니다.
imageBase64	string	예	프론트엔드에서 캡처한 셀피, base64 형식.

트랜잭션

필드	유형	필수	설명
references	array	조건부	1:1 검증 플로우를 위한 참조 입력. 각 항목에는 referenceType (REFERENCE_TYPE_IMAGE_BASE64 또는 REFERENCE_TYPE_PROCESS_ID)과 referenceContent (base64 인코딩 이미지 또는 프로세스 UUID)가 포함됩니다.
referenceProcessId	string	조건부	더 이상 사용되지 않음. 대신 references를 사용하세요. 비교할 참조 온보딩 프로세스의 ID. 참조가 by-Unico 프로세스인 경우 authenticationInfo.authenticationId를 사용하세요.
imageBase64	string	예	프론트엔드에서 캡처한 셀피, base64 형식.
subject	object	아니요	사용자 정보 컨테이너.
subject.duiType	string	아니요	식별자 유형. 가능한 값: DUI_TYPE_BR_CPF, DUI_TYPE_MX_CURP, DUI_TYPE_US_SSN, DUI_TYPE_NG_NIN, DUI_TYPE_AR_DNI, DUI_TYPE_ID_NIK.
subject.code	string	아니요	subject.duiType에 정의된 식별자 값. 점이나 대시 없이 입력하세요.
subject.name	string	아니요	사용자의 전체 이름.
subject.gender	string	아니요	M 또는 F.
subject.birthDate	string (ISO 8601)	아니요	생년월일 (YYYY-MM-DD).
subject.email	string	아니요	이메일 주소.
subject.phone	string	아니요	E.164 전화번호.
useCase	string	아니요	작업 컨텍스트, 예: Transactional.
subsidiaryId	string	아니요	지점 ID - 여러 지점이 있는 경우에만 필수.

정보

이 유스케이스에서는 위험 점수와 오케스트레이션이 불가능합니다. 결과는 항상 POST 응답에서 동기적으로 반환됩니다.

duiType 값

국가	코드	설명
BR	1	브라질 CPF
BR	5	브라질 여권
MX	2	멕시코 CURP
AR	6	아르헨티나 여권
AR	7	아르헨티나 DNI
US	4	미국 SSN
US	11	미국 여권
US	18	미국 운전면허증
ID	16	인도네시아 NIK
NG	8	나이지리아 NIN
CL	9	칠레 RUN
EC	10	에콰도르 NI
GT	12	과테말라 CUI
UY	13	우루과이 CI
ZZ	15	이메일 주소
ZZ	17	전화번호
MX	25	멕시코 RFC(개인)
CO	26	콜롬비아 NIT
PE	27	페루 RUC
CA	28	캐나다 SIN
DK	29	덴마크 CPR
GB	30	영국 국민보험번호(NINO)
PL	31	폴란드 PESEL
SE	32	스웨덴 개인번호(PNR)
AT	34	오스트리아 세금 번호(STNR)
FI	35	핀란드 개인 식별 코드(HETU)
—	0	미지정
—	3	Unico 내부 식별자

이미지 요구사항

• 최소 해상도: 640 x 480 (HD 표준)
• 최대 파일 크기: 800 KB (JPEG92 압축 권장)
• 허용 형식: PNG, JPEG, WebP
• SDK의 JWT 토큰은 10분 후 만료되며 한 번만 사용할 수 있습니다

예제

온보딩 - cURL

curl -X POST https://api.id.unico.app/processes/v1 \
  -H "Authorization: Bearer $TOKEN" \
  -H "APIKEY: $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "subject": {
      "code": "12345678909",
      "name": "Luke Skywalker",
      "gender": "M",
      "birthDate": "2000-05-20",
      "email": "[email protected]",
      "phone": "5519725570707"
    },
    "useCase": "Onboarding",
    "imageBase64": "/9j/4AAQSkZJR..."
  }'

온보딩 - Node.js

import fetch from 'node-fetch';

const res = await fetch('https://api.id.unico.app/processes/v1', {
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${process.env.UNICO_ACCESS_TOKEN}`,
    'APIKEY': process.env.UNICO_API_KEY,
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    subject: {
      code: '12345678909',
      name: 'Luke Skywalker',
      gender: 'M',
      birthDate: '2000-05-20',
      email: '[email protected]',
      phone: '5519725570707'
    },
    useCase: 'Onboarding',
    imageBase64: capturedImage
  })
});

const result = await res.json();

트랜잭션 - cURL

curl -X POST https://api.id.unico.app/processes/v1 \
  -H "Authorization: Bearer $TOKEN" \
  -H "APIKEY: $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "referenceProcessId": "80371b2a-3ac7-432e-866d-57fe37896ac6",
    "useCase": "Transactional",
    "imageBase64": "/9j/4AAQSkZJR..."
  }'

트랜잭션 - Node.js

import fetch from 'node-fetch';

const res = await fetch('https://api.id.unico.app/processes/v1', {
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${process.env.UNICO_ACCESS_TOKEN}`,
    'APIKEY': process.env.UNICO_API_KEY,
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    referenceProcessId: referenceProcessId,
    useCase: 'Transactional',
    imageBase64: capturedImage
  })
});

const result = await res.json();

응답

온보딩

200 OK

{
  "id": "80371b2a-3ac7-432e-866d-57fe37896ac6",
  "status": 3,
  "unicoId": { "result": "yes" },
  "riskLevel": { "result": "inconclusive" },
  "idFace": {
    "personId": "a1b2c3d4e5f67890a1b2c3d4e5f67890a1b2c3d4e5f67890a1b2c3d4e5f67890",
    "result": "FOUND"
  },
  "government": { "serpro": 87 },
  "liveness": 1
}

응답 필드는 APIKey에 따라 다릅니다

위의 예시는 모든 가능한 기능 필드를 보여줍니다. 실제 응답에는 APIKey 설정에서 활성화된 기능의 필드만 포함되며, 비활성화된 기능의 필드는 완전히 생략됩니다. 기능을 활성화하거나 조정하려면 Unico 프로젝트 매니저에게 문의하세요.

필드	유형	설명
id	string (UUID)	프로세스 식별자. 재조회 시 프로세스 조회와 함께 사용합니다.
status	integer	1 (처리 중), 3 (성공적으로 완료), 5 (오류).
unicoId.result	string	yes, no, inconclusive - 신원 확인 참조.
riskLevel.result	string	approved, reproved, risk-critical, risk-high, inconclusive — 아래 가능한 값 참조 또는 사기 위험 분류.
idFace.result	string	FOUND, NOT_FOUND — Face Identifier 참조.
idFace.personId	string	얼굴에 대한 안정적인 불투명 식별자. idFace.result = FOUND일 때만 제공됩니다.
identityFraudsters.result	string	더 이상 사용되지 않습니다. 대신 riskLevel을 사용하세요. 통합이 진행 중인 클라이언트는 프로젝트 팀과 마이그레이션을 조율하면서 계속 사용할 수 있습니다.
government.serpro	integer	Serpro 유사도 점수 (0-100, -1, -2). 브라질에서만 사용 가능합니다. Serpro 유사도 반환 참조.
liveness	integer	1 (통과), 2 (실패) - 라이브니스 참조.

riskLevel.result — 가능한 값

값	의미
approved	신분증 소지자의 얼굴이 맞으며, 사기와 관련된 증거가 발견되지 않았습니다.
reproved	여러 사기 지표가 감지되었으므로 거부를 권장합니다.
risk-critical	거부를 권장하나 최종 결정은 귀하의 판단에 달려 있습니다. 심각 위험은 최소 2개의 강력한 사기 증거가 발견되었음을 나타냅니다.
risk-high	거부도 권장하나 결정은 귀하에게 있습니다. 높은 위험은 최소 1개의 강력한 사기 증거가 발견되었음을 나타냅니다.
inconclusive	강력한 사기 증거가 발견되지 않았습니다. 따라서 관련 위험이 있는지 여부를 결론짓기 어렵습니다.

정보

unicoId.result = inconclusive이고 위험 점수 오케스트레이션이 활성화된 경우, 프로세스가 status: 1 (처리 중)을 반환할 수 있습니다. 프로세스 조회를 폴링하거나 웹훅을 사용하여 최종 결과를 가져오세요.

트랜잭션

200 OK

{
  "id": "80371b2a-3ac7-432e-866d-57fe37896ac6",
  "status": 3,
  "biometryToken": { "result": true },
  "liveness": 1
}

필드	유형	설명
id	string (UUID)	프로세스 식별자.
status	integer	3 (성공적으로 완료), 5 (오류). 모든 가능한 값은 프로세스 조회를 참조하세요.
biometryToken.result	boolean	제출된 얼굴이 참조 프로세스와 일치하면 true; 그렇지 않으면 false.
liveness	integer	1 (통과), 2 (실패) - 라이브니스 참조.

400 Bad Request

페이로드 형식이 잘못되었거나, 이미지가 유효하지 않거나, 필수 필드가 누락되었습니다. 아래 오류 코드를 참조하세요.

403 Forbidden

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

409 Conflict

제공된 processId가 이 테넌트에 이미 존재합니다. 아래 오류 코드를 참조하세요.

429 Too Many Requests

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

모범 사례:

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

경고

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

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

오류 코드

400 Bad Request

코드	메시지	설명
20900	O base64 informado não é válido.	base64 파라미터가 유효하지 않습니다. 가능한 원인: 이미지가 아니거나 인젝션 시도입니다.
20807	A imagem precisa estar no padrão HD ou possuir uma resolução superior a 640 x 480.	업로드된 이미지의 해상도가 너무 낮습니다.
20513	The referenced process was not found.	referenceProcessId가 존재하지 않거나 더 이상 접근할 수 없는 프로세스를 가리킵니다.
20512	The referenced process is not available for reuse.	참조된 프로세스가 존재하지만 재사용할 수 없습니다.
20509	The subject.name field is invalid.	subject.name에 유효하지 않은 문자가 포함되어 있습니다.
20508	The subject.gender field is invalid.	subject.gender는 M 또는 F여야 합니다.
20507	O parâmetro subject.code é inválido.	비표준이거나 존재하지 않는 CPF입니다.
20506	O base64 informado é muito grande. O tamanho máximo suportado é até 800kb.	이미지 크기가 800 KB를 초과합니다; JPEG92로 압축하세요.
20505	O base64 informado não é suportado. Os formatos aceitos são png, jpeg e webp.	base64 형식이 유효하지 않거나 지원되지 않습니다.
20065	The referenceProcessId field is invalid.	referenceProcessId가 유효한 UUID가 아닙니다.
20062	The useCase field is invalid.	useCase 필드에 인식할 수 없는 값입니다.
20024	The referenceProcessId field is missing.	referenceProcessId 파라미터가 제공되지 않았고 대안으로 references도 전송되지 않았습니다.
20021	The subject.phone field is invalid.	subject.phone 형식이 유효하지 않습니다 (IDD + 지역 코드 + 번호, 13자).
20019	The subject.birthDate field is invalid.	subject.birthDate가 ISO 8601 형식 (YYYY-MM-DD) 범위를 벗어났습니다.
20009	O parâmetro imagebase64 não foi informado.	셀피 이미지 파라미터가 누락되었습니다.
20008	The subject.email field is invalid.	subject.email의 이메일 형식이 유효하지 않습니다.
20006	O parâmetro subject.name não foi informado.	subject.name 파라미터가 누락되었습니다.
20005	O parâmetro subject.code não foi informado.	subject.code 파라미터가 누락되었습니다.
20004	O parâmetro subject não foi informado.	subject 파라미터가 누락되었습니다.
20003	The request body is missing or invalid.	null이거나 유효하지 않은 페이로드입니다.
20002	O parâmetro APIKey não foi informado.	요청 헤더에 APIKEY 파라미터가 누락되었습니다.
20001	O parâmetro authtoken não foi informado.	요청 헤더에 통합 토큰 파라미터가 누락되었습니다.
10508	The JWT with the captured face has already been used.	JWT는 한 번만 사용할 수 있습니다.
10507	The JWT with the captured face is expired.	JWT가 만료되었습니다; 10분 이내에 전송해야 합니다.
10506	The imageBase64 field is not a valid JWT from SDK.	imageBase64가 SDK에서 생성된 유효한 JWT가 아닙니다.

403 Forbidden

코드	메시지	설명
30017	User does not have permission to perform this action.	잘못된 형식의 JWT이거나 이 작업을 수행할 권한이 없는 사용자입니다.
10502	O token informado está expirado.	액세스 토큰이 만료되었습니다.
10501	O token informado é inválido.	인증 토큰이 유효하지 않습니다.
10201	O AppKey informado é inválido.	APIKEY가 유효하지 않거나 존재하지 않습니다.

409 Conflict

코드	메시지	설명
20073	The processID already exists.	제공된 processId가 이 테넌트에 이미 존재합니다.

500 Internal Server Error

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

다음 단계

• 온보딩 프로세스 결과를 조회하려면 프로세스 조회를 참조하세요.
• 문서 및 연령 인증 작업에 대해서는 이 섹션의 해당 페이지를 참조하세요.