Criar Processo

MarkdownChatGPTClaude

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

Ambiente	URL
Produção	POST https://api.id.unico.app/processes/v1
Sandbox	POST https://api.id.uat.unico.app/processes/v1

Requisição

Headers

Header	Valor
Authorization	Bearer <access_token> (veja Autenticação)
APIKEY	Chave de API provisionada — define o produto ativo e as capacidades habilitadas.
Content-Type	application/json

Parâmetros do corpo

Integração

Campo	Tipo	Obrigatório	Descrição
subject.duiType	integer	sim	Identificador do tipo de documento. Veja os valores de duiType abaixo.
subject.code	string	sim	Valor do identificador definido por subject.duiType. Sem pontos ou traços.
subject.name	string	não	Nome completo.
subject.gender	string	não	M ou F.
subject.birthDate	string (ISO 8601)	não	Data de nascimento (YYYY-MM-DD).
subject.email	string	não	Endereço de e-mail.
subject.phone	string	não	Número de telefone E.164.
subject.clientReference	string	condicional	Identificador ú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.
useCase	string	não	Contexto da operação, ex.: Onboarding.
subsidiaryId	string	não	ID da filial — obrigatório apenas se houver múltiplas filiais.
imageBase64	string	sim	Selfie capturada pelo seu front-end, em base64.

Transacional

Campo	Tipo	Obrigatório	Descrição
references	array	condicional	Entradas de referência para fluxos de Validação 1:1. Cada item contém referenceType (REFERENCE_TYPE_IMAGE_BASE64 ou REFERENCE_TYPE_PROCESS_ID) e referenceContent (imagem codificada em base64 ou UUID de processo).
referenceProcessId	string	condicional	Descontinuado. Use references em vez disso. ID do processo de Integração de referência para comparação. Se a referência for um processo by-Unico, use authenticationInfo.authenticationId.
imageBase64	string	sim	Selfie capturada pelo seu front-end, em base64.
subject	object	não	Container de informações do usuário.
subject.duiType	string	não	Tipo de identificador. Valores possíveis: DUI_TYPE_AR_DNI, DUI_TYPE_BR_CPF, DUI_TYPE_ID_NIK, DUI_TYPE_MX_CURP, DUI_TYPE_NG_NIN, DUI_TYPE_US_SSN.
subject.code	string	não	Valor do identificador definido por subject.duiType. Sem pontos ou traços.
subject.name	string	não	Nome completo do usuário.
subject.gender	string	não	M ou F.
subject.birthDate	string (ISO 8601)	não	Data de nascimento (YYYY-MM-DD).
subject.email	string	não	Endereço de e-mail.
subject.phone	string	não	Número de telefone E.164.
useCase	string	não	Contexto da operação, ex.: Transactional.
subsidiaryId	string	não	ID da filial — obrigatório apenas se existirem múltiplas filiais.

informação

Para este produto, não é possível orquestrar com Score de Risco. O resultado é sempre retornado de forma síncrona na resposta do POST.

Cardholder Verification

Campo	Tipo	Obrigatório	Descrição
subject.duiType	integer	sim	Identificador do tipo de documento. Veja os valores de duiType abaixo. Atualmente apenas DUI_TYPE_BR_CPF.
subject.code	string	sim	CPF do titular do cartão sendo verificado. Sem pontos ou traços.
card.bin	string	condicional	Primeiros 6 ou 8 dígitos do cartão (BIN). Obrigatório em conjunto com card.last4.
card.last4	string	condicional	Últimos 4 dígitos do cartão. Obrigatório em conjunto com card.bin.
card.name	string	não	Nome do titular do cartão, como impresso no cartão.
referenceProcessId	string (UUID)	não	ID de um processo previamente validado a ser reutilizado — um com resultado aprovado de Verificação de Identidade ou Prova de Vida para o mesmo CPF. A versão atual desta capacidade é baseada em reutilização: sem esse campo, o gate nunca é disparado e a resposta assume por padrão o resultado unsure — a própria requisição nunca falha.
useCase	string	não	Contexto da operação, ex.: CardholderVerification.
subsidiaryId	string	não	ID da filial — obrigatório apenas se houver múltiplas filiais.

