프로세스 생성

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

• 온보딩 — Unico의 신원 기반에 대해 얼굴을 비교하여 사용자가 누구인지 검증합니다 (subject.code 필수).
• 트랜잭션 — 이전 프로세스와 얼굴 대 얼굴로 비교하여 동일한 인물인지 확인합니다 (referenceProcessId 또는 셀피 / process 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.code	string	예	CPF(BR) 또는 CURP(MX).
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.
imageBase64	string	예	프론트엔드에서 캡처한 셀피, base64 형식.

트랜잭션

필드	타입	필수	설명
references	array	조건부	1:1 검증 흐름을 위한 참조 입력. 각 항목은 referenceType(REFERENCE_TYPE_IMAGE_BASE64 또는 REFERENCE_TYPE_PROCESS_ID) 및 referenceContent(base64로 인코딩된 이미지 또는 프로세스 UUID)를 포함합니다.
referenceProcessId	string	조건부	더 이상 사용되지 않습니다. 대신 references를 사용하세요. 비교할 기준 온보딩 프로세스의 ID. 기준이 Unico의 프로세스인 경우 authenticationInfo.authenticationId를 사용하세요.
imageBase64	string	예	프론트엔드에서 캡처한 셀피, base64 형식.
subject	object	아니오	사용자 정보 컨테이너.
subject.code	string	아니오	CPF(BR) 또는 CURP(MX).
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 응답에서 동기적으로 반환됩니다.

이미지 요구 사항

• 최소 해상도: 640 × 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" },
  "identityFraudsters": { "result": "inconclusive" },
  "government": { "serpro": 87 },
  "liveness": 1
}

필드	타입	설명
id	string (UUID)	프로세스 식별자. 재조회 시 프로세스 조회와 함께 사용합니다.
status	integer	1 (처리 중), 3 (성공적으로 완료), 5 (오류). 가능한 모든 값은 프로세스 조회를 참조하세요.
unicoId.result	string	yes, no, inconclusive — 신원 확인을 참조하세요.
identityFraudsters.result	string	yes, inconclusive — 사기 위험 분류를 참조하세요.
government.serpro	integer	Serpro 유사도 점수 (0–100, -1, -2). Serpro 유사도 반환을 참조하세요.
liveness	integer	1 (통과), 2 (실패) — 라이브니스를 참조하세요.

정보

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

요청 한도에 도달했습니다. Retry-After 응답 헤더에 표시된 간격 후 재시도하세요. 속도 제한을 참조하세요.

오류 코드

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	내부 오류가 발생한 경우.

다음 단계

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