Verificação de Idade

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

Parâmetros do corpo

Campo	Tipo	Obrigatório	Descrição
subject	object	sim	Container 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 (veja 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 x 480 (padrão HD)
• Tamanho máximo do arquivo: 800 KB (compressão JPEG92 recomendada)
• Tokens JWT do SDK expiram após 10 minutos e podem ser usados apenas 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 de resposta retornados 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 Obter 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, veja Obter 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 apenas quando a Verificação de Identidade está habilitada.
liveness	integer	1 (aprovado), 2 (reprovado) — presente apenas 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. 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.

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 de 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 de identificador malformado ou inexistente. Só é disparado 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.	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.	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. Só é disparado 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.	JWT excedeu a janela 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 executar 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, veja Obter Processo.