Reprocesamiento e importación de base biométrica

MarkdownChatGPTClaude

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: 1080x1920 (vertical) o 1920x1080 (horizontal).
• 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

País	Código	Descripción
AR	6	Pasaporte argentino
AR	7	DNI argentino
AR	49	Licencia de conducir argentina (Licencia Nacional de Conducir)
AT	34	Número de impuesto austríaco (STNR)
BE	36	Número Nacional belga (NN)
BR	1	CPF brasileño
BR	5	Pasaporte brasileño
BR	14	CNPJ brasileño
CA	28	SIN canadiense
CH	33	Número AHV/AVS suizo
CL	9	RUN chileno
CL	52	Pasaporte chileno
CL	57	Licencia de conducir chilena (Licencia de Conducir)
CO	26	NIT colombiano
CO	53	Pasaporte colombiano
CO	55	Licencia de conducir colombiana (Licencia de Conducción)
CO	56	Cédula de Ciudadanía colombiana (Cédula de Ciudadanía)
DE	41	Número de Identificación Fiscal alemán (IdNr)
DK	29	CPR danés
EC	10	NI ecuatoriano
ES	50	Número de Identidad de Extranjero español (NIE)
ES	51	Documento Nacional de Identidad español (DNI)
FI	35	Código de identidad personal finlandés (HETU)
FR	46	Número de Referencia Fiscal francés (SPI)
GB	30	Número de Seguro Nacional británico (NINO)
GT	12	CUI guatemalteco
ID	16	NIK indonesio
IE	47	Número de Seguro Social Personal irlandés (PPSN)
IT	37	Código Fiscal italiano (CF)
LU	48	Número de Identificación Nacional de Luxemburgo (Matricule)
MX	2	CURP mexicano
MX	25	RFC mexicano (Persona Física)
MX	58	Licencia de conducir mexicana (Licencia de Conducir)
NG	8	NIN nigeriano
NG	20	Número de Verificación Bancaria nigeriano (BVN)
NG	43	Token BVN nigeriano (hash)
NG	44	Token NIN nigeriano (hash)
NL	42	Número de Servicio al Ciudadano holandés (BSN)
NO	39	Número de Identidad Nacional noruego (Fødselsnummer)
PE	27	RUC peruano
PE	40	DNI peruano
PE	54	Pasaporte peruano
PL	31	PESEL polaco
PT	45	Número de Identificación Fiscal portugués (NIF)
SE	32	Número personal sueco (PNR)
SE	38	Número de Coordinación sueco (Samordningsnummer)
TR	24	Número de Identificación turco (TCKN)
US	4	SSN de Estados Unidos
US	11	Pasaporte de Estados Unidos
US	18	Licencia de conducir de Estados Unidos
US	21	Tarjeta de pasaporte de Estados Unidos
US	22	Pasaporte de policarbonato de Estados Unidos
US	23	Tarjeta de identificación de Estados Unidos
UY	13	CI uruguayo
ZZ	15	Dirección de correo electrónico
ZZ	17	Número de teléfono
—	0	No especificado
—	3	Identificador interno de Unico

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.