재처리 및 생체 인식 데이터베이스 가져오기
이 가이드는 Unico 플랫폼에서 재처리 또는 생체 인식 데이터베이스 가져오기를 수행하는 방법을 다룹니다. 플랫폼 모범 사례에 따른 효과적이고 안전한 통합을 위한 기술적 및 운영적 요구 사항을 자세히 설명합니다.
범위
이 자료는 두 가지 유형의 프로세스를 다룹니다:
- 재처리: 클라이언트 및 Unico의 데이터베이스를 이미 거친 사용자의 생체 인식 기록을 재평가하거나 시스템 간 마이그레이션을 위해 재처리합니다.
- 생체 인식 데이터베이스 가져오기: 본인 확인 및/또는 위험 분류 목적으로 셀피를 포함하는 데이터베이스의 초기 업로드 또는 업데이트입니다.
- 문서 데이터베이스 가져오기: Facematch 또는 CPF Match 인증을 위해 셀피와 함께 문서 데이터베이스를 업로드합니다(브라질 전용).
전제 조건
- 클라이언트는 Unico와 활성 계약 또는 NDA가 체결되어 있어야 하며, 통합 단계에 있어야 합니다(거버넌스 팀의 승인이 있는 경우 예외).
- 프로젝트는 공식적인 TPS(초당 트랜잭션 수) 합의를 따릅니다. 아래 TPS 합의를 참조하세요.
- 프로덕션 자격 증명을 받기 전에 데이터 품질, 페이로드 준수 및 안정적인 성능을 보장하기 위해 완전한 통합 검증이 필수입니다.
- 재처리 또는 가져오기를 위한 전용 서비스 계정이 생성되어야 합니다(예: "Reprocessing" 또는 "Legacy_Import").
- 재처리/가져오기를 위한 전용 API Key가 생성됩니다.
- (선택 사항) 재처리/가져오기를 위한 전용 자회사를 생성할 수 있습니다. 이 매개변수는 페이로드에서
subsidiaryId로 식별됩니다. 아래 페이로드 매개변수를 참조하세요. - API Key 및 서비스 계정은 합의된 기간 또는 처리 완료 후 비활성화됩니다.
사용 가능한 기능
| 기능 | 설명 |
|---|---|
| 신원 확인 | 제출된 셀피가 식별자의 실제 소유자에게 속하는지 확인합니다. |
| 사기 위험 분류 | 해당 얼굴과 관련된 사기 행위 이력이 있는지 확인합니다. |
| Facematch | 문서 사진이 제출된 셀피와 일치하는지 확인합니다. |
CPF Match  Brazil only | 제공된 CPF가 문서에 인쇄된 CPF 번호와 일치하는지 확인합니다. 참고: 모든 RG에 CPF가 인쇄된 것은 아닙니다. |
셀피 요구 사항
- base64 형식으로 제출해야 합니다.
- 이미지는 ICAO 표준을 따라야 합니다(밝은 배경, 중앙에 위치한 얼굴, 식별을 방해하는 액세서리 없음, 적절한 조명).
- 권장 크기: 1080x1920 (세로) 또는 1920x1080 (가로).
- 최대 크기: 800 KB (필요 시 JPEG 92로 압축).
- 방향: 세로(portrait).
문서 요구 사항
- 지원되는 문서 유형: 문서 캡처 및 재사용 — 지원 문서를 참조하세요.
- 이미지에는 문서의 앞면과 뒷면 모두가 포함되어야 하며, 잘림 없이 완전히 보여야 합니다.
- 문서는 읽을 수 있어야 합니다 — 선명하고, 조명이 충분하며, 방해물이 없어야 합니다.
TPS 합의
- 이 프로젝트에 대해 합의된 최대 TPS는 10 TPS입니다.
- 대량 버스트로 전송하지 말고 시간에 걸쳐 요청을 균등하게 분산하세요.
- 이 제한은 Unico 팀의 공식 승인 없이 초과해서는 안 됩니다.
- 제한을 초과하는 요청은 자동으로 삭제되거나 차단될 수 있습니다.
- 일시적인 증가가 필요한 경우, 공식적인 사전 합의가 필요합니다.
통합
엔드포인트
| 환경 | 기본 URL | 접근 | 참고 |
|---|---|---|---|
| 스테이징 | https://api.id.uat.unico.app | 개방 | 테스트 필수 |
| 프로덕션 | https://api.id.unico.app | 승인된 검증 후에만 | 엄격한 TPS 제어 필요 |
필수 헤더
Authorization: Bearer {access_token}
APIKEY: {your_api_key}
Content-Type: application/json
페이로드 매개변수
{
"subject": {
"duiType": 1,
"code": "11032395702",
"name": "User Name",
"phone": "21998571922",
"birthDate": "30/07/1989",
"gender": "M"
},
"useCase": "Reprocessamento/Importação",
"subsidiaryId": "35d734c4-7fbb-4b2f-a1dc-7e1575514819",
"imageBase64": "/9j/4AAQSkZJR...",
"document": {
"purpose": "Reprocessamento",
"documentId": "doc-001",
"files": [
{
"data": "doc_base64_frente",
"faceDocumentMatch": true
},
{
"data": "doc_base64_verso"
}
]
}
}
| 필드 | 타입 | 필수 | 설명 |
|---|---|---|---|
subject | object | 예 | 사용자 식별 데이터. |
subject.duiType | integer | 예 | 문서 유형 식별자. 아래 duiType 값을 참조하세요. |
subject.code | string | 예 | CPF 또는 기타 사용자 식별자. |
subject.name | string | 예 | 사용자의 전체 이름. |
subject.email | string | 아니오 | 사용자의 이메일. |
subject.phone | string | 아니오 | 사용자의 전화번호. |
subject.birthDate | string | 아니오 | 사용자의 생년월일(DD/MM/YYYY). |
subject.gender | string | 아니오 | 사용자의 성별(M 또는 F). |
useCase | string | 예 | 사용 사례 이름 ("Reprocessamento" 또는 "Importação de base"). |
subsidiaryId | string | 아니오 | 자회사 UUID (Unico에서 제공). |
imageBase64 | base64 | 예 | base64로 변환된 사용자의 셀피 이미지. |
document | object | 아니오 | 프로세스와 관련된 문서 데이터. |
document.purpose | string | 아니오 | 문서 목적(예: "Reprocessamento"). |
document.documentId | string | 아니오 | 문서 식별자. |
document.files | array | 아니오 | 문서 이미지 파일 목록. |
document.files[].data | base64 | 아니오 | base64로 변환된 문서 이미지. |
document.files[].faceDocumentMatch | boolean | 아니오 | 문서의 얼굴이 제출된 셀피와 일치하는지 여부를 나타냅니다. |
duiType 값
| 국가 | 코드 | 설명 |
|---|---|---|
| BR | 1 | 브라질 CPF |
| BR | 5 | 브라질 여권 |
| MX | 2 | 멕시코 CURP |
| AR | 6 | 아르헨티나 여권 |
| AR | 7 | 아르헨티나 DNI |
| US | 4 | 미국 SSN |
| US | 11 | 미국 여권 |
| US | 18 | 미국 운전면허증 |
| ID | 16 | 인도네시아 NIK |
| NG | 8 | 나이지리아 NIN |
| CL | 9 | 칠레 RUN |
| EC | 10 | 에콰도르 NI |
| GT | 12 | 과테말라 CUI |
| UY | 13 | 우루과이 CI |
| ZZ | 15 | 이메일 주소 |
| ZZ | 17 | 전화번호 |
| MX | 25 | 멕시코 RFC(개인) |
| CO | 26 | 콜롬비아 NIT |
| PE | 27 | 페루 RUC |
| CA | 28 | 캐나다 SIN |
| DK | 29 | 덴마크 CPR |
| GB | 30 | 영국 국민보험번호(NINO) |
| PL | 31 | 폴란드 PESEL |
| SE | 32 | 스웨덴 개인번호(PNR) |
| AT | 34 | 오스트리아 세금 번호(STNR) |
| FI | 35 | 핀란드 개인 식별 코드(HETU) |
| — | 0 | 미지정 |
| — | 3 | Unico 내부 식별자 |
중요 참고 사항
- 셀피는 적절한 품질과 조명으로 ICAO 표준을 준수해야 합니다.
- 셀피는 base64 형식이어야 합니다.
- TPS 제어 없이 대량 제출을 피하세요. 이는 속도 제한을 유발할 수 있습니다(아래 오류 처리 참조).
- 항상 스테이징 환경에서 먼저 데이터와 통합을 테스트하세요.
응답
성공 — 200 OK
- 문서 없음
- 문서 있음(Facematch)
{
"id": "80371b2a-3ac7-432e-866d-57fe37896ac6",
"status": 3,
"unicoId": {
"result": "inconclusive"
},
"identityFraudsters": {
"result": "inconclusive"
}
}
| 필드 | 타입 | 설명 |
|---|---|---|
id | string | 프로세스 식별자. 향후 조회를 위해 저장하거나 나중에 1:1 검증을 구현할 경우 사용합니다. |
status | integer | 트랜잭션 상태. |
unicoId.result | string | 신원 확인 기능 응답. |
identityFraudsters.result | string | 사기 위험 분류 기능 응답. |
{
"id": "80371b2a-3ac7-432e-866d-57fe37896ac6",
"score": 0,
"status": 3,
"unicoId": {
"result": "yes"
},
"faceDocumentMatch": {
"faceMatch": true
},
"identityFraudsters": {
"result": "yes"
}
}
| 필드 | 타입 | 설명 |
|---|---|---|
id | string | 프로세스 식별자. 향후 조회를 위해 저장하거나 나중에 1:1 검증을 구현할 경우 사용합니다. |
status | integer | 트랜잭션 상태. |
score | number | Facematch 점수. |
unicoId.result | string | 신원 확인 기능 응답. |
faceDocumentMatch.faceMatch | boolean | 문서 사진이 제출된 셀피와 일치하는지 여부. |
identityFraudsters.result | string | 사기 위험 분류 기능 응답. |
이미지 처리 오류
{
"id": "80371b2a-3ac7-432e-866d-57fe37896ac6",
"status": 5
}
일반적인 오류
4xx 범위의 코드는 제공된 데이터의 유효성 검사 오류를 나타냅니다. 5xx 범위의 코드는 서버 측 장애를 나타냅니다.
| HTTP 코드 | 오류 유형 | 가능한 원인 | 권장 조치 |
|---|---|---|---|
400 | Bad Request | 유효하지 않은 페이로드 | 구조와 내용을 검증하세요. |
401 | Unauthorized | 만료되거나 유효하지 않은 토큰 | 토큰을 재생성하세요. |
403 | Forbidden | 잘못된 API Key 또는 권한 부족 | 자격 증명을 확인하세요. |
429 | Too Many Requests | 요청 속도 초과 | 대기 후 TPS 제한을 준수하세요. |
500+ | Internal Server Error | 내부 장애 | 몇 초 후 재시도하세요. 지속되면 티켓을 생성하세요. |
오류 처리
- **속도 제한(HTTP 429)**을 주의 깊게 모니터링해야 합니다. 요청 과부하는 파이프라인을 차단할 수 있습니다.
- 항상 Unico와 합의된 TPS를 준수하세요(TPS 합의 참조).
- 지속적인 장애(5xx)의 경우 재시도/백오프 제어를 사용하여 재처리하세요.