1 de 15

Integração by Client

Nesta seção, você encontrará todas as especificações técnicas das APIs REST do IDCloud, utilizando o meio de integração by Client

Visão Geral

Nesta seção, você encontrará todas as especificações técnicas das APIs REST do by Client

Introdução

O by Client é um canal que oferece toda a liberdade para o cliente utilizar as soluções de validação de identidade da plataforma IDCloud.

Tem por objetivo, fornecer uma gama de possibilidades no uso das capacidades da plataforma IDCloud oferecendo uma solução que pode ser integrada ao seu back-end e liberdade para clientes que desejam controlar a experiência dos usuários com front-end próprio (passa isso leia sobre o ) ou através dos nossos .

Fluxos possíveis

O by Client é um meio de integração do Unico IDCloud que permite que os clientes se integrem da maneira que quiserem, combinando ou não as como julgarem necessário. Esse meio de integração fornece os recursos necessários para realizar validação da Prova de vida, Detecção de Perfil Fraudador, Verificação da Identidade, Captura e reaproveitamento de documentos.

Você pode combinar as capacidades como quiser e nos casos de uso mais distintos, mas para isso você deverá ter API Keys configuradas com as capacidades que deseja utilizar.

Para solicitar as capacidades na API Key, contate o responsável pelo seu projeto de integração ou o time de suporte da Unico para realizar essa configuração

Verifique abaixo todas as possíveis combinações de capacidade no by Client:

Também é possível utilizar as capacidades acima sem a Prova de vida, caso você já tenha um provedor de Prova de vida em sua operação;

Capacidades síncronas e assíncronas

