Pular para o conteúdo principal

Criar Processo

Este endpoint lida com três produtos que compartilham o mesmo caminho mas diferem nos parâmetros do corpo, capacidades e campos de resposta:

  • Integração — valida quem é o usuário comparando seu rosto com a base de identidade da Unico (subject.duiType + subject.code obrigatório).
  • Transacional — verifica se é a mesma pessoa de um processo anterior comparando rosto-a-rosto (referenceProcessId OU array references com selfie / ID de processo obrigatório).
  • Cardholder Verification — confirma que um cartão pertence ao seu titular declarado, sem nenhuma captura de selfie (subject.code + card obrigatórios). Opcionalmente reutiliza um processo previamente validado via referenceProcessId para disparar o gate de reutilização; sem ele, a resposta assume por padrão o resultado unsure. Veja a capacidade Cardholder Verification.

O produto ativo é determinado pela APIKEY enviada no header da requisição.

Para o fluxo completo de integração, veja Visão Geral da API.

Endpoint

AmbienteURL
ProduçãoPOST https://api.id.unico.app/processes/v1
SandboxPOST https://api.id.uat.unico.app/processes/v1

Requisição

Headers
HeaderValor
AuthorizationBearer <access_token> (veja Autenticação)
APIKEYChave de API provisionada — define o produto ativo e as capacidades habilitadas.
Content-Typeapplication/json
Parâmetros do corpo
CampoTipoObrigatórioDescrição
subject.duiTypeintegersimIdentificador do tipo de documento. Veja os valores de duiType abaixo.
subject.codestringsimValor do identificador definido por subject.duiType. Sem pontos ou traços.
subject.namestringnãoNome completo.
subject.genderstringnãoM ou F.
subject.birthDatestring (ISO 8601)nãoData de nascimento (YYYY-MM-DD).
subject.emailstringnãoEndereço de e-mail.
subject.phonestringnãoNúmero de telefone E.164.
subject.clientReferencestringcondicionalIdentificador único do usuário no seu sistema. Obrigatório para a capacidade Multi Contas. Único na sua base, máximo de 256 caracteres, sem espaços.
useCasestringnãoContexto da operação, ex.: Onboarding.
subsidiaryIdstringnãoID da filial — obrigatório apenas se houver múltiplas filiais.
imageBase64stringsimSelfie capturada pelo seu front-end, em base64.
Valores de duiType
PaísCódigoDescrição
BR1CPF Brasileiro
MX2CURP Mexicano
US4SSN dos Estados Unidos
BR5Passaporte Brasileiro
AR6Passaporte Argentino
AR7DNI Argentino
NG8NIN Nigeriano
CL9RUN Chileno
EC10NI Equatoriano
US11Passaporte dos Estados Unidos
GT12CUI Guatemalteco
UY13CI Uruguaia
BR14CNPJ Brasileiro
ZZ15Endereço de e-mail
ID16NIK Indonésio
ZZ17Número de telefone
US18Carteira de motorista dos Estados Unidos
NG20Número de Verificação Bancária Nigeriano (BVN)
US21Cartão de Passaporte dos Estados Unidos
US22Passaporte de Policarbonato dos Estados Unidos
US23Carteira de Identidade dos Estados Unidos
TR24Número de Identificação Turco (TCKN)
MX25RFC Mexicano (Pessoa Física)
CO26NIT Colombiano
PE27RUC Peruano
CA28SIN Canadense
DK29CPR Dinamarquês
GB30Número de Seguro Nacional Britânico (NINO)
PL31PESEL Polonês
SE32Número Pessoal Sueco (PNR)
CH33Número AHV/AVS Suíço
AT34Número de Contribuinte Austríaco (STNR)
FI35Código de Identidade Pessoal Finlandês (HETU)
BE36Número Nacional Belga (NN)
IT37Codice Fiscale Italiano (CF)
SE38Número de Coordenação Sueco (Samordningsnummer)
NO39Número de Identidade Nacional Norueguês (Fødselsnummer)
PE40DNI Peruano
DE41Número de Identificação Fiscal Alemão (IdNr)
NL42Número de Serviço ao Cidadão Holandês (BSN)
NG43Token de BVN Nigeriano (hash)
NG44Token de NIN Nigeriano (hash)
PT45Número de Identificação Fiscal Português (NIF)
FR46Número de Referência Fiscal Francês (SPI)
IE47Número de Serviço Público Pessoal Irlandês (PPSN)
LU48Número de Identificação Nacional de Luxemburgo (Matricule)
AR49Carteira de motorista Argentina (Licencia Nacional de Conducir)
ES50Número de Identidade de Estrangeiro Espanhol (NIE)
ES51Documento Nacional de Identidade Espanhol (DNI)
CL52Passaporte Chileno
CO53Passaporte Colombiano
PE54Passaporte Peruano
CO55Carteira de motorista Colombiana (Licencia de Conducción)
CO56Cédula de Cidadania Colombiana (Cédula de Ciudadanía)
CL57Carteira de motorista Chilena (Licencia de Conducir)
MX58Carteira de motorista Mexicana (Licencia de Conducir)
0Não especificado
3Identificador interno Unico
Requisitos de imagem
  • Resolução mínima: 640 x 480 (padrão HD)
  • Tamanho máximo do arquivo: 800 KB (compressão JPEG92 recomendada)
  • Formatos aceitos: PNG, JPEG, WebP
  • Tokens JWT do SDK expiram após 10 minutos e podem ser usados apenas uma vez

