Reprocesamiento e importación de base biométrica

Esta guía cubre cómo realizar el reprocesamiento o la importación de base biométrica en la plataforma Unico. Detalla los requisitos técnicos y operativos para una integración efectiva y segura siguiendo las mejores prácticas de la plataforma.

Alcance

Este material cubre dos tipos de procesos:

• Reprocesamiento: reprocesamiento de registros biométricos de usuarios que ya pasaron por la base del cliente y de Unico para reevaluación o migración entre sistemas.
• Importación de base biométrica: carga inicial o actualización de una base que contiene selfies para verificación de identidad y/o clasificación de riesgo.
• Importación de base de documentos: carga de una base de documentos junto con selfies para verificación por Facematch o CPF Match (solo Brasil).

Prerrequisitos

• El cliente debe tener un contrato activo o NDA firmado con Unico y estar en la fase de integración (excepción si es aprobado por el equipo de gobernanza).
• El proyecto seguirá acuerdos formales de TPS (transacciones por segundo). Consulte Acuerdo de TPS a continuación.
• Antes de obtener credenciales de producción, la homologación completa de integración es obligatoria para asegurar la calidad de los datos, el cumplimiento del payload y un rendimiento estable.
• Se debe crear una cuenta de servicio dedicada para el reprocesamiento o importación (por ejemplo, "Reprocessing" o "Legacy_Import").
• Se creará una API Key dedicada específicamente para el reprocesamiento/importación.
• (Opcional) Se puede crear una subsidiaria dedicada para el reprocesamiento/importación. Este parámetro se identifica en el payload como subsidiaryId. Consulte Parámetros del payload a continuación.
• La API Key y la cuenta de servicio se desactivarán después del período acordado o al completarse el procesamiento.

Capacidades disponibles

Capacidad	Descripción
Verificación de Identidad	Verifica si la selfie enviada pertenece al titular real del identificador.
Clasificación de riesgo de fraude	Comprueba si existe un historial de comportamiento fraudulento asociado a ese rostro.
Facematch	Verifica si la foto del documento coincide con la selfie enviada.
CPF Match Brazil only	Verifica si el CPF proporcionado coincide con el número de CPF impreso en el documento. Nota: no todos los RGs tienen el CPF impreso.

Requisitos de selfie

• Debe enviarse en formato base64.
• La imagen debe cumplir con el estándar ICAO (fondo claro, rostro centrado, sin accesorios que obstruyan la identificación, iluminación adecuada).
• Dimensiones recomendadas: proporción 1920x1080 o 1080x1920.
• Tamaño máximo: 800 KB (comprimir con JPEG 92 si es necesario).
• Orientación: vertical (portrait).

Requisitos del documento

• Tipos de documentos admitidos: consulte Captura de Documentos y Reutilización — Documentos admitidos.
• Las imágenes deben incluir tanto el anverso como el reverso del documento, completamente visibles sin recorte.
• El documento debe ser legible — claro, bien iluminado y libre de obstrucciones.

Acuerdo de TPS

• El TPS máximo acordado para este proyecto es 10 TPS.
• Distribuya las solicitudes uniformemente a lo largo del tiempo en lugar de enviarlas en grandes ráfagas.
• Este límite no debe superarse sin aprobación formal del equipo de Unico.
• Las solicitudes que superen el límite pueden ser descartadas o bloqueadas automáticamente.
• Si se necesita un aumento temporal, se requiere un acuerdo formal previo.

Integración

Endpoints

Entorno	URL base	Acceso	Notas
Staging	https://api.id.uat.unico.app	Abierto	Obligatorio para pruebas
Producción	https://api.id.unico.app	Solo después de homologación aprobada	Requiere control estricto de TPS

Headers requeridos

Authorization: Bearer {access_token}
APIKEY: {your_api_key}
Content-Type: application/json

Parámetros del payload

{
  "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"
      }
    ]
  }
}