informação

Nenhum imageBase64 é enviado para este produto — o Cardholder Verification é executado inteiramente no back-end, sem etapa de captura de selfie.

Valores de duiType

País	Código	Descrição
AR	6	Passaporte Argentino
AR	7	DNI Argentino
AR	49	Carteira de motorista Argentina (Licencia Nacional de Conducir)
AT	34	Número de Contribuinte Austríaco (STNR)
BE	36	Número Nacional Belga (NN)
BR	1	CPF Brasileiro
BR	5	Passaporte Brasileiro
BR	14	CNPJ Brasileiro
CA	28	SIN Canadense
CH	33	Número AHV/AVS Suíço
CL	9	RUN Chileno
CL	52	Passaporte Chileno
CL	57	Carteira de motorista Chilena (Licencia de Conducir)
CO	26	NIT Colombiano
CO	53	Passaporte Colombiano
CO	55	Carteira de motorista Colombiana (Licencia de Conducción)
CO	56	Cédula de Cidadania Colombiana (Cédula de Ciudadanía)
DE	41	Número de Identificação Fiscal Alemão (IdNr)
DK	29	CPR Dinamarquês
EC	10	NI Equatoriano
ES	50	Número de Identidade de Estrangeiro Espanhol (NIE)
ES	51	Documento Nacional de Identidade Espanhol (DNI)
FI	35	Código de Identidade Pessoal Finlandês (HETU)
FR	46	Número de Referência Fiscal Francês (SPI)
GB	30	Número de Seguro Nacional Britânico (NINO)
GT	12	CUI Guatemalteco
ID	16	NIK Indonésio
IE	47	Número de Serviço Público Pessoal Irlandês (PPSN)
IT	37	Codice Fiscale Italiano (CF)
LU	48	Número de Identificação Nacional de Luxemburgo (Matricule)
MX	2	CURP Mexicano
MX	25	RFC Mexicano (Pessoa Física)
MX	58	Carteira de motorista Mexicana (Licencia de Conducir)
NG	8	NIN Nigeriano
NG	20	Número de Verificação Bancária Nigeriano (BVN)
NG	43	Token de BVN Nigeriano (hash)
NG	44	Token de NIN Nigeriano (hash)
NL	42	Número de Serviço ao Cidadão Holandês (BSN)
NO	39	Número de Identidade Nacional Norueguês (Fødselsnummer)
PE	27	RUC Peruano
PE	40	DNI Peruano
PE	54	Passaporte Peruano
PL	31	PESEL Polonês
PT	45	Número de Identificação Fiscal Português (NIF)
SE	32	Número Pessoal Sueco (PNR)
SE	38	Número de Coordenação Sueco (Samordningsnummer)
TR	24	Número de Identificação Turco (TCKN)
US	4	SSN dos Estados Unidos
US	11	Passaporte dos Estados Unidos
US	18	Carteira de motorista dos Estados Unidos
US	21	Cartão de Passaporte dos Estados Unidos
US	22	Passaporte de Policarbonato dos Estados Unidos
US	23	Carteira de Identidade dos Estados Unidos
UY	13	CI Uruguaia
ZZ	15	Endereço de e-mail
ZZ	17	Número de telefone
—	0	Não especificado
—	3	Identificador 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

Requisições comprimidas

A API suporta o envio do corpo da requisição comprimido, usando o header HTTP padrão Content-Encoding. Isso é opcional e totalmente compatível com versões anteriores: clientes que não enviam esse header continuam funcionando exatamente como antes.

Formatos suportados

Codificação	Header Content-Encoding	Status
Gzip	gzip	✅ Recomendado
Deflate	deflate	✅ Suportado
Sem compressão	(header ausente)	✅ Suportado (comportamento padrão)

Recomendação

Use gzip. É o que tem o suporte mais universal entre linguagens e bibliotecas HTTP, evitando as ambiguidades de implementação presentes em outros formatos.

A compressão é recomendada para requisições com corpo grande (ex.: payloads JSON extensos, envios de imagens codificadas em base64, submissões em lote). Para requisições pequenas, o overhead de comprimir pode não trazer um benefício relevante.

