연령 인증

전체 통합 흐름은 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	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	아니오	전화번호: 국가 코드 + 지역 코드 + 번호, 구분 기호 없음 (예: 5519725570707).
useCase	string	아니오	작업의 사용 사례 식별자.
subsidiaryId	string	아니오	지점 ID — 여러 지점이 있는 경우에만 필요.
imageBase64	string	예	암호화된 SDK 출력 또는 base64 이미지 (PNG, JPEG, WebP).

이미지 요구 사항

• 최소 해상도: 640 × 480 (HD 표준)
• 최대 파일 크기: 800 KB (JPEG92 압축 권장)
• 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",
      "birthDate": "2000-05-20",
      "email": "[email protected]",
      "phone": "5519725570707"
    },
    "useCase": "AgeVerification",
    "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',
      birthDate: '2000-05-20',
      email: '[email protected]',
      phone: '5519725570707'
    },
    useCase: 'AgeVerification',
    imageBase64: capturedImage
  })
});

const result = await res.json();

응답

200 OK

반환되는 응답 필드는 APIKEY에 활성화된 기능에 따라 다릅니다.

연령 인증만 (라이브니스 없음, 신원 확인 없음):

{
  "id": "80371b2a-3ac7-432e-866d-57fe37896ac6",
  "status": 3,
  "idAge": { "result": "yes" }
}

연령 인증 + 라이브니스 + 신원 확인:

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

필드	타입	설명
id	string (UUID)	프로세스 식별자. 재조회를 위해 프로세스 조회와 함께 사용합니다.
status	integer	3 (성공적으로 완료), 5 (오류). 비즈니스 결정에는 status = 3만 사용하세요. 가능한 모든 값은 프로세스 조회를 참조하세요.
idAge.result	string	yes, no, inconclusive — 연령 인증 결과. 모든 응답에 포함됩니다.
unicoId.result	string	yes, no, inconclusive — 신원 확인이 활성화된 경우에만 표시됩니다.
liveness	integer	1 (통과), 2 (실패) — 라이브니스가 활성화된 경우에만 표시됩니다.

400 Bad Request

페이로드가 잘못되었거나, 이미지가 유효하지 않거나, 필수 필드가 누락되었습니다.

403 Forbidden

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

409 Conflict

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

429 Too Many Requests

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

500 Internal Server Error

예기치 않은 서버 오류입니다.

오류 코드

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.	이미지 해상도가 최소 임계값보다 낮습니다.
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.	잘못되었거나 존재하지 않는 식별자 값입니다. 플로우에 라이브니스 또는 신원 확인이 포함된 경우에만 발생하며, 연령 인증 전용 플로우에는 필요하지 않습니다.
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 접두사입니다.
20062	The useCase field is invalid.	useCase 필드에 인식되지 않는 값이 있습니다.
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에 유효하지 않은 이메일 형식입니다.
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가 잘못되었거나 이 작업을 수행할 권한이 없는 사용자입니다.
30017	Jwt header is an invalid JSON.	access-token에 유효하지 않은 문자가 포함되어 있습니다.
10502	O token informado está expirado.	access-token이 만료되었습니다.
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.	서버 측 처리 오류입니다.

다음 단계

• 기존 프로세스를 조회하려면 프로세스 조회를 참조하세요.