Campo	Tipo	Requerido	Descripción
subject	object	Sí	Datos de identificación del usuario.
subject.duiType	integer	Sí	Identificador del tipo de documento. Consulte valores de duiType a continuación.
subject.code	string	Sí	CPF u otro identificador del usuario.
subject.name	string	Sí	Nombre completo del usuario.
subject.email	string	No	Correo electrónico del usuario.
subject.phone	string	No	Número de teléfono del usuario.
subject.birthDate	string	No	Fecha de nacimiento del usuario (DD/MM/YYYY).
subject.gender	string	No	Género del usuario (M o F).
useCase	string	Sí	Nombre del caso de uso ("Reprocessamento" o "Importação de base").
subsidiaryId	string	No	UUID de la subsidiaria (proporcionado por Unico).
imageBase64	base64	Sí	Imagen de selfie del usuario convertida a base64.
document	object	No	Datos del documento asociado al proceso.
document.purpose	string	No	Propósito del documento (por ejemplo, "Reprocessamento").
document.documentId	string	No	Identificador del documento.
document.files	array	No	Lista de archivos de imágenes del documento.
document.files[].data	base64	No	Imagen del documento convertida a base64.
document.files[].faceDocumentMatch	boolean	No	Indica si el rostro en el documento coincide con la selfie enviada.

Valores de duiType

Valor	Descripción
0	No especificado
1	Brasil — CPF
2	México — CURP
3	Identificador interno de Unico
4	Estados Unidos — SSN
5	Brasil — Pasaporte
6	Argentina — Pasaporte
7	Argentina — DNI
8	Nigeria — NIN
9	Chile — RUN
10	Ecuador — NI
11	Estados Unidos — Pasaporte
12	Guatemala — CUI
13	Uruguay — CI
15	Dirección de correo electrónico
16	Indonesia — NIK
17	Número de teléfono
18	Estados Unidos — Licencia de conducir

Notas importantes

• La selfie debe cumplir con el estándar ICAO con calidad e iluminación adecuadas.
• La selfie debe estar en formato base64.
• Evite envíos masivos sin control de TPS, ya que esto puede activar la limitación de tasa (consulte Manejo de errores a continuación).
• Siempre pruebe los datos y la integración en el entorno de staging primero.

Respuestas

Éxito — 200 OK

Sin documento

{
  "id": "80371b2a-3ac7-432e-866d-57fe37896ac6",
  "status": 3,
  "unicoId": {
    "result": "inconclusive"
  },
  "identityFraudsters": {
    "result": "inconclusive"
  }
}

Campo	Tipo	Descripción
id	string	Identificador del proceso. Almacénelo para consultas futuras o si implementa Validación (1:1) más adelante.
status	integer	Estado de la transacción.
unicoId.result	string	Respuesta de la capacidad Verificación de Identidad.
identityFraudsters.result	string	Respuesta de la capacidad Clasificación de riesgo de fraude.

Con documento (Facematch)

{
  "id": "80371b2a-3ac7-432e-866d-57fe37896ac6",
  "score": 0,
  "status": 3,
  "unicoId": {
    "result": "yes"
  },
  "faceDocumentMatch": {
    "faceMatch": true
  },
  "identityFraudsters": {
    "result": "yes"
  }
}

Campo	Tipo	Descripción
id	string	Identificador del proceso. Almacénelo para consultas futuras o si implementa Validación (1:1) más adelante.
status	integer	Estado de la transacción.
score	number	Puntuación de Facematch.
unicoId.result	string	Respuesta de la capacidad Verificación de Identidad.
faceDocumentMatch.faceMatch	boolean	Si la foto del documento coincide con la selfie enviada.
identityFraudsters.result	string	Respuesta de la capacidad Clasificación de riesgo de fraude.

Error de procesamiento de imagen

{
  "id": "80371b2a-3ac7-432e-866d-57fe37896ac6",
  "status": 5
}

Errores comunes

Los códigos en el rango 4xx indican errores de validación con los datos proporcionados. Los códigos en el rango 5xx indican fallos del lado del servidor.

Código HTTP	Tipo de error	Causa probable	Acción recomendada
400	Bad Request	Payload inválido	Valide la estructura y el contenido.
401	Unauthorized	Token expirado o inválido	Regenere el token.
403	Forbidden	API Key incorrecta o permisos insuficientes	Verifique las credenciales.
429	Too Many Requests	Tasa de solicitudes excedida	Espere y respete el límite de TPS.
500+	Internal Server Error	Fallo interno	Reintente después de unos segundos; abra un ticket si persiste.

Manejo de errores

• Rate Limit (HTTP 429) debe ser monitoreado cuidadosamente. La sobrecarga de solicitudes puede bloquear el pipeline.
• Siempre respete el TPS acordado con Unico (consulte Acuerdo de TPS).
• Para fallos persistentes (5xx), reprocese con control de reintentos/backoff.