No by Client possuímos capacidades onde a resposta é síncrona (ou seja, no momento de criar o processo já devolvemos a resposta) e outras capacidades assíncronas (onde processamos os dados e você necessariamente precisa "buscar" este resultado através de um método GET na API REST.

Em sua operação você poderá combinar as capacidades como bem quiser, porém cada capacidade terá sua comunicação, por exemplo:

Você pode ter uma operação que utilize as capacidades Verificação de Identidade + Detecção de Perfil Fraudador;
Ao criar o processo, a resposta da capacidade Verificação de Identidade será síncrona, no próprio response da API de criação de processo;
Já a capacidade de Detecção de Perfil Fraudador será executada de forma assíncrona, sendo necessário aguardar seu processamento e então realizar uma outra requisição GET para obter o resultado final do processo.

Abaixo veja as capacidades síncronas e assíncronas:

Capacidades síncronas

Prova de vida:

Verificação de Identidade:

Validação (1:1)

Capacidades assíncronas

Verificação de Identidade:

Assim como a capacidade Verificação de Identidade é um capacidade "síncrona", ela também pode ser configurada para uso "assíncrono".

Score de risco:

Detecção de Perfil Fraudador:

Captura e reaproveitamento de documentos:

Padrão de captura (sem SDK)

Nesta seção, você encontrará como deve ser o padrão de captura da selfie do usuário, caso não utilize nossas SDKs

Para uma melhor performance das capacidades da plataforma IDCloud, orientamos que utilize nossos SDKs. Eles irão garantir o melhor funcionamento do produto como um todo, tanto em relação ao drop quanto na validação da Prova de vida.

Para obter melhores resultados na captura de imagens um padrão de captura foi definido. A imagem deve ser nítida com iluminação frontal suficiente. O rosto deve estar reto, voltado para a camera, sem objetos ou obstruções e com expressão neutra.

Normalmente, as imagens capturadas apresentam os seguintes problemas:

Iluminação atrás do cliente - É necessário que a iluminação frontal seja boa o suficiente para uma captura nítida do rosto;
Iluminação estourada - A iluminação frontal precisa ser boa o suficiente para uma captura nítida do rosto;
Rosto muito próximo da captura + iluminação - O rosto precisa estar enquadrado no centro da câmera e a iluminação frontal precisa ser boa o suficiente;
Imagens embaçadas - O rosto da pessoa precisa estar bem focado no momento da captura;
Imagens tremidas - Estabilizar a câmera na hora da captura;
Cliente de óculos - O cliente precisa estar sem óculos ou objetos que possam impedir a visualização completa da face.

Como obter uma boa captura de imagem

Para obtenção e envio de imagens, o padrão ICAO é utilizado. O padrão ICAO (International Civil Aviation Organization) consiste em características para que uma fotografia esteja em conformidade com os seguinte requisitos e recomendações definidos para configurações de captura e envio das imagens:

Posicionamento da face e informações adicionais:
- A foto deve ser tirada de frente - olhar diretamente para a câmera e manter a cabeça ereta. O rosto deve estar centralizado. Os ombros devem estar alinhados, paralelos ao plano de imagem da câmera;
- Os olhos devem estar abertos naturalmente - pupilas e íris visíveis;
- Óculos - a foto deve ser capturada sem óculos;
- Sem chapéu, boné, ou máscara - a região da face deve ser claramente visível;
- Fisionomia Neutra - o rosto deve ter uma expressão neutra, a pessoa não deve sorrir, não levantar as sobrancelhas, não apertar os olhos ou franzir a testa;
- Penteado - O cabelo também não deve cobrir a zona de visibilidade dos olhos.
Iluminação e fundo: Fundo claro, liso e sem textura. Não deve conter manchas, linhas ou curvas que fiquem visíveis na imagem capturada. Cores claras como azul claro ou branco podem ser usadas desde que haja distinção suficiente entre a área do rosto/cabelo e o fundo. As configurações de cor da câmera não devem ser alteradas dependendo da cor de fundo. Atrás da imagem do rosto, não deve haver sombra. Também não deve haver objetos visíveis ao fundo, como pessoas, móveis, papéis de parede estampados, plantas. A iluminação precisa ser adequada e uniforme, distribuída igualmente na face para que não haja diferença entre o lado esquerdo e lado direito. A foto precisa ter brilho e bom contraste entre cabelo, rosto e fundo. Fotos com iluminação ruim são fotos quando a iluminação está somente na lateral, iluminação superior, ou iluminação inferior.
Imagens no formato JPEG, PNG ou JWT;
Imagens capturadas em cores.

Tamanhos / Proporções

Selfies:

Tamaho recomendado: Proporção 1920x1080 ou 1080x1920;
Orientação: Retrato;
Tamanho: No máximo 800kb, se necessário pode comprimir em Jpeg92.

Documentos:

Tamanho recomendado: Proporção HD - 1280x720 ou 720x1280;
Tamanho mínimo: Proporção VGA - 640x480 ou 480x640;
Orientação: Caso use tipificação/ocr é recomendado que seja capturado na orientação de leitura;
Tamanho: No máximo 800kb, se necessário pode comprimir em Jpeg92;
Enquadramento: É recomendado que na imagem não haja espaços sobrando (sem bordas). Quanto maior a área de folga (borda), é pior para a tipificação de documentos.

A foto deve ter:

Cor.
Enquadramento.
Foco nítido e claro, sem marcas de tinta ou vincos.

Olhar diretamente para a câmera.
Mostrar o tom de pele natural.
Ter brilho e contraste apropriados.

Fisionomia neutra e olhos abertos claramente visíveis
Sem cabelo sobre os olhos.
De frente para a câmera, sem olhar por cima do ombro ou inclinado, e mostrando as duas bordas do rosto claramente.
Com um fundo simples de cor clara, de preferência branco.
Com iluminação uniforme, sem sombras ou reflexos de flash no rosto e sem olhos vermelhos.
Sem lentes de contato coloridas.
Sem maquiagem.

O uso de óculos não é recomendado, mas nos casos de necessidade do uso de óculos:

Os olhos devem estar nítidos, sem o reflexo do flash ou da luz ambiente nos óculos e sem lentes coloridas.
A armação não deve cobrir nenhuma parte dos olhos.

Dicas

Adicionar orientações antes da captura para o usuário:

Utilize "frames" de captura para orientar o posicionamento do cliente frente ao rosto:

APIs

Nesta seção, você encontrará todas as APIs REST disponíveis para utilização do meio de integração by Client

CreateProcess

Nesta seção, você encontrará como criar um processo no by Client através da API REST

Antes de começar

Suas requisições de API são autenticadas utilizando um access-token. Qualquer requisição que não inclua um access-token válido retornará um erro.

Você pode ver mais sobre como gerar um access-token .

Endpoints:

UAT: ;
Produção: .

Os parâmetros acima são os da utilização mais comum da API, mas podem sofrer alterações a depender das capacidades que estiver utilizando. Confira nas subseções desta seção as possibilidades de capacidades e suas diferenças.

Responses de erro

A API by Client não recusa as fotos (ou seja, não há drop). Os retornos existentes são da capacidade Verificação de Identidade e sempre serão: yes, no ou inconclusive. Sendo assim, os casos de má qualidade na captura da imagem, prova de vida ou não titularidade, o retorno é inconclusive. O retorno é um yes quando é possível identificar uma pessoa ao vivo e que seja a real titular do CPF.

Prova de vida

Nesta seção, você encontrará as particularidades de criar um processo que tenha somente a Prova de vida como capacidade

Antes de começar

Suas requisições de API são autenticadas utilizando um access-token. Qualquer requisição que não inclua um access-token válido retornará um erro.

Você pode ver mais sobre como gerar um access-token aqui.

Endpoints:

UAT: https://api.id.uat.unico.app/processes/v1;
Produção: https://api.id.unico.app/processes/v1.

Note que para utilizar a Prova de vida de forma isolada:

Na criação do processo, somente o subject.code e imageBase64 são obrigatórios;
No response do processo, só devolvemos os parâmetros id, status e liveness (resultado da Prova de vida).

Para este caso de uso, não há a necessidade de realizar o GetProcess, visto que a resposta é síncrona.

Dúvidas?

Não encontrou algo ou ainda precisa de ajuda? Se já é um cliente ou parceiro, pode entrar em contato através da Central de Ajuda.

Verificação de Identidade

Nesta seção, você encontrará as particularidades de criar um processo que tenha a Verificação de Identidade como capacidade, bem como seus complementos

Antes de começar

Suas requisições de API são autenticadas utilizando um access-token. Qualquer requisição que não inclua um access-token válido retornará um erro.

Você pode ver mais sobre como gerar um access-token aqui.

Endpoints:

UAT: https://api.id.uat.unico.app/processes/v1;
Produção: https://api.id.unico.app/processes/v1.

Note que para a utilização da capacidade de Verificação de Identidade:

Na criação do processo, são obrigatórios subject.code, subject.name e imageBase64;
No response do processo, as respostas das capacidades podem vir em tempos diferentes, visto que o IDCloud possui Capacidades síncronas e assíncronas. Em função disso, deve-se implementar o método GetProcess a depender da combinação destas capacidades.

A capacidade de Verificação de Identidade pode ser combinada com outras capacidades, como Score de risco ou Detecção de Perfil Fraudador. Para encontrar mais informações das respostas possíveis, veja as seções Cenários de response e Especificação de Parâmetros.

Dúvidas?

Não encontrou algo ou ainda precisa de ajuda? Se já é um cliente ou parceiro, pode entrar em contato através da Central de Ajuda.

Validação (1:1)

Nesta seção, você encontrará as particularidades de criar um processo que tenha a Validação (1:1) como capacidade

Antes de começar

Suas requisições de API são autenticadas utilizando um access-token. Qualquer requisição que não inclua um access-token válido retornará um erro.

Você pode ver mais sobre como gerar um access-token aqui.

Endpoints:

UAT: https://api.id.uat.unico.app/processes/v1;
Produção: https://api.id.unico.app/processes/v1.

Note que para a utilização da capacidade de Validação (1:1):

Na criação do processo, são obrigatórios subject.code, referenteProcessId e imageBase64;
No response do processo, devolvemos o id, authenticated (resultado da Validação 1:1) e liveness (resultado da Prova de vida).

Para este caso de uso, não há a necessidade de realizar o GetProcess, visto que a resposta é síncrona.

O endpoint acima considera o uso da capacidade Validação (1:1) em conjunto com a capacidade Prova de vida.

Dúvidas?

Não encontrou algo ou ainda precisa de ajuda? Se já é um cliente ou parceiro, pode entrar em contato através da Central de Ajuda.

Captura de documentos

Nesta seção, você encontrará as particularidades de criar um processo que tenha a Captura de documentos como capacidade

Antes de começar

Suas requisições de API são autenticadas utilizando um access-token. Qualquer requisição que não inclua um access-token válido retornará um erro.

Você pode ver mais sobre como gerar um access-token .

Endpoints:

UAT: ;
Produção: .

Note que para a utilização da capacidade de Captura de documentos:

Na criação do processo, são obrigatórios subject.code, subject.name, document.Purpose, document.files.documentId ou document.files.data e imageBase64;
- O valor do parâmetro document.documenId só será informado na requisição caso tenha encontrado um ID de documento na API "GetReusableDocuments".
- Caso não tenha encontrado nenhum ID de documento na API "GetReusableDocuments", você deve enviar o base64 do documento capturado como um valor do parâmetro document.files.data

GetProcess

Nesta seção, você encontrará como obter o resultado de um processo no by Client através da API REST

Antes de começar

Suas requisições de API são autenticadas utilizando um access-token. Qualquer requisição que não inclua um access-token válido retornará um erro.

Você pode ver mais sobre como gerar um access-token aqui.

Endpoints:

UAT: https://api.id.uat.unico.app/processes/v1;
Produção: https://api.id.unico.app/processes/v1.

Para implementar suas regras de negócio, sempre valide os status finais dos processos (`3`,`4`,`5`). Para validar a reposta das capacidades IDCloud, só considere o `status` = `3` para sua tomada de decisão. Veja mais sobre os possíveis status na seção Especificação de parâmetros.

Para entender mais sobre as combinações de capacidades, veja também a seção Cenários de response.

No endpoint da v2 (/processes/v2/{id}), também devolvemos algumas informações adicionais do usuário, conforme exemplo abaixo:

"processAdditionalInfo": {
      "transactionId": "2ed76ac5-8fd7-4477-839d-92bedd7e9fd5",
      "personName": "Nome da pessoa",
      "personDocument": "Número do documento da pessoa",
      "personImage": "URL assinada da imagem da pessoa",
      "finishedAt": "2024-10-04T18:53:17.028228"
  }
}

