Reprocessamento e Importação de Base Biométrica

Este guia aborda como realizar reprocessamento ou importação de base biométrica na plataforma Unico. Ele detalha os requisitos técnicos e operacionais para uma integração eficaz e segura, seguindo as melhores práticas da plataforma.

Escopo

Este material cobre dois tipos de processos:

• Reprocessamento: reprocessamento de registros biométricos de usuários que já passaram pela base do cliente e da Unico para reavaliação ou migração entre sistemas.
• Importação de Base Biométrica: upload inicial ou atualização de uma base contendo selfies para fins de verificação de identidade e/ou classificação de risco.
• Importação de Base de Documentos: upload de uma base de documentos junto com selfies para fins de verificação por Facematch ou CPF Match (somente Brasil).

Pré-requisitos

• O cliente deve ter um contrato ativo ou NDA assinado com a Unico e estar na fase de integração (exceção se aprovado pela equipe de governança).
• O projeto seguirá acordos formais de TPS (transações por segundo). Veja Acordo de TPS abaixo.
• Antes de obter credenciais de produção, a homologação completa da integração é obrigatória para garantir qualidade dos dados, conformidade do payload e desempenho estável.
• Uma conta de serviço dedicada deve ser criada para o reprocessamento ou importação (ex.: "Reprocessamento" ou "Legacy_Import").
• Uma API Key dedicada será criada especificamente para o reprocessamento/importação.
• (Opcional) Uma subsidiária dedicada pode ser criada para o reprocessamento/importação. Este parâmetro é identificado no payload como subsidiaryId. Veja Parâmetros do payload abaixo.
• A API Key e a conta de serviço serão desativadas após o período acordado ou conclusão do processamento.

Capacidades disponíveis

Capacidade	Descrição
Verificação de Identidade	Verifica se a selfie enviada pertence ao real titular do identificador.
Classificação de risco de fraude	Verifica se há histórico de comportamento fraudulento associado àquele rosto.
Facematch	Verifica se a foto do documento corresponde à selfie enviada.
CPF Match Brazil only	Verifica se o CPF fornecido corresponde ao número de CPF impresso no documento. Observação: nem todos os RGs possuem o CPF impresso.

Requisitos da selfie

• Deve ser enviada em formato base64.
• A imagem deve seguir o padrão ICAO (fundo claro, rosto centralizado, sem acessórios que obstruam a identificação, iluminação adequada).
• Dimensões recomendadas: proporção 1920x1080 ou 1080x1920.
• Tamanho máximo: 800 KB (comprima com JPEG 92 se necessário).
• Orientação: retrato.

Requisitos do documento

• Tipos de documento suportados: veja Captura de Documentos e Reutilização — Documentos suportados.
• As imagens devem incluir a frente e o verso do documento, totalmente visíveis e sem cortes.
• O documento deve estar legível — nítido, bem iluminado e livre de obstruções.

Acordo de TPS

• O TPS máximo acordado para este projeto é de 10 TPS.
• Distribua as requisições de forma uniforme ao longo do tempo em vez de enviá-las em grandes rajadas.
• Este limite não deve ser excedido sem aprovação formal da equipe Unico.
• Requisições acima do limite podem ser automaticamente descartadas ou bloqueadas.
• Se um aumento temporário for necessário, é exigido um acordo formal prévio.

Integração

Endpoints

Ambiente	URL Base	Acesso	Observações
Staging	https://api.id.uat.unico.app	Aberto	Obrigatório para testes
Produção	https://api.id.unico.app	Somente após homologação aprovada	Requer controle rigoroso de TPS

Headers obrigatórios

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

