연령 인증

전체 통합 플로우는 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 x 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

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

모범 사례:

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

경고

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

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

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.	액세스 토큰에 유효하지 않은 문자가 포함되어 있습니다.
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.	서버 측 처리 오류입니다.

다음 단계

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