Responses de erro

Dúvidas?

Não encontrou algo ou ainda precisa de ajuda? Se já é um cliente ou parceiro, pode entrar em contato através da Central de Ajuda.

GetReusableDocuments

Nesta seção, você encontrará como obter o documento para ser reaproveitado no by Client através da API REST

Antes de começar

Suas requisições de API são autenticadas utilizando um access-token. Qualquer requisição que não inclua um access-token válido retornará um erro.

Você pode ver mais sobre como gerar um access-token .

Endpoints:

UAT: ;
Produção: .

Cenários de response

Nesta seção, você encontrará os responses possíveis das combinações de capacidades separados por seus métodos, para facilitar seu entendimento sobre a integração by Client

Entender como funciona o retorno de cada parâmetro é fundamental para implementar a melhor tomada de decisão. Para ver detalhadamente o significado de cada parâmetro, veja a seção Especificação de parâmetros.

Em todas as combinações descritas a seguir, caso ocorra algum erro no processamento, o processo retornará um status = 5. Por esse motivo, os cenários abaixo não exibem responses referentes a essa condição. Exemplo:

  {
  "id": "80371b2a-3ac7-432e-866d-57fe37896ac6",
  "status": 5 //indica que houve um erro no processo
  }

Prova de vida

Response CreateProcess

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