Exemplo

curl -X POST https://api.id.unico.app/processes/v1 \
-H "Authorization: Bearer $TOKEN" \
-H "APIKEY: $API_KEY" \
-H "Content-Type: application/json" \
-d '{
"subject": {
"duiType": 1,
"code": "12345678909",
"name": "Luke Skywalker",
"gender": "M",
"birthDate": "2000-05-20",
"email": "[email protected]",
"phone": "5519725570707"
},
"useCase": "Onboarding",
"imageBase64": "/9j/4AAQSkZJR..."
}'

Respostas

200 OK

O contrato é único — o campo idCloud.result carrega o veredito consolidado das capacidades utilizadas.

A Unico consolida os resultados das capacidades executadas em um único idCloud.result, pronto para decidir o próximo passo do seu fluxo — sem necessidade de orquestrar resultados individuais.

{
"id": "80371b2a-3ac7-432e-866d-57fe37896ac6",
"status": 3,
"idCloud": {
"result": "approved"
}
}
CampoTipoDescrição
idstring (UUID)Identificador do processo. Use com Obter Processo para reconsultas.
statusinteger1 (processando), 3 (finalizado com sucesso), 5 (erro).
Valores possíveis de resultado
idCloud.resultMeaningRecommended action
approvedReal person and validated identity.Proceed with the flow.
deniedIdentity not validated, liveness check failed, or extreme risk identified.End the flow or redirect to an alternative flow.
critical-riskCritical risk level identified.End the flow or route to manual review.
high-riskHigh risk level identified.Route to manual review or an alternative flow.
retryInsufficient capture or score to evaluate.Ask the user for a new capture.
inconclusiveNot enough evidence for a verdict.Route to manual review or an alternative flow.

Os valores retornados dependem da receita configurada na sua APIKey. Veja Fluxos os valores de resultado que cada receita pode retornar.

BrazilClientes no Brasil podem receber a resposta por capacidade

A estrutura geral da resposta permanece a mesma — o resultado único é o padrão.

Integrações no Brasil podem receber os resultados abertos, por capacidade. Cada capacidade habilitada na APIKey adiciona seu próprio bloco à resposta — campos de capacidades desabilitadas são omitidos.

{
"id": "80371b2a-3ac7-432e-866d-57fe37896ac6",
"status": 3,
"unicoId": {
"result": "yes"
},
"riskLevel": {
"result": "inconclusive"
},
"idFace": {
"personId": "a1b2c3d4e5f67890a1b2c3d4e5f67890a1b2c3d4e5f67890a1b2c3d4e5f67890",
"result": "FOUND"
},
"government": {
"serpro": 87
},
"liveness": 1
}
Os campos da resposta dependem da sua APIKey

O exemplo acima exibe todos os campos de capacidades possíveis. Sua resposta real incluirá apenas os campos das capacidades habilitadas na configuração da sua APIKey — campos de capacidades desabilitadas são omitidos. Entre em contato com o gerente de projetos da Unico para habilitar ou ajustar capacidades.

CampoTipoDescrição
unicoId.resultstringyes, no, inconclusive — veja Verificação de Identidade.
riskLevel.resultstringapproved, reproved, risk-critical, risk-high, inconclusive — veja os valores possíveis abaixo ou a Classificação de Risco de Fraude.
idFace.resultstringFOUND — veja Identificador Facial.
idFace.personIdstringIdentificador opaco estável para o rosto, retornado junto com idFace.result = FOUND. Quando nenhum rosto pode ser identificado na imagem, a requisição falha com o erro 20532 em vez de retornar um bloco idFace.
identityFraudsters.resultstringObsoleto. Use riskLevel em vez disso. Clientes com integrações em andamento podem continuar utilizando enquanto alinham a migração com a equipe responsável pelo projeto.
government.serprointegerScore de similaridade Serpro (0–100, -1, -2). Disponível apenas no Brasil. Veja Retorno de Semelhança do Serpro.
livenessinteger1 (aprovado), 2 (reprovado) — veja Prova de Vida.
riskLevel.result — valores possíveis
ValorSignificado
approvedÉ o rosto do titular do documento e nenhuma evidência relacionada a fraude foi encontrada.
reprovedA rejeição é recomendada, pois múltiplos indicadores de fraude foram detectados.
risk-criticalA rejeição é recomendada, mas a decisão final fica a seu critério. Risco crítico indica que encontramos pelo menos 2 fortes evidências de fraude.
risk-highA rejeição também é recomendada, mas a decisão permanece sendo sua. Risco alto indica que encontramos pelo menos uma forte evidência de fraude.
inconclusiveNenhuma evidência forte de fraude foi encontrada. Portanto, não é possível concluir se há risco relevante ou não.
informação