Parâmetros do 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	Obrigatório	Descrição
subject	object	Sim	Dados de identificação do usuário.
subject.duiType	integer	Sim	Identificador do tipo de documento. Veja os valores de duiType abaixo.
subject.code	string	Sim	CPF ou outro identificador do usuário.
subject.name	string	Sim	Nome completo do usuário.
subject.email	string	Não	E-mail do usuário.
subject.phone	string	Não	Número de telefone do usuário.
subject.birthDate	string	Não	Data de nascimento do usuário (DD/MM/YYYY).
subject.gender	string	Não	Gênero do usuário (M ou F).
useCase	string	Sim	Nome do caso de uso ("Reprocessamento" ou "Importação de base").
subsidiaryId	string	Não	UUID da subsidiária (fornecido pela Unico).
imageBase64	base64	Sim	Imagem de selfie do usuário convertida em base64.
document	object	Não	Dados do documento associado ao processo.
document.purpose	string	Não	Finalidade do documento (ex.: "Reprocessamento").
document.documentId	string	Não	Identificador do documento.
document.files	array	Não	Lista de arquivos de imagem do documento.
document.files[].data	base64	Não	Imagem do documento convertida em base64.
document.files[].faceDocumentMatch	boolean	Não	Indica se o rosto no documento corresponde à selfie enviada.

Valores de duiType

Valor	Descrição
0	Não especificado
1	Brasil — CPF
2	México — CURP
3	Identificador interno Unico
4	Estados Unidos — SSN
5	Brasil — Passaporte
6	Argentina — Passaporte
7	Argentina — DNI
8	Nigéria — NIN
9	Chile — RUN
10	Equador — NI
11	Estados Unidos — Passaporte
12	Guatemala — CUI
13	Uruguai — CI
15	Endereço de e-mail
16	Indonésia — NIK
17	Número de telefone
18	Estados Unidos — Carteira de motorista

Observações importantes

• A selfie deve estar em conformidade com o padrão ICAO com qualidade e iluminação adequadas.
• A selfie deve estar em formato base64.
• Evite envios em massa sem controle de TPS — isso pode acionar limitação de taxa (veja Tratamento de erros abaixo).
• Sempre teste dados e integração no ambiente de staging primeiro.

Respostas

Sucesso — 200 OK

Sem documento

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

Campo	Tipo	Descrição
id	string	Identificador do processo. Armazene-o para consultas futuras ou caso implemente Validação 1:1 posteriormente.
status	integer	Status da transação.
unicoId.result	string	Resposta da capacidade Verificação de Identidade.
identityFraudsters.result	string	Resposta da capacidade Classificação de risco de fraude.

Com documento (Facematch)

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

Campo	Tipo	Descrição
id	string	Identificador do processo. Armazene-o para consultas futuras ou caso implemente Validação 1:1 posteriormente.
status	integer	Status da transação.
score	number	Pontuação do Facematch.
unicoId.result	string	Resposta da capacidade Verificação de Identidade.
faceDocumentMatch.faceMatch	boolean	Se a foto do documento corresponde à selfie enviada.
identityFraudsters.result	string	Resposta da capacidade Classificação de risco de fraude.

Erro de processamento de imagem

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

Erros comuns

Códigos na faixa 4xx indicam erros de validação nos dados fornecidos. Códigos na faixa 5xx indicam falhas no lado do servidor.

Código HTTP	Tipo de Erro	Causa Provável	Ação Recomendada
400	Bad Request	Payload inválido	Valide a estrutura e o conteúdo.
401	Unauthorized	Token expirado ou inválido	Regenere o token.
403	Forbidden	API Key incorreta ou permissões insuficientes	Verifique as credenciais.
429	Too Many Requests	Taxa de requisições excedida	Aguarde e respeite o limite de TPS.
500+	Internal Server Error	Falha interna	Tente novamente após alguns segundos; abra um ticket se persistir.

Tratamento de erros

• Rate Limit (HTTP 429) deve ser monitorado com atenção. Sobrecarga de requisições pode bloquear o pipeline.
• Sempre respeite o TPS acordado com a Unico (veja Acordo de TPS).
• Para falhas persistentes (5xx), reprocesse com controle de retry/backoff.