Response GetProcess

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

Prova de vida

Response CreateProcess

{
  "id": "80371b2a-3ac7-432e-866d-57fe37896ac6",
  "status": 3,
  "liveness": 2
}

Response GetProcess

{
  "id": "80371b2a-3ac7-432e-866d-57fe37896ac6",
  "status": 3,
  "liveness": 2
}

Para os cenários onde o response no CreateProcess é o mesmo que o response do GetProcess, otimize sua aplicação e tome sua decisão de forma síncrona.

Prova de vida + Verificação de Identidade

Para os cenários onde o response no CreateProcess é o mesmo que o response do GetProcess, otimize sua aplicação e tome sua decisão de forma síncrona.

Prova de vida + Verificação de Identidade + Score de risco

Para os cenários onde o response no CreateProcess é o mesmo que o response do GetProcess, otimize sua aplicação e tome sua decisão de forma síncrona.

Dúvidas?

Não encontrou algo ou ainda precisa de ajuda? Se já é um cliente ou parceiro, pode entrar em contato através da Central de Ajuda.

Especificação de parâmetros

Nesta seção, você encontrará a especificação de todos os parâmetros da API REST do meio de integração by Client

CreateProcess - Payload da requisição

Nome

Tipo

Obrigatório / Opcional

Descrição

{
  "subject": {
    "Code": "12345678909",
    "Name": "Luke Skywalker",
    "Email": "luke@gmail.com",
    "Phone": "5511999998888"
  },
  "useCase": "Abertura de conta",
  "imagebase64": "/9j/4AAQSkZJRg[...]p6qtRUZeUQf//Z"
}

GetProcess (Prova de vida + Verificação de Identidade) - Response da requisição

Nome

Tipo

Descrição

{
  "id": "2b034568-dfaf-463f-94fb-18ed93c312e8",
  "status": 3,
  "unicoId": {
    "result": "inconclusive"
  },
  "liveness": 1,
  "identityFraudsters": {
    "result": "inconclusive"
  },
  "score": 50,
  "government"{
    "serpro": 50
  },
  "processAdditionalInfo": {
      "transactionId": "2ed76ac5-8fd7-4477-839d-92bedd7e9fd5",
      "personName": "Luke Skywalker",
      "personDocument": "12345678909",
      "personImage": "https://api.datafortress.private.unico[...]OXc93D",
      "finishedAt": "2024-10-04T18:53:17.028228"
  }
}

GetProcess (Captura de documentos) - Response da requisição