Quando unicoId.result = inconclusive e a orquestração de Score de Risco está ativa, o processo pode retornar status: 1 (processando). Consulte Obter Processo ou use webhooks para recuperar o resultado final.

Códigos de Erro

CódigoMensagemDescrição
40221This flow does not support reusing a prior process (referenceProcessId or bioTokenId) without an image; send an image (imageBase64, or references[0] with type IMAGE_BASE64) instead.O fluxo de reutilização (referenceProcessId/bioTokenId, sem imagem) foi rejeitado porque a reutilização de processo não está habilitada para esta API key.
20900O base64 informado não é válido.O parâmetro base64 é inválido. Causas possíveis: não é uma imagem ou é uma tentativa de injeção.
20807A imagem precisa estar no padrão HD ou possuir uma resolução superior a 640 x 480.A resolução da imagem enviada é muito baixa.
20532No face detected in image.Nenhum rosto foi detectado na imagem enviada.
20513The referenced process was not found.O referenceProcessId aponta para um processo que não existe ou não está mais acessível.
20512The referenced process is not available for reuse.O processo referenciado existe mas não está disponível para reutilização.
20509The subject.name field is invalid.subject.name contém caracteres inválidos.
20508The subject.gender field is invalid.subject.gender deve ser M ou F.
20507O parâmetro subject.code é inválido.CPF fora do padrão ou inexistente.
20506O base64 informado é muito grande. O tamanho máximo suportado é até 800kb.Tamanho da imagem excede 800 KB; comprima para JPEG92.
20505O base64 informado não é suportado. Os formatos aceitos são png, jpeg e webp.O formato base64 é inválido ou não suportado.
20065The referenceProcessId field is invalid.O referenceProcessId não é um UUID válido.
20062The useCase field is invalid.Valor não reconhecido no campo useCase.
20024The referenceProcessId field is missing.O parâmetro referenceProcessId não foi fornecido e references não foi enviado como alternativa. Não se aplica ao Cardholder Verification — o referenceProcessId desse produto nunca é validado como obrigatório; um gate de reutilização não satisfeito responde unsure em vez disso.
20533The card field is missing.Cardholder Verification: o objeto card não foi fornecido.
20534The card.bin field is missing.Cardholder Verification: card.bin não foi fornecido.
20535The card.last4 field is missing.Cardholder Verification: card.last4 não foi fornecido.
20536The card data is invalid.Cardholder Verification: os dados do cartão foram rejeitados como inválidos.
20021The subject.phone field is invalid.Formato de subject.phone inválido (DDI + código de área + número, 13 caracteres).
20019The subject.birthDate field is invalid.subject.birthDate está fora do formato ISO 8601 (YYYY-MM-DD).
20009O parâmetro imagebase64 não foi informado.O parâmetro de imagem selfie está ausente.
20008The subject.email field is invalid.Formato de e-mail inválido em subject.email.
20006O parâmetro subject.name não foi informado.O parâmetro subject.name está ausente.
20005O parâmetro subject.code não foi informado.O parâmetro subject.code está ausente.
20004O parâmetro subject não foi informado.O parâmetro subject está ausente.
20003The request body is missing or invalid.Payload nulo ou inválido.
20002O parâmetro APIKey não foi informado.O parâmetro APIKEY está ausente no header da requisição.
20001O parâmetro authtoken não foi informado.O parâmetro de token de integração está ausente no header da requisição.
10508The JWT with the captured face has already been used.O JWT só pode ser usado uma vez.
10507The JWT with the captured face is expired.JWT expirado; deve ser enviado dentro de 10 minutos.
10506The imageBase64 field is not a valid JWT from SDK.O imageBase64 não é um JWT válido gerado pelo SDK.

Próximos passos

  • Para consultar o resultado de um processo de Integração, veja Obter Processo.
  • Para ver todas as combinações de receitas e seus valores de resultado possíveis, veja Fluxos.
  • Para operações de Documento e Verificação de Idade, veja as respectivas páginas nesta seção.