Verificação de Idade

Para o fluxo completo de integração, consulte 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 — deve ter as capacidades de Verificação de Idade habilitadas.
Content-Type	application/json

Parâmetros do body

Campo	Tipo	Obrigatório	Descrição
subject	object	sim	Contêiner de informações do usuário.
subject.code	string	condicional	CPF (BR) ou CURP (MX), sem formatação. Obrigatório quando o fluxo inclui Prova de Vida ou Verificação de Identidade (consulte capacidade de Verificação de Idade); não obrigatório para fluxos somente de Verificação de Idade.
subject.name	string	não	Nome completo do usuário.
subject.gender	string	não	M para masculino ou F para feminino.
subject.birthDate	string (ISO 8601)	não	Data de nascimento (YYYY-MM-DD).
subject.email	string	não	Endereço de e-mail do usuário.
subject.phone	string	não	Número de telefone: código do país + código de área + número, sem separadores (ex.: 5519725570707).
useCase	string	não	Identificador do caso de uso da operação.
subsidiaryId	string	não	ID da filial — obrigatório apenas se existirem múltiplas filiais.
imageBase64	string	sim	Saída criptografada do SDK ou imagem em base64 (PNG, JPEG, WebP).

Requisitos de imagem

• Resolução mínima: 640 × 480 (padrão HD)
• Tamanho máximo do arquivo: 800 KB (compressão JPEG92 recomendada)
• Tokens JWT gerados pelo SDK expiram após 10 minutos e só podem ser usados uma vez

Exemplo

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": {
      "code": "12345678909",
      "name": "Luke Skywalker",
      "birthDate": "2000-05-20",
      "email": "[email protected]",
      "phone": "5519725570707"
    },
    "useCase": "AgeVerification",
    "imageBase64": "/9j/4AAQSkZJR..."
  }'

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: {
      code: '12345678909',
      name: 'Luke Skywalker',
      birthDate: '2000-05-20',
      email: '[email protected]',
      phone: '5519725570707'
    },
    useCase: 'AgeVerification',
    imageBase64: capturedImage
  })
});

const result = await res.json();

Respostas

200 OK

Os campos retornados na resposta dependem de quais capacidades estão habilitadas para sua APIKEY.

Somente Verificação de Idade (sem Prova de Vida, sem Verificação de Identidade):

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

Verificação de Idade + Prova de Vida + Verificação de Identidade:

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

Campo	Tipo	Descrição
id	string (UUID)	Identificador do processo. Use com Consultar Processo para reconsultas.
status	integer	3 (finalizado com sucesso), 5 (erro). Use apenas status = 3 para decisões de negócio. Para todos os valores possíveis, consulte Consultar Processo.
idAge.result	string	yes, no, inconclusive — resultado da Verificação de Idade. Presente em todas as respostas.
unicoId.result	string	yes, no, inconclusive — presente somente quando a Verificação de Identidade está habilitada.
liveness	integer	1 (aprovado), 2 (reprovado) — presente somente quando a Prova de Vida está habilitada.

400 Bad Request

O payload está malformado, a imagem é inválida ou campos obrigatórios estão ausentes.

403 Forbidden

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

409 Conflict

O processId fornecido 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 header de resposta Retry-After. Consulte Limites de taxa.

500 Internal Server Error

Erro inesperado no servidor.

Códigos de Erro

400 Bad Request

Código	Mensagem	Descrição
20900	O base64 informado não é válido.	Parâmetro base64 inválido; possível problema com a imagem ou injeção.
20807	A imagem precisa estar no padrão HD ou possuir uma resolução superior a 640 x 480.	Resolução da imagem abaixo do limite mínimo.
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.	Valor do identificador malformado ou inexistente. Disparado apenas quando Prova de Vida ou Verificação de Identidade está incluída no fluxo — não obrigatório para fluxos somente de Verificação de Idade.
20506	O base64 informado é muito grande. O tamanho máximo suportado é até 800kb.	Payload excede 800 KB; comprima para JPEG92.
20505	O base64 informado não é suportado. Os formatos aceitos são png, jpeg e webp.	Formato não suportado ou prefixo base64 inválido.
20062	The useCase field is invalid.	Valor não reconhecido no campo useCase.
20021	The subject.phone field is invalid.	O formato de subject.phone é inválido (DDI + DDD + 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.	Parâmetro de imagem selfie ausente.
20008	The subject.email field is invalid.	Formato de e-mail inválido em subject.email.
20005	O parâmetro subject.code não foi informado.	Parâmetro subject.code ausente. Disparado apenas quando Prova de Vida ou Verificação de Identidade está incluída no fluxo — não obrigatório para fluxos somente de Verificação de Idade.
20004	O parâmetro subject não foi informado.	Objeto subject ausente.
20003	The request body is missing or invalid.	Payload nulo ou malformado.
20002	O parâmetro APIKey não foi informado.	Header APIKEY ausente.
20001	O parâmetro authtoken não foi informado.	Header de token de autenticação ausente.
10508	The JWT with the captured face has already been used.	O JWT só pode ser consumido uma vez.
10507	The JWT with the captured face is expired.	O JWT excedeu o prazo de validade 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

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.
30017	Jwt header is an invalid JSON.	O access-token contém caracteres inválidos.
10502	O token informado está expirado.	Access-token expirado.
10501	O token informado é inválido.	Token de autenticação inválido.
10201	O AppKey informado é inválido.	APIKEY ausente ou inexistente.

409 Conflict

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

500 Internal Server Error

Código	Mensagem	Descrição
99999	Internal failure! Try again later.	Erro de processamento no servidor.

Próximos passos

• Para consultar um processo existente, consulte Consultar Processo.