{
  "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "status": 3,
  },
  "document": {
    "id": "b97c3fd9-d95d-413f-bc0a-75eb87304421",
    "type": "CNH",
    "cpfMatch": false,
    "content": {
      "numero": "044589731564",
      "rgNumero": "123456789 SESP PR",
      "nomeCivil": "Homer Simpson",
      "filiacao": [
        "Monasimpson",
        "Monasimpson"
      ],
      "dataNascimento": "1990-05-12T00:00:00Z",
      "dataHabilitacao": "1997-11-18T00:00:00Z",
      "dataExpiracao": "2017-12-07T00:00:00Z",
      "dataEmissao": "2012-12-07T00:00:00Z",
      "localEmissao": "Curitiba PR",
      "categoria": "B",
      "renachNumero": "PR904987581"
    },
    "fileUrls": [
            "https://url-signer-1",
            "https://url-signer-2"
        ]
  }
}

GetReusableDocuments - Response da requisição

{
    "items": [{
        "documentType": "unico.moja.dictionary.br.rg.v2.Rg",
        "documentId": "2aaf6037-0153-415d-b9fe-cf7e8198408f"
    }]
}

Dúvidas?

Não encontrou algo ou ainda precisa de ajuda? Se já é um cliente ou parceiro, pode entrar em contato através da Central de Ajuda.

Recursos adicionais

Nesta seção, você encontrará os recursos adicionais relacionados ao meio de integração by Client

Postman Collection

Nesta seção, você encontrará você encontrará a collection do Postman com as APIs REST do by Client

Dúvidas?

Não encontrou algo ou ainda precisa de ajuda? Se já é um cliente ou parceiro, pode entrar em contato através da .

Padrão de captura (sem SDK)

Nesta seção, você encontrará como deve ser o padrão de captura da selfie do usuário, caso não utilize nossas SDKs

Para uma melhor performance das capacidades da plataforma IDCloud, orientamos que utilize nossos SDKs. Eles irão garantir o melhor funcionamento do produto como um todo, tanto em relação ao drop quanto na validação da Prova de vida.

Normalmente, as imagens capturadas apresentam os seguintes problemas:

Iluminação atrás do cliente - É necessário que a iluminação frontal seja boa o suficiente para uma captura nítida do rosto;
Iluminação estourada - A iluminação frontal precisa ser boa o suficiente para uma captura nítida do rosto;
Rosto muito próximo da captura + iluminação - O rosto precisa estar enquadrado no centro da câmera e a iluminação frontal precisa ser boa o suficiente;
Imagens embaçadas - O rosto da pessoa precisa estar bem focado no momento da captura;
Imagens tremidas - Estabilizar a câmera na hora da captura;
Cliente de óculos - O cliente precisa estar sem óculos ou objetos que possam impedir a visualização completa da face.

Como obter uma boa captura de imagem

Posicionamento da face e informações adicionais:
- A foto deve ser tirada de frente - olhar diretamente para a câmera e manter a cabeça ereta. O rosto deve estar centralizado. Os ombros devem estar alinhados, paralelos ao plano de imagem da câmera;
- Os olhos devem estar abertos naturalmente - pupilas e íris visíveis;
- Óculos - a foto deve ser capturada sem óculos;
- Sem chapéu, boné, ou máscara - a região da face deve ser claramente visível;
- Fisionomia Neutra - o rosto deve ter uma expressão neutra, a pessoa não deve sorrir, não levantar as sobrancelhas, não apertar os olhos ou franzir a testa;
- Penteado - O cabelo também não deve cobrir a zona de visibilidade dos olhos.
Iluminação e fundo: Fundo claro, liso e sem textura. Não deve conter manchas, linhas ou curvas que fiquem visíveis na imagem capturada. Cores claras como azul claro ou branco podem ser usadas desde que haja distinção suficiente entre a área do rosto/cabelo e o fundo. As configurações de cor da câmera não devem ser alteradas dependendo da cor de fundo. Atrás da imagem do rosto, não deve haver sombra. Também não deve haver objetos visíveis ao fundo, como pessoas, móveis, papéis de parede estampados, plantas. A iluminação precisa ser adequada e uniforme, distribuída igualmente na face para que não haja diferença entre o lado esquerdo e lado direito. A foto precisa ter brilho e bom contraste entre cabelo, rosto e fundo. Fotos com iluminação ruim são fotos quando a iluminação está somente na lateral, iluminação superior, ou iluminação inferior.
Imagens no formato JPEG, PNG ou JWT;
Imagens capturadas em cores.

Tamanhos / Proporções

Selfies:

Tamaho recomendado: Proporção 1920x1080 ou 1080x1920;
Orientação: Retrato;
Tamanho: No máximo 800kb, se necessário pode comprimir em Jpeg92.

Documentos:

