--- title: Criar Processo description: Crie um processo de verificação enviando a imagem capturada diretamente. Retorna um resultado síncrono. canonical: https://developer.unico.io/pt-BR/dual-api/developers/api-reference/api/post-processes 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/) - Create Process **Nesta página# Criar Processo Este endpoint lida com três produtos 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). **Cardholder Verification** — confirma que um cartão pertence ao seu titular declarado, sem nenhuma captura de selfie (`subject.code` + `card` obrigatórios). Opcionalmente reutiliza um processo previamente validado via `referenceProcessId` para disparar o gate de reutilização; sem ele, a resposta assume por padrão o resultado `unsure`. Veja a capacidade [Cardholder Verification](/pt-BR/capabilities/cardholder-verification). O produto ativo é determinado pela **APIKEY** enviada no header da requisição. 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 — define o produto ativo e as capacidades habilitadas.`Content-Type``application/json` Parâmetros do corpo IntegraçãoTransacionalCardholder VerificationCampoTipoObrigatórioDescrição`subject.duiType`integersimIdentificador do tipo de documento. Veja os [valores de `duiType`](#duitype-values) abaixo.`subject.code`stringsimValor do identificador definido por `subject.duiType`. Sem pontos ou traços.`subject.name`stringnãoNome completo.`subject.gender`stringnão`M` ou `F`.`subject.birthDate`string (ISO 8601)nãoData de nascimento (`YYYY-MM-DD`).`subject.email`stringnãoEndereço de e-mail.`subject.phone`stringnãoNúmero de telefone E.164.`subject.clientReference`stringcondicionalIdentificador único do usuário no seu sistema. **Obrigatório para a capacidade [Multi Contas](/pt-BR/capabilities/multi-accounts).** Único na sua base, máximo de 256 caracteres, sem espaços.`useCase`stringnãoContexto da operação, ex.: `Onboarding`.`subsidiaryId`stringnãoID da filial — obrigatório apenas se houver múltiplas filiais.`imageBase64`stringsimSelfie capturada pelo seu front-end, em base64.CampoTipoObrigatórioDescrição`references`arraycondicionalEntradas 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`stringcondicional**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`stringsimSelfie capturada pelo seu front-end, em base64.`subject`objectnãoContainer de informações do usuário.`subject.duiType`stringnãoTipo de identificador. Valores possíveis: `DUI_TYPE_AR_DNI`, `DUI_TYPE_BR_CPF`, `DUI_TYPE_ID_NIK`, `DUI_TYPE_MX_CURP`, `DUI_TYPE_NG_NIN`, `DUI_TYPE_US_SSN`.`subject.code`stringnãoValor do identificador definido por `subject.duiType`. Sem pontos ou traços.`subject.name`stringnãoNome completo do usuário.`subject.gender`stringnão`M` ou `F`.`subject.birthDate`string (ISO 8601)nãoData de nascimento (`YYYY-MM-DD`).`subject.email`stringnãoEndereço de e-mail.`subject.phone`stringnãoNúmero de telefone E.164.`useCase`stringnãoContexto da operação, ex.: `Transactional`.`subsidiaryId`stringnãoID da filial — obrigatório apenas se existirem múltiplas filiais.informaçãoPara este produto, não é possível orquestrar com Score de Risco. O resultado é sempre retornado de forma síncrona na resposta do POST.CampoTipoObrigatórioDescrição`subject.duiType`integersimIdentificador do tipo de documento. Veja os [valores de `duiType`](#duitype-values) abaixo. Atualmente apenas `DUI_TYPE_BR_CPF`.`subject.code`stringsimCPF do titular do cartão sendo verificado. Sem pontos ou traços.`card.bin`stringcondicionalPrimeiros 6 ou 8 dígitos do cartão (BIN). Obrigatório em conjunto com `card.last4`.`card.last4`stringcondicionalÚltimos 4 dígitos do cartão. Obrigatório em conjunto com `card.bin`.`card.name`stringnãoNome do titular do cartão, como impresso no cartão.`referenceProcessId`string (UUID)nãoID de um processo previamente validado a ser reutilizado — um com resultado aprovado de Verificação de Identidade ou Prova de Vida para o mesmo CPF. A versão atual desta capacidade é baseada em reutilização: sem esse campo, o gate nunca é disparado e a resposta assume por padrão o resultado `unsure` — a própria requisição nunca falha.`useCase`stringnãoContexto da operação, ex.: `CardholderVerification`.`subsidiaryId`stringnãoID da filial — obrigatório apenas se houver múltiplas filiais.informaçãoNenhum `imageBase64` é enviado para este produto — o Cardholder Verification é executado inteiramente no back-end, sem etapa de captura de selfie. **Valores de `duiType`**PaísCódigoDescriçãoAR6Passaporte ArgentinoAR7DNI ArgentinoAR49Carteira de motorista Argentina (Licencia Nacional de Conducir)AT34Número de Contribuinte Austríaco (STNR)BE36Número Nacional Belga (NN)BR1CPF BrasileiroBR5Passaporte BrasileiroBR14CNPJ BrasileiroCA28SIN CanadenseCH33Número AHV/AVS SuíçoCL9RUN ChilenoCL52Passaporte ChilenoCL57Carteira de motorista Chilena (Licencia de Conducir)CO26NIT ColombianoCO53Passaporte ColombianoCO55Carteira de motorista Colombiana (Licencia de Conducción)CO56Cédula de Cidadania Colombiana (Cédula de Ciudadanía)DE41Número de Identificação Fiscal Alemão (IdNr)DK29CPR DinamarquêsEC10NI EquatorianoES50Número de Identidade de Estrangeiro Espanhol (NIE)ES51Documento Nacional de Identidade Espanhol (DNI)FI35Código de Identidade Pessoal Finlandês (HETU)FR46Número de Referência Fiscal Francês (SPI)GB30Número de Seguro Nacional Britânico (NINO)GT12CUI GuatemaltecoID16NIK IndonésioIE47Número de Serviço Público Pessoal Irlandês (PPSN)IT37Codice Fiscale Italiano (CF)LU48Número de Identificação Nacional de Luxemburgo (Matricule)MX2CURP MexicanoMX25RFC Mexicano (Pessoa Física)MX58Carteira de motorista Mexicana (Licencia de Conducir)NG8NIN NigerianoNG20Número de Verificação Bancária Nigeriano (BVN)NG43Token de BVN Nigeriano (hash)NG44Token de NIN Nigeriano (hash)NL42Número de Serviço ao Cidadão Holandês (BSN)NO39Número de Identidade Nacional Norueguês (Fødselsnummer)PE27RUC PeruanoPE40DNI PeruanoPE54Passaporte PeruanoPL31PESEL PolonêsPT45Número de Identificação Fiscal Português (NIF)SE32Número Pessoal Sueco (PNR)SE38Número de Coordenação Sueco (Samordningsnummer)TR24Número de Identificação Turco (TCKN)US4SSN dos Estados UnidosUS11Passaporte dos Estados UnidosUS18Carteira de motorista dos Estados UnidosUS21Cartão de Passaporte dos Estados UnidosUS22Passaporte de Policarbonato dos Estados UnidosUS23Carteira de Identidade dos Estados UnidosUY13CI UruguaiaZZ15Endereço de e-mailZZ17Número de telefone—0Não especificado—3Identificador 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** Requisições comprimidas A API suporta o envio do corpo da requisição comprimido, usando o header HTTP padrão `Content-Encoding`. Isso é opcional e totalmente compatível com versões anteriores: clientes que não enviam esse header continuam funcionando exatamente como antes. Formatos suportados CodificaçãoHeader `Content-Encoding`StatusGzip`gzip`✅ RecomendadoDeflate`deflate`✅ SuportadoSem compressão(header ausente)✅ Suportado (comportamento padrão) RecomendaçãoUse `gzip`. É o que tem o suporte mais universal entre linguagens e bibliotecas HTTP, evitando as ambiguidades de implementação presentes em outros formatos. A compressão é recomendada para requisições com corpo grande (ex.: payloads JSON extensos, envios de imagens codificadas em base64, submissões em lote). Para requisições pequenas, o overhead de comprimir pode não trazer um benefício relevante. Como enviar uma requisição comprimida Comprima o corpo da requisição (ex.: o JSON serializado) usando o algoritmo escolhido. Envie o corpo comprimido como bytes binários na requisição. Inclua o header `Content-Encoding` com o valor correspondente (`gzip` ou `deflate`). Mantenha o `Content-Type` descrevendo o formato original do conteúdo (ex.: `application/json`), e não a codificação de transporte. cURLPython (requests).NET (C#, HttpClient)``` echo '{"subject":{"code":"12345678909"},"useCase":"Onboarding","imageBase64":"/9j/4AAQSkZJR..."}' | gzip > body.json.gzcurl -X POST https://api.id.unico.app/processes/v1 \ -H "Authorization: Bearer $TOKEN" \ -H "APIKEY: $API_KEY" \ -H "Content-Type: application/json" \ -H "Content-Encoding: gzip" \ --data-binary @body.json.gz ``` ``` import gzipimport jsonimport requestspayload = { "subject": {"code": "12345678909"}, "useCase": "Onboarding", "imageBase64": capturedImage,}compressed_body = gzip.compress(json.dumps(payload).encode("utf-8"))response = requests.post( "https://api.id.unico.app/processes/v1", data=compressed_body, headers={ "Authorization": f"Bearer {token}", "APIKEY": api_key, "Content-Type": "application/json", "Content-Encoding": "gzip", },) ``` ``` using System.IO.Compression;using System.Text;using System.Text.Json;var json = JsonSerializer.Serialize(payload);var jsonBytes = Encoding.UTF8.GetBytes(json);using var outputStream = new MemoryStream();using (var gzipStream = new GZipStream(outputStream, CompressionMode.Compress, leaveOpen: true)){ await gzipStream.WriteAsync(jsonBytes, 0, jsonBytes.Length);}outputStream.Position = 0;var content = new ByteArrayContent(outputStream.ToArray());content.Headers.ContentType = new MediaTypeHeaderValue("application/json");content.Headers.ContentEncoding.Add("gzip");using var client = new HttpClient();client.DefaultRequestHeaders.Add("Authorization", $"Bearer {token}");client.DefaultRequestHeaders.Add("APIKEY", apiKey);var response = await client.PostAsync("https://api.id.unico.app/processes/v1", content); ``` dicaPara o exemplo em Python, use o parâmetro `data=`, não `json=`. O parâmetro `json=` serializa o payload automaticamente, mas não o comprime. **Usando `deflate` em vez disso:** o fluxo acima é idêntico — apenas a chamada de compressão e o valor de `Content-Encoding` mudam. Idioma`deflate`Bash / cURL`zlib-flate -compress < body.json > body.json.deflate` (do `qpdf`), depois `-H "Content-Encoding: deflate"`Python`zlib.compress(data)` em vez de `gzip.compress(data)`.NET (C#)`System.IO.Compression.DeflateStream` em vez de `GZipStream` `deflate` é ambíguo na práticaA codificação de conteúdo `deflate` do HTTP é especificada como um stream zlib (RFC 1950), mas alguns clientes e servidores historicamente emitem ou esperam DEFLATE bruto (RFC 1951) em vez disso. Esta API espera o stream padrão envolto em zlib — a mesma saída que `zlib.compress()` (Python) ou `DeflateStream` (.NET) produzem por padrão. Em caso de dúvida, prefira `gzip`, que não tem essa ambiguidade. Comportamento em caso de erroSe `Content-Encoding` for enviado com um valor não suportado, ou se o corpo estiver corrompido ou inválido para a codificação declarada, a API retorna `400 Bad Request` com uma mensagem indicando que a descompressão do corpo da requisição falhou. FAQ **Preciso alterar algo se eu não quiser usar compressão?** Não. O suporte a `Content-Encoding` é aditivo — requisições sem esse header continuam sendo processadas normalmente. **Isso afeta a resposta da API?** Não. Esse recurso diz respeito apenas ao corpo enviado pelo cliente (requisição). A compressão da resposta (o que a API retorna) é controlada separadamente pelo header `Accept-Encoding`. **Qual formato eu devo escolher?** Use `gzip`, a menos que alguma restrição específica do seu ambiente exija outro formato. ### Exemplo​ Integração — cURLIntegração — Node.jsTransacional — cURLTransacional — Node.jsCardholder Verification — cURLCardholder Verification — 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": "luke@example.com", "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: 'luke@example.com', 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(); ``` ``` 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" }, "card": { "bin": "12345678", "last4": "4321", "name": "Luke Skywalker" }, "referenceProcessId": "4f00b35f-69d4-415a-a843-d975cefcb169", "useCase": "CardholderVerification" }' ``` ``` 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' }, card: { bin: '12345678', last4: '4321', name: 'Luke Skywalker' }, referenceProcessId: '4f00b35f-69d4-415a-a843-d975cefcb169', useCase: 'CardholderVerification' })});const result = await res.json(); ``` ### Respostas​ IntegraçãoTransacionalCardholder Verification200 OKO contrato é único — o campo `idCloud.result` carrega o veredito consolidado das capacidades utilizadas.A Unico consolida os resultados das capacidades executadas em um único `idCloud.result`, pronto para decidir o próximo passo do seu fluxo — sem necessidade de orquestrar resultados individuais.``` { "id": "80371b2a-3ac7-432e-866d-57fe37896ac6", "status": 3, "idCloud": { "result": "approved" }} ``` 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`1` (processando), `3` (finalizado com sucesso), `5` (erro).Valores possíveis de resultadoidCloud.resultSignificadoAção recomendadaapprovedPessoa real e identidade validada.Prossiga com o fluxo.deniedIdentidade não validada, falha na prova de vida, ou risco extremo identificado.Encerre o fluxo ou redirecione para um fluxo alternativo.critical-riskNível de risco crítico identificado.Encerre o fluxo ou encaminhe para revisão manual.high-riskNível de risco alto identificado.Encaminhe para revisão manual ou para um fluxo alternativo.retryCaptura ou score insuficiente para avaliação.Solicite uma nova captura ao usuário.inconclusiveEvidências insuficientes para um veredito.Encaminhe para revisão manual ou para um fluxo alternativo.Os valores retornados dependem da receita configurada na sua APIKey. Veja [Fluxos](/pt-BR/dual-api/developers/api-reference/api/flows) os valores de resultado que cada receita pode retornar.Clientes no Brasil podem receber a resposta por capacidadeA estrutura geral da resposta permanece a mesma — o resultado único é o padrão.Integrações no Brasil podem receber os resultados abertos, por capacidade. Cada capacidade habilitada na APIKey adiciona seu próprio bloco à resposta — campos de capacidades desabilitadas são omitidos.``` { "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 APIKeyO 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.CampoTipoDescrição`unicoId.result`string`yes`, `no`, `inconclusive` — veja [Verificação de Identidade](/pt-BR/capabilities/identity-verification).`riskLevel.result`string`approved`, `reproved`, `risk-critical`, `risk-high`, `inconclusive` — veja os [valores possíveis](#risklevel-values) abaixo ou a [Classificação de Risco de Fraude](/pt-BR/capabilities/fraud-risk-classification).`idFace.result`string`FOUND` — veja Identificador Facial.`idFace.personId`stringIdentificador opaco estável para o rosto, retornado junto com `idFace.result = FOUND`. Quando nenhum rosto pode ser identificado na imagem, a requisição falha com o erro [`20532`](#error-codes) em vez de retornar um bloco `idFace`.`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`integerScore de similaridade Serpro (0–100, -1, -2). Disponível apenas no Brasil. Veja [Retorno de Semelhança do Serpro](/pt-BR/capabilities/serpro-similarity-return).`liveness`integer`1` (aprovado), `2` (reprovado) — veja [Prova de Vida](/pt-BR/capabilities/liveness).riskLevel.result — valores possíveisValorSignificado`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çãoQuando `unicoId.result = inconclusive` e a orquestração de Score de Risco está ativa, o processo pode retornar `status: 1` (processando). Consulte [Obter Processo](/pt-BR/dual-api/developers/api-reference/api/get-process) ou use webhooks para recuperar o resultado final.Clientes no México podem receber o bloco de Verificação RENAPOA resposta mantém a mesma estrutura e acrescenta o bloco idGov.Integrações no México com a Verificação RENAPO habilitada recebem um bloco idGov adicional com o registro que o RENAPO mantém para a CURP do usuário. É uma resposta separada do resultado de identidade.``` { "id": "11111111-2222-3333-4444-555555555555", "status": 3, "idCloud": { "result": "approved" }, "idGov": { "government_valid": true, "curp": "PUEA880304MDFRJN04", "government_name": "ANA PRUEBA EJEMPLO", "date_of_birth": "1988-03-04", "age": 38, "gender": "F", "deceased": false, "is_mexican": true, "citizenship": "MEXICO", "state_of_birth": "Ciudad de México", "state_iso": "MX-CMX", "issuing_entity_code": "DF", "municipality_registration": "" }} ``` CampoTipoDescrição`idGov`objectRegistro do RENAPO para a CURP. Ausente quando a capability não está habilitada. `{}` quando o RENAPO não respondeu. Apenas México. Veja [Verificação RENAPO](/pt-BR/capabilities/renapo-verification).200 OKO contrato é único — o campo `idCloud.result` carrega o veredito consolidado das capacidades utilizadas.A Unico consolida os resultados das capacidades executadas em um único `idCloud.result`, pronto para decidir o próximo passo do seu fluxo — sem necessidade de orquestrar resultados individuais.``` { "id": "80371b2a-3ac7-432e-866d-57fe37896ac6", "status": 3, "idCloud": { "result": "approved" }} ``` CampoTipoDescrição`id`string (UUID)Identificador do processo.`status`integer`3` (finalizado com sucesso), `5` (erro). Para todos os valores possíveis, veja [Obter Processo](/pt-BR/dual-api/developers/api-reference/api/get-process).Valores possíveis de resultadoidCloud.resultSignificadoAção recomendadaapprovedPessoa real e identidade validada.Prossiga com o fluxo.deniedIdentidade não validada, falha na prova de vida, ou risco extremo identificado.Encerre o fluxo ou redirecione para um fluxo alternativo.critical-riskNível de risco crítico identificado.Encerre o fluxo ou encaminhe para revisão manual.high-riskNível de risco alto identificado.Encaminhe para revisão manual ou para um fluxo alternativo.retryCaptura ou score insuficiente para avaliação.Solicite uma nova captura ao usuário.inconclusiveEvidências insuficientes para um veredito.Encaminhe para revisão manual ou para um fluxo alternativo.Os valores retornados dependem da receita configurada na sua APIKey. Veja [Fluxos](/pt-BR/dual-api/developers/api-reference/api/flows) os valores de resultado que cada receita pode retornar.Clientes no Brasil podem receber a resposta por capacidadeA estrutura geral da resposta permanece a mesma — o resultado único é o padrão.Integrações no Brasil podem receber os resultados abertos, por capacidade. Cada capacidade habilitada na APIKey adiciona seu próprio bloco à resposta — campos de capacidades desabilitadas são omitidos.``` { "id": "80371b2a-3ac7-432e-866d-57fe37896ac6", "status": 3, "biometryToken": { "result": true }, "liveness": 1} ``` CampoTipoDescrição`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](/pt-BR/capabilities/liveness).200 OK``` { "id": "80371b2a-3ac7-432e-866d-57fe37896ac6", "status": 3, "cardholderVerification": { "result": "approved" }} ``` CampoTipoDescrição`id`string (UUID)Identificador do processo.`status`integer`1` (processando), `3` (finalizado com sucesso), `5` (erro). Para todos os valores, veja [Obter Processo](/pt-BR/dual-api/developers/api-reference/api/get-process).`cardholderVerification.result`string`approved` — o CPF e o cartão pertencem à mesma pessoa. `unsure` — o gate de reutilização não foi satisfeito, ou a verificação em si foi inconclusiva. Ausente enquanto `status` ainda não é `3`. Veja [Cardholder Verification](/pt-BR/capabilities/cardholder-verification). ### Códigos de Erro​ 400 Bad Request403 Forbidden409 Conflict429 Too Many Requests500 Internal Server ErrorCódigoMensagemDescrição`40221`This flow does not support reusing a prior process (referenceProcessId or bioTokenId) without an image; send an image (imageBase64, or references[0] with type IMAGE_BASE64) instead.O fluxo de reutilização (`referenceProcessId`/`bioTokenId`, sem imagem) foi rejeitado porque a reutilização de processo não está habilitada para esta API key.`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.`20532`No face detected in image.Nenhum rosto foi detectado na imagem enviada.`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. Não se aplica ao Cardholder Verification — o `referenceProcessId` desse produto nunca é validado como obrigatório; um gate de reutilização não satisfeito responde `unsure` em vez disso.`20533`The card field is missing.[Cardholder Verification](/pt-BR/capabilities/cardholder-verification): o objeto `card` não foi fornecido.`20534`The card.bin field is missing.[Cardholder Verification](/pt-BR/capabilities/cardholder-verification): `card.bin` não foi fornecido.`20535`The card.last4 field is missing.[Cardholder Verification](/pt-BR/capabilities/cardholder-verification): `card.last4` não foi fornecido.`20536`The card data is invalid.[Cardholder Verification](/pt-BR/capabilities/cardholder-verification): os dados do cartão foram rejeitados como inválidos.`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.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.`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ó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 laterQuando há um erro interno. ### Próximos passos​ Para consultar o resultado de um processo de Integração, veja [Obter Processo](/pt-BR/dual-api/developers/api-reference/api/get-process). Para ver todas as combinações de receitas e seus valores de resultado possíveis, veja [Fluxos](/pt-BR/dual-api/developers/api-reference/api/flows). Para operações de Documento e Verificação de Idade, veja as respectivas páginas nesta seção. Última atualização em 8 de out. de 2026**