Criar Processo

Este endpoint lida com dois casos de uso 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).

O caso de uso 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 caso de uso ativo e as capacidades habilitadas.
`Content-Type`	`application/json`

Parâmetros do corpo

Integração
Transacional

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

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_BR_CPF`, `DUI_TYPE_MX_CURP`, `DUI_TYPE_US_SSN`, `DUI_TYPE_NG_NIN`, `DUI_TYPE_AR_DNI`, `DUI_TYPE_ID_NIK`.
`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 caso de uso, não é possível orquestrar com Score de Risco. O resultado é sempre retornado de forma síncrona na resposta do POST.

Valores de duiType

País	Código	Descrição
BR	1	CPF Brasileiro
BR	5	Passaporte Brasileiro
MX	2	CURP Mexicano
AR	6	Passaporte Argentino
AR	7	DNI Argentino
US	4	SSN dos Estados Unidos
US	11	Passaporte dos Estados Unidos
US	18	Carteira de motorista dos Estados Unidos
ID	16	NIK Indonésio
NG	8	NIN Nigeriano
CL	9	RUN Chileno
EC	10	NI Equatoriano
GT	12	CUI Guatemalteco
UY	13	CI Uruguaia
ZZ	15	Endereço de e-mail
ZZ	17	Número de telefone
MX	25	RFC Mexicano (Pessoa Física)
CO	26	NIT Colombiano
PE	27	RUC Peruano
CA	28	SIN Canadense
DK	29	CPR Dinamarquês
GB	30	Número de Seguro Nacional Britânico (NINO)
PL	31	PESEL Polonês
SE	32	Número Pessoal Sueco (PNR)
AT	34	Número de Contribuinte Austríaco (STNR)
FI	35	Código de Identidade Pessoal Finlandês (HETU)
—	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

Exemplo

Integração — cURL
Integração — Node.js
Transacional — cURL
Transacional — Node.js

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

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();

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

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();

Respostas

Integração
Transacional

200 OK

{
  "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
`id`	string (UUID)	Identificador do processo. Use com Obter Processo para reconsultas.
`status`	integer	`1` (processando), `3` (finalizado com sucesso), `5` (erro).
`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`, `NOT_FOUND` — veja Identificador Facial.
`idFace.personId`	string	Identificador opaco estável para o rosto. Presente apenas quando `idFace.result = FOUND`.
`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.

200 OK

{
  "id": "80371b2a-3ac7-432e-866d-57fe37896ac6",
  "status": 3,
  "biometryToken": {
    "result": true
  },
  "liveness": 1
}

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

400 Bad Request

O payload está malformado, a imagem é inválida ou campos obrigatórios estão ausentes. Veja Códigos de Erro abaixo.

403 Forbidden

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

409 Conflict

O processId fornecido já existe para este tenant. Veja Códigos de Erro abaixo.

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.

Códigos de Erro

400 Bad Request
403 Forbidden
409 Conflict
500 Internal Server Error

Código	Mensagem	Descrição
`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.
`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.
`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.

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.

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

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 operações de Documento e Verificação de Idade, veja as respectivas páginas nesta seção.

Endpoint​

Requisição​

Exemplo​

Respostas​

Códigos de Erro​

Próximos passos​