Tamanho recomendado: Proporção HD - 1280x720 ou 720x1280;
Tamanho mínimo: Proporção VGA - 640x480 ou 480x640;
Orientação: Caso use tipificação/ocr é recomendado que seja capturado na orientação de leitura;
Tamanho: No máximo 800kb, se necessário pode comprimir em Jpeg92;
Enquadramento: É recomendado que na imagem não haja espaços sobrando (sem bordas). Quanto maior a área de folga (borda), é pior para a tipificação de documentos.

Exemplos de fotos no padrão e fora do padrão:

A foto deve ter:

Cor.
Enquadramento.
Foco nítido e claro, sem marcas de tinta ou vincos.

Olhar diretamente para a câmera.
Mostrar o tom de pele natural.
Ter brilho e contraste apropriados.

Fisionomia neutra e olhos abertos claramente visíveis
Sem cabelo sobre os olhos.
De frente para a câmera, sem olhar por cima do ombro ou inclinado, e mostrando as duas bordas do rosto claramente.
Com um fundo simples de cor clara, de preferência branco.
Com iluminação uniforme, sem sombras ou reflexos de flash no rosto e sem olhos vermelhos.
Sem lentes de contato coloridas.
Sem maquiagem.

O uso de óculos não é recomendado, mas nos casos de necessidade do uso de óculos:

Os olhos devem estar nítidos, sem o reflexo do flash ou da luz ambiente nos óculos e sem lentes coloridas.
A armação não deve cobrir nenhuma parte dos olhos.

Nota: Imagens retiradas do guia "ICAO Guide for MRTD Photo Guidelines. ICAO. Icao guide for mrtd photo guidelines.

Dicas

Adicionar orientações antes da captura para o usuário:

Utilize "frames" de captura para orientar o posicionamento do cliente frente ao rosto:

Dúvidas?

Não encontrou algo ou ainda precisa de ajuda? Se já é um cliente ou parceiro, pode entrar em contato através da .

Visão Geral

Nesta seção, você encontrará todas as especificações técnicas das APIs REST do by Client

Introdução

O by Client é um canal que oferece toda a liberdade para o cliente utilizar as soluções de validação de identidade da plataforma IDCloud.

Fluxos possíveis

Você pode combinar as capacidades como quiser e nos casos de uso mais distintos, mas para isso você deverá ter API Keys configuradas com as capacidades que deseja utilizar.

Para solicitar as capacidades na API Key, contate o responsável pelo seu projeto de integração ou o time de suporte da Unico para realizar essa configuração

Verifique abaixo todas as possíveis combinações de capacidade no by Client:

Também é possível utilizar as capacidades acima sem a Prova de vida, caso você já tenha um provedor de Prova de vida em sua operação;
Caso utilize a capacidade Verificação de Identidade, independentemente de suas combinações, é possível obter também o retorno de similaridade da Serpro ().

Capacidades síncronas e assíncronas

Em sua operação você poderá combinar as capacidades como bem quiser, porém cada capacidade terá sua comunicação, por exemplo:

Você pode ter uma operação que utilize as capacidades Verificação de Identidade + Detecção de Perfil Fraudador;
Ao criar o processo, a resposta da capacidade Verificação de Identidade será síncrona, no próprio response da API de criação de processo;
Já a capacidade de Detecção de Perfil Fraudador será executada de forma assíncrona, sendo necessário aguardar seu processamento e então realizar uma outra requisição GET para obter o resultado final do processo.

Abaixo veja as capacidades síncronas e assíncronas:

Capacidades síncronas

Prova de vida:

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

{
  "id": "80371b2a-3ac7-432e-866d-57fe37896ac6",
  "status": 3,
  "liveness": 2
}

Verificação de Identidade:

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

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

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

Validação (1:1)

{
    "authenticated": "true"
}

{
    "authenticated": "false"
}

Capacidades assíncronas

Verificação de Identidade:

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

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

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

Assim como a capacidade Verificação de Identidade é um capacidade "síncrona", ela também pode ser configurada para uso "assíncrono".

Score de risco:

{
  "id": "2b034568-dfaf-463f-94fb-18ed93c312e8",
  "status": 3,
  "unicoId": {
    "result": "inconclusive"
  },
  "liveness": 1,
  "score": 50
}

Detecção de Perfil Fraudador:

{
  "id": "2b034568-dfaf-463f-94fb-18ed93c312e8",
  "status": 3,
  "unicoId": {
    "result": "inconclusive"
  },
  "liveness": 1,
  "identityFraudsters": {
    "result": "yes"
  }
}

