Criar Processo

Este endpoint contempla dois casos de uso que compartilham o mesmo caminho, mas diferem nos parâmetros do corpo, nas capacidades e nos campos de resposta:

Onboarding — valida quem é o usuário comparando o rosto dele com a base de identidade da Unico (campo subject.code obrigatório).
Transactional — verifica se é a mesma pessoa de um processo anterior comparando rosto a rosto (campo referenceProcessId OU array references com selfie / process id obrigatório).

O caso de uso ativo é determinado pela APIKEY enviada no cabeçalho da requisição.

Para o fluxo completo de integração, consulte a 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>` (consulte Autenticação)
`APIKEY`	Chave de API provisionada — define o caso de uso ativo e as capacidades habilitadas.
`Content-Type`	`application/json`

Parâmetros do body

Onboarding
Transactional

Campo	Tipo	Obrigatório	Descrição
`subject.code`	string	sim	CPF (BR) ou CURP (MX).
`subject.name`	string	sim	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 no formato E.164.
`useCase`	string	não	Contexto da operação, ex.: `Onboarding`.
`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 do processo).
`referenceProcessId`	string	condicional	Obsoleto. Use `references` em vez disso. ID do processo de Onboarding de referência para comparação. Se o processo de referência for do tipo by-Unico, utilize `authenticationInfo.authenticationId`.
`imageBase64`	string	sim	Selfie capturada pelo seu front-end, em base64.
`subject`	object	não	Contêiner de informações do usuário.
`subject.code`	string	não	CPF (BR) ou CURP (MX).
`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 no formato E.164.
`useCase`	string	não	Contexto da operação, ex.: `Transactional`.
`subsidiaryId`	string	não	ID da filial — obrigatório somente se houver múltiplas filiais.

informação

Para este caso de uso, não é possível orquestrar com Classificação de risco de fraude. O resultado é sempre retornado de forma síncrona na resposta do POST.

Requisitos da imagem

Resolução mínima: 640 × 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 só podem ser usados uma vez

Exemplo

Onboarding — cURL
Onboarding — Node.js
Transactional — cURL
Transactional — 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": {
      "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: {
      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 '{
    "referenceProcessId": "80371b2a-3ac7-432e-866d-57fe37896ac6",
    "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({
    referenceProcessId: referenceProcessId,
    useCase: 'Transactional',
    imageBase64: capturedImage
  })
});

const result = await res.json();

Respostas

Onboarding
Transacional

200 OK

{
  "id": "80371b2a-3ac7-432e-866d-57fe37896ac6",
  "status": 3,
  "unicoId": { "result": "yes" },
  "identityFraudsters": { "result": "inconclusive" },
  "government": { "serpro": 87 },
  "liveness": 1
}

Campo	Tipo	Descrição
`id`	string (UUID)	Identificador do processo. Utilize com Obter Processo para re-consultas.
`status`	integer	`1` (processando), `3` (finalizado com sucesso), `5` (erro). Para todos os valores possíveis, consulte Obter Processo.
`unicoId.result`	string	`yes`, `no`, `inconclusive` — consulte Verificação de Identidade.
`identityFraudsters.result`	string	`yes`, `inconclusive` — consulte Classificação de risco de fraude.
`government.serpro`	integer	Pontuação de similaridade Serpro (0–100, -1, -2). Consulte Retorno de Semelhança do Serpro.
`liveness`	integer	`1` (aprovado), `2` (reprovado) — consulte Prova de Vida.

informação

Quando unicoId.result = inconclusive e a orquestração com Classificação de risco de fraude está ativa, o processo pode retornar status: 1 (processando). Faça polling em Obter Processo ou utilize webhooks para obter 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, consulte 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) — consulte Prova de Vida.

400 Bad Request

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

403 Forbidden

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

409 Conflict

O processId informado já existe para este tenant. Consulte Códigos de Erro abaixo.

429 Too Many Requests

Limite de taxa atingido. Tente novamente após o intervalo indicado no cabeçalho de resposta Retry-After. Consulte Rate limits.

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. Possíveis causas: 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.	O 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 do 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 informado e `references` não foi enviado como alternativa.
`20021`	The subject.phone field is invalid.	Formato de `subject.phone` inválido (DDI + DDD + número, 13 caracteres).
`20019`	The subject.birthDate field is invalid.	`subject.birthDate` fora do formato ISO 8601 (`YYYY-MM-DD`).
`20009`	O parâmetro imagebase64 não foi informado.	O parâmetro de imagem de 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 cabeçalho da requisição.
`20001`	O parâmetro authtoken não foi informado.	O parâmetro de token de integração está ausente no cabeçalho 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 realizar 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` informado já existe para este tenant.

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

Próximos passos

Para consultar o resultado de um processo de Onboarding, consulte Obter Processo.
Para operações de Verificação de Documentos e Verificação de Idade, consulte as respectivas páginas nesta seção.

Endpoint​

Requisição​

Exemplo​

Respostas​

Códigos de Erro​

Próximos passos​