재처리 및 생체 인식 데이터베이스 가져오기

이 가이드는 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 표준을 따라야 합니다(밝은 배경, 중앙에 위치한 얼굴, 식별을 방해하는 액세서리 없음, 적절한 조명).
권장 크기: 1920x1080 또는 1080x1920 비율.
최대 크기: 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",
    "email": "[email protected]",
    "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 값

값	설명
`0`	미지정
`1`	브라질 — CPF
`2`	멕시코 — CURP
`3`	Unico 내부 식별자
`4`	미국 — SSN
`5`	브라질 — 여권
`6`	아르헨티나 — 여권
`7`	아르헨티나 — DNI
`8`	나이지리아 — NIN
`9`	칠레 — RUN
`10`	에콰도르 — NI
`11`	미국 — 여권
`12`	과테말라 — CUI
`13`	우루과이 — CI
`15`	이메일 주소
`16`	인도네시아 — NIK
`17`	전화번호
`18`	미국 — 운전면허증

중요 참고 사항

셀피는 적절한 품질과 조명으로 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)의 경우 재시도/백오프 제어를 사용하여 재처리하세요.

범위​

전제 조건​

사용 가능한 기능​

셀피 요구 사항​

문서 요구 사항​

TPS 합의​

통합​

엔드포인트​

필수 헤더​

페이로드 매개변수​

중요 참고 사항​

응답​

오류 처리​

범위