{
  "id": "2b034568-dfaf-463f-94fb-18ed93c312e8",
  "status": 3,
  "unicoId": {
    "result": "inconclusive"
  },
  "liveness": 1,
  "identityFraudsters": {
    "result": "inconclusive"
}

Captura e reaproveitamento de documentos:

{
  "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "status": 3,
  },
  "document": {
    "id": "b97c3fd9-d95d-413f-bc0a-75eb87304421",
    "type": "CNH",
    "cpfMatch": false,
    "content": {
      "numero": "044589731564",
      "rgNumero": "123456789 SESP PR",
      "nomeCivil": "Homer Simpson",
      "filiacao": [
        "Monasimpson",
        "Monasimpson"
      ],
      "dataNascimento": "1990-05-12T00:00:00Z",
      "dataHabilitacao": "1997-11-18T00:00:00Z",
      "dataExpiracao": "2017-12-07T00:00:00Z",
      "dataEmissao": "2012-12-07T00:00:00Z",
      "localEmissao": "Curitiba PR",
      "categoria": "B",
      "renachNumero": "PR904987581"
    },
    "fileUrls": [
            "https://url-signer-1",
            "https://url-signer-2"
        ]
  }
}

Dúvidas?

Não encontrou algo ou ainda precisa de ajuda? Se já é um cliente ou parceiro, pode entrar em contato através da .

Cenários de response

Nesta seção, você encontrará os responses possíveis das combinações de capacidades separados por seus métodos, para facilitar seu entendimento sobre a integração by Client

Entender como funciona o retorno de cada parâmetro é fundamental para implementar a melhor tomada de decisão. Para ver detalhadamente o significado de cada parâmetro, veja a seção Especificação de parâmetros.

  {
  "id": "80371b2a-3ac7-432e-866d-57fe37896ac6",
  "status": 5 //indica que houve um erro no processo
  }

Prova de vida

Response CreateProcess

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

Response GetProcess

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

Prova de vida

Response CreateProcess

{
  "id": "80371b2a-3ac7-432e-866d-57fe37896ac6",
  "status": 3,
  "liveness": 2
}

Response GetProcess

{
  "id": "80371b2a-3ac7-432e-866d-57fe37896ac6",
  "status": 3,
  "liveness": 2
}

Para os cenários onde o response no CreateProcess é o mesmo que o response do GetProcess, otimize sua aplicação e tome sua decisão de forma síncrona.

Prova de vida + Verificação de Identidade

Response CreateProcess

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

Response GetProcess

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

Observações:

A resposta de "yes" do unicoId.result (verificação de identidade) já engloba a validação da capacidade Prova de vida, ou seja, se a resposta for "yes" entende-se que a face do usuário é a do titular do CPF E ele estava ao vivo no momento da captura da selfie.

Prova de vida + Verificação de Identidade ❔

Response CreateProcess

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

Response GetProcess

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

Prova de vida + Verificação de Identidade ❔

Response CreateProcess

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

Response GetProcess

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

Prova de vida + Verificação de Identidade

Response CreateProcess

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

Response GetProcess

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

Prova de vida + Verificação de Identidade

Response CreateProcess

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

Response GetProcess

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

Para os cenários onde o response no CreateProcess é o mesmo que o response do GetProcess, otimize sua aplicação e tome sua decisão de forma síncrona.

Prova de vida + Verificação de Identidade + Score de risco

Prova de vida + Verificação de identidade

Response CreateProcess

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

Response GetProcess

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

Observações:

A resposta de "yes" do unicoId.result (Verificação de identidade) já engloba a validação da capacidade Prova de vida, ou seja, se a resposta for "yes" entende-se que a face do usuário é a do titular do CPF E ele estava ao vivo no momento da captura da selfie;
Quando a resposta do unicoId.result (Verificação de identidade) for "yes", não haverá a orquestração com a capacidade score de risco.

Prova de vida + Verificação de identidade❔+ Score de risco

Response CreateProcess

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

Response GetProcess

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

Observações:

Caso realize o GetProcess e o processo ainda não esteja concluído, retornaremos os status 1 ou 2. Só tome sua decisão final quando obtiver um status de conclusão do processo (status = 3). Você também pode utilizar o webhook para ser notificado quando o processo estiver concluído.

Prova de vida + Verificação de identidade❔+ Score de risco

Response CreateProcess

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

Response GetProcess

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

Observações:

Quando a resposta do liveness (Prova de vida) for 2, não haverá orquestração com o Score de risco.

Prova de vida + Verificação de identidade❔+ Score de risco

Response CreateProcess

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

Response GetProcess

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

Observações:

Quando o status = 3 e o unicoId.result for "inconclusive", mas não devolvermos o Score de risco, é porque houve um erro (drop) no motor de biométrica que não pôde gerar o score de probabilidade de risco.

