--- title: Verificação de Idade description: Crie um processo de Verificação de Idade. Opcionalmente combina detecção de prova de vida e verificação de identidade em uma única requisição. canonical: https://developer.unico.io/pt-BR/dual-api/developers/api-reference/api/post-processes-age-validation locale: pt-BR generated_by: markdown-export --- - [/pt-BR/](/pt-BR/) - [Referência de API](/pt-BR/dual-api/developers/api-reference/) - [API](/pt-BR/dual-api/developers/api-reference/api/) - Verificação de Idade **Nesta página# Verificação de Idade Para o fluxo completo de integração, veja [Visão Geral da API](/pt-BR/dual-api/developers/api-reference/api/). ### Endpoint​ AmbienteURL**Produção**`POST https://api.id.unico.app/processes/v1`**Sandbox**`POST https://api.id.uat.unico.app/processes/v1` ### Requisição​ Headers HeaderValor`Authorization``Bearer ` (veja [Autenticação](/pt-BR/dual-api/developers/api-reference/authentication))`APIKEY`Chave de API provisionada — deve ter as capacidades de Verificação de Idade habilitadas.`Content-Type``application/json` Parâmetros do corpo CampoTipoObrigatórioDescrição`subject`objectsimContainer de informações do usuário.`subject.code`stringcondicionalCPF (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](/pt-BR/dual-api/capabilities/age-verification)); não obrigatório para fluxos somente de Verificação de Idade.`subject.name`stringnãoNome completo do usuário.`subject.gender`stringnão`M` para masculino ou `F` para feminino.`subject.birthDate`string (ISO 8601)nãoData de nascimento (`YYYY-MM-DD`).`subject.email`stringnãoEndereço de e-mail do usuário.`subject.phone`stringnãoNúmero de telefone: código do país + código de área + número, sem separadores (ex.: `5519725570707`).`useCase`stringnãoIdentificador do cenário da operação.`subsidiaryId`stringnãoID da filial — obrigatório apenas se existirem múltiplas filiais.`imageBase64`stringsimSaí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​ cURLNode.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", "birthDate": "2000-05-20", "email": "luke@example.com", "phone": "5519725570707" }, "useCase": "AgeVerification", "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', birthDate: '2000-05-20', email: 'luke@example.com', 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} ``` CampoTipoDescrição`id`string (UUID)Identificador do processo. Use com [Obter Processo](/pt-BR/dual-api/developers/api-reference/api/get-process) 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](/pt-BR/dual-api/developers/api-reference/api/get-process).`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. ### Códigos de Erro​ 400 Bad Request403 Forbidden409 Conflict429 Too Many Requests500 Internal Server ErrorCódigoMensagemDescriçã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.Bearer token ou `APIKEY` ausente, expirado ou inválido. Veja [Autenticação](/pt-BR/dual-api/developers/api-reference/authentication).CódigoMensagemDescriçã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.CódigoMensagemDescrição`20073`The processID already exists.O `processId` fornecido já existe para este tenant.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. avisoContinuar 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](/pt-BR/dual-api/developers/api-reference/rate-limits).CódigoMensagemDescrição`99999`Internal failure! Try again later.Erro de processamento no servidor. ### Próximos passos​ Para consultar um processo existente, veja [Obter Processo](/pt-BR/dual-api/developers/api-reference/api/get-process). Última atualização em 8 de out. de 2026**