Como enviar uma requisição comprimida

1. Comprima o corpo da requisição (ex.: o JSON serializado) usando o algoritmo escolhido.
2. Envie o corpo comprimido como bytes binários na requisição.
3. Inclua o header Content-Encoding com o valor correspondente (gzip ou deflate).
4. Mantenha o Content-Type descrevendo o formato original do conteúdo (ex.: application/json), e não a codificação de transporte.

cURL

echo '{"subject":{"code":"12345678909"},"useCase":"Onboarding","imageBase64":"/9j/4AAQSkZJR..."}' | gzip > body.json.gz

curl -X POST https://api.id.unico.app/processes/v1 \
  -H "Authorization: Bearer $TOKEN" \
  -H "APIKEY: $API_KEY" \
  -H "Content-Type: application/json" \
  -H "Content-Encoding: gzip" \
  --data-binary @body.json.gz

Python (requests)

import gzip
import json
import requests

payload = {
    "subject": {"code": "12345678909"},
    "useCase": "Onboarding",
    "imageBase64": capturedImage,
}
compressed_body = gzip.compress(json.dumps(payload).encode("utf-8"))

response = requests.post(
    "https://api.id.unico.app/processes/v1",
    data=compressed_body,
    headers={
        "Authorization": f"Bearer {token}",
        "APIKEY": api_key,
        "Content-Type": "application/json",
        "Content-Encoding": "gzip",
    },
)

.NET (C#, HttpClient)

using System.IO.Compression;
using System.Text;
using System.Text.Json;

var json = JsonSerializer.Serialize(payload);
var jsonBytes = Encoding.UTF8.GetBytes(json);

using var outputStream = new MemoryStream();
using (var gzipStream = new GZipStream(outputStream, CompressionMode.Compress, leaveOpen: true))
{
    await gzipStream.WriteAsync(jsonBytes, 0, jsonBytes.Length);
}
outputStream.Position = 0;

var content = new ByteArrayContent(outputStream.ToArray());
content.Headers.ContentType = new MediaTypeHeaderValue("application/json");
content.Headers.ContentEncoding.Add("gzip");

using var client = new HttpClient();
client.DefaultRequestHeaders.Add("Authorization", $"Bearer {token}");
client.DefaultRequestHeaders.Add("APIKEY", apiKey);

var response = await client.PostAsync("https://api.id.unico.app/processes/v1", content);

dica

Para o exemplo em Python, use o parâmetro data=, não json=. O parâmetro json= serializa o payload automaticamente, mas não o comprime.

Usando deflate em vez disso: o fluxo acima é idêntico — apenas a chamada de compressão e o valor de Content-Encoding mudam.

Idioma	deflate
Bash / cURL	zlib-flate -compress < body.json > body.json.deflate (do qpdf), depois -H "Content-Encoding: deflate"
Python	zlib.compress(data) em vez de gzip.compress(data)
.NET (C#)	System.IO.Compression.DeflateStream em vez de GZipStream

deflate é ambíguo na prática

A codificação de conteúdo deflate do HTTP é especificada como um stream zlib (RFC 1950), mas alguns clientes e servidores historicamente emitem ou esperam DEFLATE bruto (RFC 1951) em vez disso. Esta API espera o stream padrão envolto em zlib — a mesma saída que zlib.compress() (Python) ou DeflateStream (.NET) produzem por padrão. Em caso de dúvida, prefira gzip, que não tem essa ambiguidade.

Comportamento em caso de erro

Se Content-Encoding for enviado com um valor não suportado, ou se o corpo estiver corrompido ou inválido para a codificação declarada, a API retorna 400 Bad Request com uma mensagem indicando que a descompressão do corpo da requisição falhou.

FAQ

Preciso alterar algo se eu não quiser usar compressão? Não. O suporte a Content-Encoding é aditivo — requisições sem esse header continuam sendo processadas normalmente.

Isso afeta a resposta da API? Não. Esse recurso diz respeito apenas ao corpo enviado pelo cliente (requisição). A compressão da resposta (o que a API retorna) é controlada separadamente pelo header Accept-Encoding.

Qual formato eu devo escolher? Use gzip, a menos que alguma restrição específica do seu ambiente exija outro formato.

Exemplo

Integração — cURL

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..."
  }'

Integração — Node.js

import fetch from 'node-fetch';

const res = await fetch('https://api.id.unico.app/processes/v1', {
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${process.env.UNICO_ACCESS_TOKEN}`,
    'APIKEY': process.env.UNICO_API_KEY,
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    subject: {
      duiType: 1,
      code: '12345678909',
      name: 'Luke Skywalker',
      gender: 'M',
      birthDate: '2000-05-20',
      email: '[email protected]',
      phone: '5519725570707'
    },
    useCase: 'Onboarding',
    imageBase64: capturedImage
  })
});

const result = await res.json();

Transacional — cURL

curl -X POST https://api.id.unico.app/processes/v1 \
  -H "Authorization: Bearer $TOKEN" \
  -H "APIKEY: $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "references": [
      {
        "referenceType": "REFERENCE_TYPE_PROCESS_ID",
        "referenceContent": "4f00b35f-69d4-415a-a843-d975cefcb169"
      }
    ],
    "useCase": "Transactional",
    "imageBase64": "/9j/4AAQSkZJR..."
  }'

Transacional — Node.js

import fetch from 'node-fetch';

const res = await fetch('https://api.id.unico.app/processes/v1', {
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${process.env.UNICO_ACCESS_TOKEN}`,
    'APIKEY': process.env.UNICO_API_KEY,
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    references: [
      {
        referenceType: 'REFERENCE_TYPE_PROCESS_ID',
        referenceContent: '4f00b35f-69d4-415a-a843-d975cefcb169'
      }
    ],
    useCase: 'Transactional',
    imageBase64: capturedImage
  })
});