Prova de vida + Verificação de Identidade + Score de risco

Response CreateProcess

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

Response GetProcess

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

Observações:

Quando o status = 3 e o unicoId.result for "no" não haverá orquestração com a capacidade Score de risco.

Prova de vida + Verificação de Identidade + Score de risco

Response CreateProcess

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

Response GetProcess

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

Para os cenários onde o response no CreateProcess é o mesmo que o response do GetProcess, otimize sua aplicação e tome sua decisão de forma síncrona.

Dúvidas?

Não encontrou algo ou ainda precisa de ajuda? Se já é um cliente ou parceiro, pode entrar em contato através da Central de Ajuda.

Integração by Client

Visão Geral

Introdução

Fluxos possíveis

Para solicitar as capacidades na API Key, contate o responsável pelo seu projeto de integração ou o time de suporte da Unico para realizar essa configuração

Verifique abaixo todas as possíveis combinações de capacidade no by Client:

Capacidades síncronas e assíncronas

Capacidades síncronas

Prova de vida:

Verificação de Identidade:

Validação (1:1)

Capacidades assíncronas

Verificação de Identidade:

Score de risco:

Detecção de Perfil Fraudador:

Captura e reaproveitamento de documentos:

Padrão de captura (sem SDK)

Para uma melhor performance das capacidades da plataforma IDCloud, orientamos que utilize nossos SDKs. Eles irão garantir o melhor funcionamento do produto como um todo, tanto em relação ao drop quanto na validação da Prova de vida.

Como obter uma boa captura de imagem

Tamanhos / Proporções

Selfies:

Documentos:

A foto deve ter:

Dicas

APIs

CreateProcess

Antes de começar

Endpoints:

Responses de erro

Prova de vida

Antes de começar

Endpoints:

Dúvidas?​

Verificação de Identidade

Antes de começar

Endpoints:

Dúvidas?​

Validação (1:1)

Antes de começar

Endpoints:

Dúvidas?​

Captura de documentos

Antes de começar

Endpoints:

GetProcess

Antes de começar

Endpoints:

Para implementar suas regras de negócio, sempre valide os status finais dos processos (3,4,5). Para validar a reposta das capacidades IDCloud, só considere o status = 3 para sua tomada de decisão. Veja mais sobre os possíveis status na seção Especificação de parâmetros.

Responses de erro

Dúvidas?​

GetReusableDocuments

Antes de começar

Endpoints:

Cenários de response

Entender como funciona o retorno de cada parâmetro é fundamental para implementar a melhor tomada de decisão. Para ver detalhadamente o significado de cada parâmetro, veja a seção Especificação de parâmetros.

Prova de vida

Prova de vida + Verificação de Identidade

Prova de vida + Verificação de Identidade + Score de risco

Especificação de parâmetros

CreateProcess - Payload da requisição

GetProcess (Prova de vida + Verificação de Identidade) - Response da requisição

GetProcess (Captura de documentos) - Response da requisição

GetReusableDocuments - Response da requisição

Dúvidas?​

Recursos adicionais

Postman Collection

Dúvidas?

Integração by Client

Validação (1:1)

Antes de começar

Endpoints:

CreateProcess

Dúvidas?​

Prova de vida

Antes de começar

Endpoints:

Dúvidas?​

GetProcess

Antes de começar

Endpoints:

Dúvidas?

Dúvidas?

Dúvidas?

Para implementar suas regras de negócio, sempre valide os status finais dos processos (`3`,`4`,`5`). Para validar a reposta das capacidades IDCloud, só considere o `status` = `3` para sua tomada de decisão. Veja mais sobre os possíveis status na seção Especificação de parâmetros.

Dúvidas?

Dúvidas?

Dúvidas?

Dúvidas?

Para implementar suas regras de negócio, sempre valide os status finais dos processos (`3`,`4`,`5`). Para validar a reposta das capacidades IDCloud, só considere o `status` = `3` para sua tomada de decisão. Veja mais sobre os possíveis status na seção Especificação de parâmetros.

Dúvidas?

Dúvidas?

Para implementar suas regras de negócio, sempre valide os status finais dos processos (`3`,`4`,`5`). Para validar a reposta das capacidades IDCloud, só considere o `status` = `3` para sua tomada de decisão. Veja mais sobre os possíveis status na seção .

Para implementar suas regras de negócio, sempre valide os status finais dos processos (`3`,`4`,`5`). Para validar a reposta das capacidades IDCloud, só considere o `status` = `3` para sua tomada de decisão. Veja mais sobre os possíveis status na seção .

Dúvidas?