메인 콘텐츠로 건너뛰기

연령 인증

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

엔드포인트​

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

요청​

헤더
헤더값
AuthorizationBearer <access_token> (인증 참조)
APIKEY연령 인증 기능이 활성화된 프로비저닝된 API 키.
Content-Typeapplication/json
본문 파라미터
필드유형필수설명
subjectobject예사용자 정보 컨테이너.
subject.codestring조건부CPF (BR) 또는 CURP (MX), 포맷팅 없이. 플로우에 라이브니스 또는 신원 확인이 포함된 경우 필수입니다 (연령 인증 기능 참조); 연령 인증 전용 플로우에서는 필수가 아닙니다.
subject.namestring아니요사용자의 전체 이름.
subject.genderstring아니요남성은 M, 여성은 F.
subject.birthDatestring (ISO 8601)아니요생년월일 (YYYY-MM-DD).
subject.emailstring아니요사용자의 이메일 주소.
subject.phonestring아니요전화번호: 국가 코드 + 지역 코드 + 번호, 구분자 없이 (예: 5519725570707).
useCasestring아니요작업의 시나리오 식별자.
subsidiaryIdstring아니요지점 ID - 여러 지점이 있는 경우에만 필수.
imageBase64string예암호화된 SDK 출력 또는 base64 이미지 (PNG, JPEG, WebP).
이미지 요구사항
  • 최소 해상도: 640 x 480 (HD 표준)
  • 최대 파일 크기: 800 KB (JPEG92 압축 권장)
  • SDK의 JWT 토큰은 10분 후 만료되며 한 번만 사용할 수 있습니다

예제​

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..."
  }'

응답​

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
}
필드유형설명
idstring (UUID)프로세스 식별자. 재조회 시 프로세스 조회와 함께 사용합니다.
statusinteger3 (성공적으로 완료), 5 (오류). 비즈니스 결정에는 status = 3만 사용하세요. 모든 가능한 값은 프로세스 조회를 참조하세요.
idAge.resultstringyes, no, inconclusive - 연령 인증 결과. 모든 응답에 존재합니다.
unicoId.resultstringyes, no, inconclusive - 신원 확인이 활성화된 경우에만 존재합니다.
livenessinteger1 (통과), 2 (실패) - 라이브니스가 활성화된 경우에만 존재합니다.

오류 코드​

코드메시지설명
20900O base64 informado não é válido.유효하지 않은 base64 파라미터; 이미지 또는 인젝션 문제일 수 있습니다.
20807A imagem precisa estar no padrão HD ou possuir uma resolução superior a 640 x 480.이미지 해상도가 최소 기준 이하입니다.
20509The subject.name field is invalid.subject.name에 유효하지 않은 문자가 포함되어 있습니다.
20508The subject.gender field is invalid.subject.gender는 M 또는 F여야 합니다.
20507O parâmetro subject.code é inválido.잘못된 형식이거나 존재하지 않는 식별자 값. 라이브니스 또는 신원 확인이 플로우에 포함된 경우에만 발생합니다 - 연령 인증 전용 플로우에서는 필수가 아닙니다.
20506O base64 informado é muito grande. O tamanho máximo suportado é até 800kb.페이로드가 800 KB를 초과합니다; JPEG92로 압축하세요.
20505O base64 informado não é suportado. Os formatos aceitos são png, jpeg e webp.지원되지 않는 형식이거나 유효하지 않은 base64 접두사입니다.
20062The useCase field is invalid.useCase 필드에 인식할 수 없는 값입니다.
20021The subject.phone field is invalid.subject.phone 형식이 유효하지 않습니다 (IDD + 지역 코드 + 번호, 13자).
20019The subject.birthDate field is invalid.subject.birthDate가 ISO 8601 형식 (YYYY-MM-DD) 범위를 벗어났습니다.
20009O parâmetro imagebase64 não foi informado.셀피 이미지 파라미터가 누락되었습니다.
20008The subject.email field is invalid.subject.email의 이메일 형식이 유효하지 않습니다.
20005O parâmetro subject.code não foi informado.subject.code 파라미터가 누락되었습니다. 라이브니스 또는 신원 확인이 플로우에 포함된 경우에만 발생합니다 - 연령 인증 전용 플로우에서는 필수가 아닙니다.
20004O parâmetro subject não foi informado.subject 객체가 누락되었습니다.
20003The request body is missing or invalid.null이거나 형식이 잘못된 페이로드입니다.
20002O parâmetro APIKey não foi informado.APIKEY 헤더가 누락되었습니다.
20001O parâmetro authtoken não foi informado.인증 토큰 헤더가 누락되었습니다.
10508The JWT with the captured face has already been used.JWT는 한 번만 사용할 수 있습니다.
10507The JWT with the captured face is expired.JWT가 만료되었습니다; 10분 이내에 전송해야 합니다.
10506The imageBase64 field is not a valid JWT from SDK.imageBase64가 SDK에서 생성된 유효한 JWT가 아닙니다.

다음 단계​

마지막 업데이트 에