const result = await res.json();

Cardholder Verification — cURL

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"
    },
    "card": {
      "bin": "12345678",
      "last4": "4321",
      "name": "Luke Skywalker"
    },
    "referenceProcessId": "4f00b35f-69d4-415a-a843-d975cefcb169",
    "useCase": "CardholderVerification"
  }'

Cardholder Verification — Node.js

import fetch from 'node-fetch';

const res = await fetch('https://api.id.unico.app/processes/v1', {
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${process.env.UNICO_ACCESS_TOKEN}`,
    'APIKEY': process.env.UNICO_API_KEY,
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    subject: {
      duiType: 1,
      code: '12345678909'
    },
    card: {
      bin: '12345678',
      last4: '4321',
      name: 'Luke Skywalker'
    },
    referenceProcessId: '4f00b35f-69d4-415a-a843-d975cefcb169',
    useCase: 'CardholderVerification'
  })
});

const result = await res.json();

Respostas

Integração

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

Campo	Tipo	Descrição
id	string (UUID)	Identificador do processo. Use com Obter Processo para reconsultas.
status	integer	1 (processando), 3 (finalizado com sucesso), 5 (erro).

Valores possíveis de resultado

idCloud.result	Significado	Ação recomendada
approved	Pessoa real e identidade validada.	Prossiga com o fluxo.
denied	Identidade não validada, falha na prova de vida, ou risco extremo identificado.	Encerre o fluxo ou redirecione para um fluxo alternativo.
critical-risk	Nível de risco crítico identificado.	Encerre o fluxo ou encaminhe para revisão manual.
high-risk	Nível de risco alto identificado.	Encaminhe para revisão manual ou para um fluxo alternativo.
retry	Captura ou score insuficiente para avaliação.	Solicite uma nova captura ao usuário.
inconclusive	Evidências insuficientes para um veredito.	Encaminhe para revisão manual ou para um fluxo alternativo.

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

Clientes 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.

Campo	Tipo	Descrição
unicoId.result	string	yes, no, inconclusive — veja Verificação de Identidade.
riskLevel.result	string	approved, reproved, risk-critical, risk-high, inconclusive — veja os valores possíveis abaixo ou a Classificação de Risco de Fraude.
idFace.result	string	FOUND — veja Identificador Facial.
idFace.personId	string	Identificador 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.result	string	Obsoleto. 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.serpro	integer	Score de similaridade Serpro (0–100, -1, -2). Disponível apenas no Brasil. Veja Retorno de Semelhança do Serpro.
liveness	integer	1 (aprovado), 2 (reprovado) — veja Prova de Vida.

riskLevel.result — valores possíveis

Valor	Significado
approved	É o rosto do titular do documento e nenhuma evidência relacionada a fraude foi encontrada.
reproved	A rejeição é recomendada, pois múltiplos indicadores de fraude foram detectados.
risk-critical	A 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-high	A 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.
inconclusive	Nenhuma 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.

Clientes no México podem receber o bloco de Verificação RENAPO

A resposta mantém a mesma estrutura e acrescenta o bloco idGov.

Integrações no México com a Verificação RENAPO habilitada recebem um bloco idGov adicional com o registro que o RENAPO mantém para a CURP do usuário. É uma resposta separada do resultado de identidade.

{
  "id": "11111111-2222-3333-4444-555555555555",
  "status": 3,
  "idCloud": { "result": "approved" },
  "idGov": {
    "government_valid": true,
    "curp": "PUEA880304MDFRJN04",
    "government_name": "ANA PRUEBA EJEMPLO",
    "date_of_birth": "1988-03-04",
    "age": 38,
    "gender": "F",
    "deceased": false,
    "is_mexican": true,
    "citizenship": "MEXICO",
    "state_of_birth": "Ciudad de México",
    "state_iso": "MX-CMX",
    "issuing_entity_code": "DF",
    "municipality_registration": ""
  }
}

Campo	Tipo	Descrição
idGov	object	Registro do RENAPO para a CURP. Ausente quando a capability não está habilitada. {} quando o RENAPO não respondeu. Apenas México. Veja Verificação RENAPO.

Transacional

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

Campo	Tipo	Descrição
id	string (UUID)	Identificador do processo.
status	integer	3 (finalizado com sucesso), 5 (erro). Para todos os valores possíveis, veja Obter Processo.

Valores possíveis de resultado

idCloud.result	Significado	Ação recomendada
approved	Pessoa real e identidade validada.	Prossiga com o fluxo.
denied	Identidade não validada, falha na prova de vida, ou risco extremo identificado.	Encerre o fluxo ou redirecione para um fluxo alternativo.
critical-risk	Nível de risco crítico identificado.	Encerre o fluxo ou encaminhe para revisão manual.
high-risk	Nível de risco alto identificado.	Encaminhe para revisão manual ou para um fluxo alternativo.
retry	Captura ou score insuficiente para avaliação.	Solicite uma nova captura ao usuário.
inconclusive	Evidências insuficientes para um veredito.	Encaminhe para revisão manual ou para um fluxo alternativo.

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

Clientes 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,
  "biometryToken": {
    "result": true
  },
  "liveness": 1
}

Campo	Tipo	Descrição
biometryToken.result	boolean	true se o rosto enviado corresponde ao processo de referência; false caso contrário.
liveness	integer	1 (aprovado), 2 (reprovado) — veja Prova de Vida.

Cardholder Verification

200 OK

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

Campo	Tipo	Descrição
id	string (UUID)	Identificador do processo.
status	integer	1 (processando), 3 (finalizado com sucesso), 5 (erro). Para todos os valores, veja Obter Processo.
cardholderVerification.result	string	approved — o CPF e o cartão pertencem à mesma pessoa. unsure — o gate de reutilização não foi satisfeito, ou a verificação em si foi inconclusiva. Ausente enquanto status ainda não é 3. Veja Cardholder Verification.

Códigos de Erro

400 Bad Request

Código	Mensagem	Descrição
40221	This 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.
20900	O 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.
20807	A 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.
20532	No face detected in image.	Nenhum rosto foi detectado na imagem enviada.
20513	The referenced process was not found.	O referenceProcessId aponta para um processo que não existe ou não está mais acessível.
20512	The referenced process is not available for reuse.	O processo referenciado existe mas não está disponível para reutilização.
20509	The subject.name field is invalid.	subject.name contém caracteres inválidos.
20508	The subject.gender field is invalid.	subject.gender deve ser M ou F.
20507	O parâmetro subject.code é inválido.	CPF fora do padrão ou inexistente.
20506	O base64 informado é muito grande. O tamanho máximo suportado é até 800kb.	Tamanho da imagem excede 800 KB; comprima para JPEG92.
20505	O base64 informado não é suportado. Os formatos aceitos são png, jpeg e webp.	O formato base64 é inválido ou não suportado.
20065	The referenceProcessId field is invalid.	O referenceProcessId não é um UUID válido.
20062	The useCase field is invalid.	Valor não reconhecido no campo useCase.
20024	The 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.
20533	The card field is missing.	Cardholder Verification: o objeto card não foi fornecido.
20534	The card.bin field is missing.	Cardholder Verification: card.bin não foi fornecido.
20535	The card.last4 field is missing.	Cardholder Verification: card.last4 não foi fornecido.
20536	The card data is invalid.	Cardholder Verification: os dados do cartão foram rejeitados como inválidos.
20021	The subject.phone field is invalid.	Formato de subject.phone inválido (DDI + código de área + número, 13 caracteres).
20019	The subject.birthDate field is invalid.	subject.birthDate está fora do formato ISO 8601 (YYYY-MM-DD).
20009	O parâmetro imagebase64 não foi informado.	O parâmetro de imagem selfie está ausente.
20008	The subject.email field is invalid.	Formato de e-mail inválido em subject.email.
20006	O parâmetro subject.name não foi informado.	O parâmetro subject.name está ausente.
20005	O parâmetro subject.code não foi informado.	O parâmetro subject.code está ausente.
20004	O parâmetro subject não foi informado.	O parâmetro subject está ausente.
20003	The request body is missing or invalid.	Payload nulo ou inválido.
20002	O parâmetro APIKey não foi informado.	O parâmetro APIKEY está ausente no header da requisição.
20001	O parâmetro authtoken não foi informado.	O parâmetro de token de integração está ausente no header da requisição.
10508	The JWT with the captured face has already been used.	O JWT só pode ser usado uma vez.
10507	The JWT with the captured face is expired.	JWT expirado; deve ser enviado dentro de 10 minutos.
10506	The imageBase64 field is not a valid JWT from SDK.	O imageBase64 não é um JWT válido gerado pelo SDK.

403 Forbidden

Bearer token ou APIKEY ausente, expirado ou inválido. Veja Autenticação.

Código	Mensagem	Descrição
30017	User does not have permission to perform this action.	JWT malformado ou usuário sem permissão para executar esta operação.
10502	O token informado está expirado.	O access-token expirou.
10501	O token informado é inválido.	O token de autenticação é inválido.
10201	O AppKey informado é inválido.	A APIKEY é inválida ou não existe.

409 Conflict

Código	Mensagem	Descrição
20073	The processID already exists.	O processId fornecido já existe para este tenant.

429 Too Many Requests

Limite de requisições atingido. Quando seu sistema recebe um erro HTTP 429, você deve implementar mecanismos para prevenir falhas em cascata e evitar agravar a restrição.

Boas práticas:

• Período de espera (backoff): Interrompa ou limite imediatamente as requisições subsequentes do seu sistema. Não tente reenviar requisições falhas continuamente em um loop apertado.
• Enfileiramento e controle de fluxo: Armazene ou enfileire as requisições de saída do seu lado para controlar o fluxo de tráfego antes de reenviá-las.
• Backoff exponencial com jitter: Ao tentar novamente, aumente o tempo de espera exponencialmente entre as tentativas (ex.: 1 s, 2 s, 4 s, 8 s) e adicione um pequeno atraso aleatório ("jitter") para evitar um efeito manada onde todas as requisições enfileiradas tentam novamente no exato mesmo milissegundo.

aviso

Continuar acessando um endpoint com limite de taxa sem aplicar backoff pode prolongar o período de restrição e impactar severamente a taxa de transferência operacional do seu sistema. Controlar adequadamente as requisições do seu lado garante uma integração mais suave e resiliente.

Para limites padrão, aumento de requisições e detalhes adicionais, veja Limites de Taxa.

500 Internal Server Error

Código	Mensagem	Descrição
99999	Internal failure! Try again later	Quando há um erro interno.

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.