--- title: 연령 인증 description: 연령 인증 프로세스를 생성합니다. 선택적으로 라이브니스 감지와 신원 확인을 단일 요청으로 결합합니다. canonical: https://developer.unico.io/ko/dual-api/developers/api-reference/api/post-processes-age-validation locale: ko generated_by: markdown-export --- - [/ko/](/ko/) - [API 레퍼런스](/ko/dual-api/developers/api-reference/) - [API](/ko/dual-api/developers/api-reference/api/) - 연령 인증 **이 페이지에서# 연령 인증 전체 통합 플로우는 [API 개요](/ko/dual-api/developers/api-reference/api/)를 참조하세요. ### 엔드포인트​ 환경URL**프로덕션**`POST https://api.id.unico.app/processes/v1`**샌드박스**`POST https://api.id.uat.unico.app/processes/v1` ### 요청​ 헤더 헤더값`Authorization``Bearer ` ([인증](/ko/dual-api/developers/api-reference/authentication) 참조)`APIKEY`연령 인증 기능이 활성화된 프로비저닝된 API 키.`Content-Type``application/json` 본문 파라미터 필드유형필수설명`subject`object예사용자 정보 컨테이너.`subject.code`string조건부CPF (BR) 또는 CURP (MX), 포맷팅 없이. 플로우에 라이브니스 또는 신원 확인이 포함된 경우 필수입니다 ([연령 인증 기능](/ko/dual-api/capabilities/age-verification) 참조); 연령 인증 전용 플로우에서는 필수가 아닙니다.`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분** 후 만료되며 **한 번만** 사용할 수 있습니다 ### 예제​ cURLNode.js``` 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": "luke@example.com", "phone": "5519725570707" }, "useCase": "AgeVerification", "imageBase64": "/9j/4AAQSkZJR..." }' ``` ``` 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: 'luke@example.com', 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)프로세스 식별자. 재조회 시 [프로세스 조회](/ko/dual-api/developers/api-reference/api/get-process)와 함께 사용합니다.`status`integer`3` (성공적으로 완료), `5` (오류). 비즈니스 결정에는 `status = 3`만 사용하세요. 모든 가능한 값은 [프로세스 조회](/ko/dual-api/developers/api-reference/api/get-process)를 참조하세요.`idAge.result`string`yes`, `no`, `inconclusive` - 연령 인증 결과. 모든 응답에 존재합니다.`unicoId.result`string`yes`, `no`, `inconclusive` - 신원 확인이 활성화된 경우에만 존재합니다.`liveness`integer`1` (통과), `2` (실패) - 라이브니스가 활성화된 경우에만 존재합니다. ### 오류 코드​ 400 Bad Request403 Forbidden409 Conflict429 Too Many Requests500 Internal Server Error코드메시지설명`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가 아닙니다.Bearer 토큰 또는 `APIKEY`가 누락되었거나, 만료되었거나, 유효하지 않습니다. [인증](/ko/dual-api/developers/api-reference/authentication)을 참조하세요.코드메시지설명`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입니다.코드메시지설명`20073`The processID already exists.제공된 `processId`가 이 테넌트에 이미 존재합니다.속도 제한에 도달했습니다. 시스템이 HTTP 429 오류를 수신하면 연쇄 장애를 방지하고 제한을 악화시키지 않기 위한 메커니즘을 구현해야 합니다.**모범 사례:** **쿨다운 기간 (백오프):** 시스템에서 후속 요청을 즉시 중지하거나 조절하세요. 실패한 요청을 타이트한 루프에서 지속적으로 재시도하지 마세요. **큐잉 및 조절:** 발신 요청을 버퍼링하거나 큐에 넣어 다시 보내기 전에 트래픽 흐름을 제어하세요. **지터를 포함한 지수 백오프:** 재시도할 때 시도 간 대기 시간을 지수적으로 늘리고 (예: 1초, 2초, 4초, 8초) 작은 랜덤 지연("지터")을 추가하여 큐에 있는 모든 요청이 정확히 같은 밀리초에 재시도하는 허드 효과를 방지하세요. 경고백오프 없이 속도 제한된 엔드포인트에 지속적으로 요청하면 **제한 기간이 연장**되고 시스템의 운영 처리량에 심각한 영향을 줄 수 있습니다. 요청을 적절히 조절하면 더 부드럽고 탄력적인 통합을 보장할 수 있습니다.기본 제한, 요청 증가 및 추가 세부사항은 [속도 제한](/ko/dual-api/developers/api-reference/rate-limits)을 참조하세요.코드메시지설명`99999`Internal failure! Try again later.서버 측 처리 오류입니다. ### 다음 단계​ 기존 프로세스를 조회하려면 [프로세스 조회](/ko/dual-api/developers/api-reference/api/get-process)를 참조하세요. 마지막 업데이트 2026년 10월 8일**에