Todas as páginas
Fornecido por GitBook
1 de 21

Integração by Unico

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

Visão Geral

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

Introdução


O by Unico é um canal que oferece uma infraestrutura de soluções de validação de identidade da plataforma IDCloud.

Tem por objetivo, simplificar o uso das capacidades da plataforma IDCloud oferecendo uma solução que pode ser integrada ao seu back-end e front-end e que aumenta a segurança das transações.

Com o by Unico, você terá um time de especialistas em segurança e melhores práticas de UX design para garantir a melhor conversão possível em sua operação. Pode ser utilizada de forma responsiva tanto no Desktop quanto no Mobile. Oferendo as seguintes possibilidades de uso:

Canal
Redirect
Open.window()
iFrame
Webview
Mensagens

Desktop

Webmobile

App mobile

Para o fluxo de mensagens, é possível enviar notificações pelos canais de: WhatsApp e/ou SMS.

Dispositivos compatíveis


Android

Compatível com todos os dispositivos com câmera frontal, Android 8+, armv7 ou arm64.

iOS

Compatível com todos os dispositivos iOS igual ou superior a versão 12.

Web


Compatível com todos os dispositivos com câmera frontal, seja em laptops ou mobile, respeitando a lista de navegadores oficialmente suportados abaixo:

Navegadores nativos

  • IOS:

    • versão superior ou igual a 12.

  • Android:

    • versão superior ou igual a 5.

Navegadores em dispositivos móveis

  • Android:

    • Chrome: versão superior ou igual a 90.

  • IOS:

    • Safari: versão superior ou igual a 14.1;

    • Chrome: versão superior ou igual a 90 (apenas para IOS versão igual superior a 14.4).

Navegadores de computadores/notebooks

  • Chrome:

    • versão superior ou igual a 85.

  • Firefox:

    • versão superior ou igual a 94.

  • Safari:

    • versão superior ou igual a 11.

Demais navegadores não são suportados.

Fluxos possíveis


O by Unico é um meio de integração do Unico IDCloud que permite que os clientes se integrem de forma mais simples e consigam conectar diferentes capacidades em uma mesma jornada. Esse meio de integração fornece os recursos necessários para realizar Prova de vida, Verificação de Identidade, Score de risco, Captura e reaproveitamento de documentos e Assinatura eletrônica.

Para isso, você irá mudar apenas o parâmetro flow no payload da REST API, e com isso terá diversas possibilidades de jornadas de verificação. Verifique abaixo a tabela relacionando os flows disponíveis e suas respectivas capacidades:

Flow
Prova de vida
Verificação de Identidade
Alerta de comportamento
Reaproveitamento e captura de documentos
Assinatura eletrônica
Validação (1:1)
Retorno de similaridade da Serpro

idlive

id

idlivetrust

idtrust

idunicodocs

idunicosign

idunicodocssign

idunicoserprodocssign

idtrustdocs

idtrustsign

idtrustdocssign

idtoken

idtokentrust

idtokensign

Caso utilize a capacidade Reaproveitamento e Captura de documentos, considere que é possível utilizar os seguintes documentos:

  • RG, CNH, CIN e Passaporte brasileiro.

Fluxos depreciados


Fluxos com Score de risco
Flow
Capacidades

idcheck

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

iddocs

Prova de vida + Verificação de Identidade + Score de risco + Reaproveitamento e captura de documentos

idsign

Prova de vida + Verificação de Identidade + Score de risco + Assinatura eletrônica

iddocssign

Prova de vida + Verificação de Identidade + Score de risco + Reaproveitamento e captura de documentos + Assinatura eletrônica

idchecktrust

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

idchecktrustdocs

Prova de vida + Verificação de Identidade + Score de risco + Alerta de comportamento + Reaproveitamento e captura de documentos

idchecktrustsign

Prova de vida + Verificação de Identidade + Score de risco + Alerta de comportamento + Assinatura eletrônica

idchecktrustdocssign

Prova de vida + Verificação de Identidade + Score de risco + Alerta de comportamento + Reaproveitamento e captura de documentos + Assinatura eletrônica

idcheckserpro

Prova de vida + Verificação de Identidade + Score de risco + Retorno de similaridade da Serpro

idcheckserprodocs

Prova de vida + Verificação de Identidade + Score de risco + Retorno de similaridade da Serpro + Reaproveitamento e captura de documentos

idcheckserprodocssign

Prova de vida + Verificação de Identidade + Score de risco + Retorno de similaridade da Serpro + Reaproveitamento e captura de documentos + Assinatura eletrônica

creditoconsignado

Prova de vida + Verificação de Identidade + Score de risco + Retorno de similaridade da Serpro + Assinatura eletrônica

Este fluxo funciona na forma de uma condicional:

  • Se o retorno de similaridade da Serpro for positivo, solicitamos a assinatura eletrônica;

  • Se o retorno de similaridade da Serpro for negativo, pedimos os documentos do usuário para realizar o facematch:

    • Se o resultado do facematch for positivo, solicitamos a assinatura eletrônica;

    • Se o resultado do facematch for negativo, finalizamos a jornada sem pedir a assinatura eletrônica.

A capacidade Score de risco está sendo descontinuada e só poderá ser utilizada em casos excepcionais.


Como integrar


1

Se autentique

Primeiramente você deve possuir uma conta de serviço e realizar a autenticação OAuth2 para obter um access-token válido.

Saiba mais em Autenticação.

2

Crie um processo

Com o access-token obtido no passo anterior, realize uma requisição do tipo POST no endpoint client/v1/process(aqui você informará o "flow" que deseja utilizar).

Saiba mais em CreateProcess.

3

Defina onde será a jornada do seu usuário

Nesta etapa você irá definir onde será a jornada do seu usuário.

  • A jornada será web? Você pode utilizar o Redirect do navegador ou o SDK.

  • A jornada será no seu app? Você pode utilizar uma Webview.

  • A jornada será no fluxo de mensagens? Você pode enviar notificações via WhatsApp e SMS (para isso, basta informar o parâmetro correspondente na requisição CreateProcess no passo 2).

4

Consulte o resultado do processo

Com o access-token obtido no passo 1, realize uma requisição do tipo GET no endpoint client/v1/process/{id}(aqui você informará o "id" do processo que foi criado no passo 2), consulte o resultado do processo e tome a decisão de aprovar ou não o usuário.

Saiba mais em GetProcess.

Para otimizar sua integração, você pode utilizar o Webhook e saber quando o resultado do seu processo estiver concluído.


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.

API

Nesta seção, você encontrará tudo relacionado as APIs REST do meio de integração by Unico

API Reference

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

Criação do Processo

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


Introdução


Nesta seção, você encontrará a documentação detalhada sobre o funcionamento do endpoint de Criação de Processos no by Unico. Perceba que, para utilizar as capacidades da plataforma IDCloud neste meio de integração, basta alterar o valor do parâmetro "flow" no momento de criar o processo e a Unico será a responsável por orquestrar todas as capacidades que deseja utilizar.

Entenda mais sobre a utilização das capacidades no by Unico na seção Visão Geral.

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.cadastro.uat.unico.app;

  • Produção: https://api.cadastro.unico.app.


Criação do Processo


Criar Processo

post

Endpoint para criar um novo processo no by Unico.

Autorizações
Corpo
callbackUristringObrigatório

Define para onde o usuário será redirecionado ao fim do processo. Valores possíveis são: Uma URL https para redirecionar páginas web (ex: https://developers.unico.io/callback), uma URL Schema para redirecionamento em aplicações móveis nativas (ex: br.com.meupacote.app://callback - o callback precisa estar registrado em sua aplicação móvel) ou sem redireciomento (incluir apenas a '/').

Example: /
flowstring · enumObrigatório

Tipo de fluxo. Veja detalhes dos fluxos na seção 'Visão Geral' nesta mesma documentação (alguns fluxos foram depreciados e você pode consultá-los também na seção 'Visão Geral').

Example: idunicosignValores possíveis:
clientReferencestringOpcional

É um identificador não obrigatório que será utilizado como indexador no portal e você pode utilizar como forma de associação (foreign key) entre seu sistema e o IDCloud.

Example: 60837cd3-ed3c-4038-ad7c-0a85ad64b03a
companyBranchIdstringOpcional

É o ID da filial onde o processo será criado. Caso haja somente uma filial associada a conta de serviço, não há a necessidade de passar este parâmetro. Caso haja separação de processos por filial, você receberá os IDs das filiais do time Unico.

Example: 60837cd3-ed3c-4038-ad7c-0a85ad64b03a
bioTokenIdstringOpcional

Identificação do token biométrico. Obrigatório para o flow "idtoken" e deve-se utilizar um id de um processo concluído de qualquer outro flow de verificação de identidade.

Example: 60837cd3-ed3c-4038-ad7c-0a85ad64b03a
purposestring · enumObrigatório

Propósito do processo.

Example: creditprocessValores possíveis:
expiresInstringOpcional

É o tempo de expiração do processo em segundos a partir de sua criação. Deve ser passado um valor no padrão "10080s", com "s" no fim. Caso este parâmetro não seja informado, será usado o valor default de 7 dias.

Example: 3600s
Respostas
200
Processo criado com sucesso.
application/json
400
Payload inválido.
application/json
401
Erro no access-token.
application/json
500
Erro inesperado (Erro interno ou problema de parâmetro).
application/json
post
POST /client/v1/process HTTP/1.1
Host: api.cadastro.uat.unico.app
Authorization: Bearer JWT
Content-Type: application/json
Accept: */*
Content-Length: 950

{
  "callbackUri": "/",
  "flow": "idunicosign",
  "flow_config": {
    "biometry_capture": {
      "enabled_back_camera": true
    }
  },
  "clientReference": "60837cd3-ed3c-4038-ad7c-0a85ad64b03a",
  "companyBranchId": "60837cd3-ed3c-4038-ad7c-0a85ad64b03a",
  "bioTokenId": "60837cd3-ed3c-4038-ad7c-0a85ad64b03a",
  "person": {
    "duiType": "DUI_TYPE_BR_CPF",
    "duiValue": "12345678909",
    "friendlyName": "Luke Skywalker",
    "phone": "5511912345678",
    "email": "teste@teste.com",
    "notifications": [
      {
        "notificationChannel": "NOTIFICATION_CHANNEL_WHATSAPP"
      }
    ]
  },
  "purpose": "creditprocess",
  "expiresIn": "3600s",
  "contextualization": {
    "currency": "BRL",
    "price": 15990.9,
    "locale": {
      "ptBr": {
        "reason": "Abertura de cadastro"
      },
      "enUs": {
        "reason": "Identity validation for personal loan application"
      },
      "esMX": {
        "reason": "Validación de identidad para solicitud de préstamo personal"
      }
    }
  },
  "payload": [
    {
      "envelopePayload": {
        "documents": [
          {
            "documentName": "teste",
            "fileContents": "JVBERi0xLjMNCiXi48/[...]DQoNCnN0YXJ0eHJlZg0KMjcxNA0KJSVFT0YNCg=="
          }
        ]
      }
    }
  ]
}
{
  "process": {
    "id": "53060f52-f146-4c12-a234-5bb5031f6f5b",
    "companyBranchId": "60837cd3-ed3c-4038-ad7c-0a85ad64b03a",
    "flow": "idunicosign",
    "callbackUri": "/path/to/callback-url/",
    "userRedirectUrl": "https://cadastro.dev.unico.app/process/53060f52-f146-4c12-a234-5bb5031f6f5b",
    "state": "PROCESS_STATE_CREATED",
    "createdAt": "2023-10-09T15:15:25.417105Z",
    "person": {
      "duiType": "DUI_TYPE_BR_CPF",
      "duiValue": "73689290074",
      "friendlyName": "Luke Skywalker",
      "phone": "5511912345678",
      "email": "teste@teste.com",
      "notifications": [
        {
          "notificationChannel": "NOTIFICATION_CHANNEL_WHATSAPP"
        }
      ]
    },
    "purpose": "creditprocess",
    "authenticationInfo": {},
    "capacities": [
      [
        "PROCESS_CAPACITY_IDUNICO",
        "PROCESS_CAPACITY_IDCHECK",
        "PROCESS_CAPACITY_IDDOCS"
      ]
    ],
    "expiresAt": "2023-10-09T15:15:25.417105Z",
    "token": "eyJhbGciOiJSUzI1[...]d_jhQ",
    "companyData": {
      "branchId": "60837cd3-ed3c-4038-ad7c-0a85ad64b03a",
      "countryCode": "BRA"
    },
    "clientReference": "60837cd3-ed3c-4038-ad7c-0a85ad64b03a"
  }
}

Os processos devem ser criados exclusivamente em uma comunicação backend-to-backend, devido à nossa política de CORS, que impede a criação de processos em uma comunicação frontend-to-backend.

A obrigatoriedade de parâmetros na criação do processo pode mudar a depender dos flows utilizados. Ex:

  • Em flows que possuem Assinatura eletrônica, é obrigatório o envio do objeto payload e todas as suas propriedades;

  • Em flows que possuem Validação (1:1), é obrigatório o envio da propriedade bioTokenId.

Dicas:

  • Para mais informações sobre os erros possíveis para este endpoint, consulte a seção Erros.


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.

Criação de processos separados por flows

Nesta seção, você encontrará exemplos de requisições de Ciação de processos no by Unico


Requisições separadas por flows


{
  "callbackUri": "/path/to/url",
  "flow": "idlive", //este é um exemplo de flow
  "companyBranchId": "60837cd3-ed3c-4038-ad7c",
  "person": {
    "duiType": "DUI_TYPE_BR_CPF",
    "duiValue": "73689290074",
    "friendlyName": "Luke Skywalker",
    "phone": "5511974749090",
    "email": "luke@unico.io",
    "notifications":
    [
      {
        "notificationChannel": "NOTIFICATION_CHANNEL_WHATSAPP"
      },
      {
        "notificationChannel": "NOTIFICATION_CHANNEL_SMS"
      }
    ]
  },
  "purpose": "biometryonboarding",
  "expiresIn": "3600s"
}
{
  "callbackUri": "/path/to/url",
  "flow": "idunicosign", //este é um exemplo de flow
  "person": {
    "duiType": "DUI_TYPE_BR_CPF",
    "duiValue": "73689290074",
    "friendlyName": "Luke Skywalker",
    "phone": "5511974749090",
    "email": "luke@unico.io",
    "notifications": 
    [
      {
        "notificationChannel": "NOTIFICATION_CHANNEL_WHATSAPP"
      },
      {
        "notificationChannel": "NOTIFICATION_CHANNEL_SMS"
      }
    ]
  },
  "purpose": "biometryonboarding",
  "expiresIn": "3600s",
  "payload": [
    {
      "envelopePayload": {
        "documents": [
          {
            "documentName": "teste",
            "fileContents": "JVBERi0xLjMNCiXi48/[...]DKJSVFT0YNCg=="
          }
        ]
      }
    }
  ]
}
{
  "callbackUri": "/path/to/url",
  "flow": "idtoken", //este é um exemplo de flow
  "bioTokenId": "339f9225-6f09-4303-9688-bf35944787e1",
  "person": {
    "duiType": "DUI_TYPE_BR_CPF",
    "duiValue": "73689290074"
    "friendlyName": "Luke Skywalker",
    "phone": "5511974749090",
    "email": "luke@unico.io",
    "notifications": 
    [
      {
        "notificationChannel": "NOTIFICATION_CHANNEL_WHATSAPP"
      },
      {
        "notificationChannel": "NOTIFICATION_CHANNEL_SMS"
      }
    ]
  },
  "purpose": "biometryonboarding",
  "expiresIn": "3600s"
}
{
  "callbackUri": "/path/to/url",
  "flow": "idtokensign", //este é um exemplo de flow
  "bioTokenId": "339f9225-6f09-4303-9688-bf35944787e1",
  "person": {
    "duiType": "DUI_TYPE_BR_CPF",
    "duiValue": "73689290074"
    "friendlyName": "Luke Skywalker",
    "phone": "5511974749090",
    "email": "luke@unico.io",
    "notifications": 
    [
      {
        "notificationChannel": "NOTIFICATION_CHANNEL_WHATSAPP"
      },
      {
        "notificationChannel": "NOTIFICATION_CHANNEL_SMS"
      }
    ]
  },
  "purpose": "biometryonboarding",
  "expiresIn": "3600s",
  "payload": [
    {
      "envelopePayload": {
        "documents": [
          {
            "documentName": "teste",
            "fileContents": "JVBERi0xLjMNCiXi48/[...]DKJSVFT0YNCg=="
          }
        ]
      }
    }
  ]

Outras formas de fazer uma requisição (request)


curl -X 'POST' \
  'https://api.cadastro.uat.unico.app/client/v1/process/' \
  -H 'accept: application/json' \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer {{TOKEN}}'
  -d '{
    "callbackUri": "/",
    "flow": "id",
    "person": {
        "duiType": "DUI_TYPE_BR_CPF",
        "duiValue": "73689290074",
    "friendlyName": "John Doe"
    },
    "purpose": "creditprocess"
}'

Para utilizar o Postman, siga os passos:

  1. Selecione o método POST.

  2. Insira a URL https://api.cadastro.uat.unico.app/client/v1/process/.

  3. Selecione a aba Authorization.

  4. Na lista de Type, selecione Bearer Token.

  5. Insira o token obtido no campo Token com o prefixo Bearer .

  6. Selecione a aba Body e insira os dados abaixo de acordo com sua necessidade.

{
  "callbackUri": "/paht/callback-url",
  "flow": "id",
  "person": {
    "duiType": "DUI_TYPE_BR_CPF",
    "duiValue": "73689290074",
    "friendlyName": "John Doe"
  },
  "purpose": "creditprocess"
}
const axios = require("axios");

const apiUrl = "https://api.cadastro.uat.unico.app/client/v1/process/";
const token =  "<YOUR_TOKEN_HERE>";

const requestData = {
  callbackUri: "/path/to/url",
  flow: "id",
  person: {
    duiType: "DUI_TYPE_BR_CPF",
    duiValue: "73689290074",
    friendlyName: "John Doe",
  },
  purpose: "creditprocess",
};

const headers = {
  "Content-Type": "application/json",
  Authorization: `Bearer ${token}`,
  accept: "application/json",
};

axios
  .post(apiUrl, requestData, { headers })
  .then((response) => {
    console.log("Resposta da API:", response.data);
  })
  .catch((error) => {
    console.error("Erro:", error);
  });
import java.net.URI;
import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;
import java.util.HashMap;
import java.util.Map;

public class Main {
    public static void main(String[] args) {
        String apiUrl = "https://api.cadastro.uat.unico.app/client/v1/process/";
        String token = "<YOUR_TOKEN_HERE>";

        // Crie o corpo da solicitação em formato JSON
        String requestBody = "{\"callbackUri\":\"/\",\"flow\":\"id\",\"person\":{\"duiType\":\"DUI_TYPE_BR_CPF\",\"duiValue\":\"73689290074\"},\"purpose\":\"creditprocess\"}";

        // Configure os cabeçalhos da solicitação
        Map<String, String> headers = new HashMap<>();
        headers.put("Content-Type", "application/json");
        headers.put("Authorization", "Bearer " + token);
        headers.put("accept", "application/json");

        // Crie a instância do HttpClient
        HttpClient httpClient = HttpClient.newBuilder().build();

        // Crie a solicitação HTTP POST
        HttpRequest request = HttpRequest.newBuilder()
                .uri(URI.create(apiUrl))
                .headers(headers.entrySet().stream()
                        .map(e -> e.getKey() + ":" + e.getValue())
                        .toArray(String[]::new))
                .POST(HttpRequest.BodyPublishers.ofString(requestBody))
                .build();

        try {
            // Envie a solicitação e obtenha a resposta
            HttpResponse<String> response = httpClient.send(request, HttpResponse.BodyHandlers.ofString());

            // Exiba a resposta da API
            System.out.println("Status da resposta: " + response.statusCode());
            System.out.println("Corpo da resposta: " + response.body());
        } catch (Exception e) {
            e.printStackTrace();
        }
    }
}
using System;
using System.Net.Http;
using System.Text;
using System.Threading.Tasks;

class Program
{
    static async Task Main()
    {
        string apiUrl = "https://api.cadastro.uat.unico.app/client/v1/process/";
        string token = "<YOUR_TOKEN_HERE>";

        // Crie o corpo da solicitação em formato JSON
        string requestBody = "{\"callbackUri\":\"/\",\"flow\":\"id\",\"person\":{\"duiType\":\"DUI_TYPE_BR_CPF\",\"duiValue\":\"73689290074\"},\"purpose\":\"creditprocess\"}";

        // Configure os cabeçalhos da solicitação
        HttpClient client = new HttpClient();
        client.DefaultRequestHeaders.Add("Content-Type", "application/json");
        client.DefaultRequestHeaders.Add("Authorization", "Bearer " + token);
        client.DefaultRequestHeaders.Add("accept", "application/json");

        try
        {
            // Envie a solicitação HTTP POST
            HttpResponseMessage response = await client.PostAsync(apiUrl, new StringContent(requestBody, Encoding.UTF8, "application/json"));

            // Verifique o status da resposta
            if (response.IsSuccessStatusCode)
            {
                string responseBody = await response.Content.ReadAsStringAsync();
                Console.WriteLine("Status da resposta: " + response.StatusCode);
                Console.WriteLine("Corpo da resposta: " + responseBody);
            }
            else
            {
                Console.WriteLine("Erro na solicitação. Status da resposta: " + response.StatusCode);
            }
        }
        catch (Exception e)
        {
            Console.WriteLine("Erro: " + e.Message);
        }
    }
}
package main

import (
    "bytes"
    "fmt"
    "net/http"
)

func main() {
    apiURL := "https://api.cadastro.uat.unico.app/client/v1/process/"
    token := "<YOUR_TOKEN_HERE>";

    // Crie o corpo da solicitação em formato JSON
    requestBody := []byte(`{
        "callbackUri": "/path/to/url",
        "flow": "id",
        "person": {
            "duiType": "DUI_TYPE_BR_CPF",
            "duiValue": "73689290074"
        },
        "purpose": "creditprocess"
    }`)

    // Crie um cliente HTTP
    client := &http.Client{}

    // Crie uma solicitação HTTP POST
    req, err := http.NewRequest("POST", apiURL, bytes.NewBuffer(requestBody))
    if err != nil {
        fmt.Println("Erro ao criar a solicitação HTTP:", err)
        return
    }

    // Defina os cabeçalhos da solicitação
    req.Header.Set("Content-Type", "application/json")
    req.Header.Set("Authorization", "Bearer "+token)
    req.Header.Set("accept", "application/json")

    // Faça a solicitação HTTP
    resp, err := client.Do(req)
    if err != nil {
        fmt.Println("Erro ao fazer a solicitação HTTP:", err)
        return
    }
    defer resp.Body.Close()

    // Verifique o status da resposta
    if resp.StatusCode == http.StatusOK {
        // Leitura do corpo da resposta
        var responseBody []byte
        _, err := resp.Body.Read(responseBody)
        if err != nil {
            fmt.Println("Erro ao ler o corpo da resposta:", err)
            return
        }

        fmt.Println("Status da resposta:", resp.Status)
        fmt.Println("Corpo da resposta:", string(responseBody))
    } else {
        fmt.Println("Erro na solicitação. Status da resposta:", resp.Status)
    }
}

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.

Consultar Resultado do Processo

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


Introdução


Nesta seção, você encontrará a documentação detalhada sobre o funcionamento do endpoint de Consulta do Resultado de Processos no by Unico.

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.cadastro.uat.unico.app;

  • Produção: https://api.cadastro.unico.app.


Consulta do Resultado do Processo


Consultar Resultado do Processo

get

Endpoint para buscar o resultado de um processo no by Unico.

Autorizações
Parâmetros de rota
processIdstringObrigatório

ID do processo.

Respostas
200
Detalhes do processo obtidos com sucesso.
application/json
400
Quando o ID de processo é inválido.
application/json
401
Erro no access-token.
application/json
404
Quando não foi possível encontrar o processo.
application/json
500
Erro inesperado (Erro interno ou problema de parâmetro).
application/json
get
GET /client/v1/process/{processId} HTTP/1.1
Host: api.cadastro.uat.unico.app
Authorization: Bearer JWT
Accept: */*
{
  "process": {
    "id": "53060f52-f146-4c12-a234-5bb5031f6f5b",
    "flow": "idunicosign",
    "callbackUri": "/path/to/callback-url/",
    "userRedirectUrl": "https://cadastro.dev.unico.app/process/53060f52-f146-4c12-a234-5bb5031f6f5b",
    "state": "PROCESS_STATE_FINISHED",
    "result": "PROCESS_RESULT_OK",
    "createdAt": "2023-10-05T18:28:58.537985Z",
    "finishedAt": "2023-10-09T15:15:25.417105Z",
    "person": {
      "duiType": "DUI_TYPE_BR_CPF",
      "duiValue": "73689290074",
      "friendlyName": "Luke Skywalker",
      "notifications": [
        {
          "notificationChannel": "NOTIFICATION_CHANNEL_WHATSAPP"
        }
      ]
    },
    "purpose": "creditprocess",
    "authenticationInfo": {
      "authenticationResult": "AUTHENTICATION_RESULT_INCONCLUSIVE",
      "authenticationId": "fd433602-d496-4291-adbb-dda95a3e50b1",
      "livenessResult": "LIVENESS_RESULT_LIVE",
      "bioTokenEngineResult": "BIO_TOKEN_ENGINE_RESULT_UNSPECIFIED",
      "identityFraudstersResult": "TRUST_RESULT_UNSPECIFIED",
      "scoreEngineResult": {
        "scoreEnabled": "SCORE_ENABLED_TRUE",
        "score": 50
      },
      "serproResult": {
        "score": 50
      }
    },
    "capacities": [
      "PROCESS_CAPACITY_IDUNICO",
      "PROCESS_CAPACITY_IDSIGN",
      "PROCESS_CAPACITY_IDLIVE"
    ],
    "services": [
      {
        "documents": [
          {
            "doc": {
              "version": 2,
              "code": "RG",
              "data": {
                "dataExpiracao": "2025-10-35T00:00:00Z",
                "dataHabilitacao": "2022-08-09T00:00:00Z",
                "dataNascimento": "1950-06-30T00:00:00Z",
                "nomeCivil": "John Doe",
                "rgNumero": 5478854,
                "categoria": "D",
                "cpfNumero": 73689290074,
                "dataEmissao": "2020-08-09T00:00:00Z",
                "localEmissao": "DEREX SP",
                "numero": 85775532778,
                "renachNumero": ""
              }
            },
            "typified": true,
            "cpf_match": true,
            "face_match": true,
            "doc_id": "1e61a978-3673-4fdd-8fa8-808d0a26d131",
            "validate_doc": true,
            "reused_doc": true,
            "signed_url": "https://api.datafortre[...]OXc9PQ%3D%3D"
          }
        ],
        "consent_granted": true,
        "envelopeId": "4d4f3d90-04a3-4259-b63b-930ab10d2e47",
        "documentIds": [
          "03307601-b518-49ca-b368-ae3919e24e54"
        ]
      }
    ],
    "expiresAt": "2023-10-09T15:15:25.417105Z",
    "token": "",
    "companyData": {
      "branchId": "60837cd3-ed3c-4038-ad7c-0a85ad64b03a",
      "countryCode": "BRA"
    },
    "clientReference": "60837cd3-ed3c-4038-ad7c-0a85ad64b03a"
  }
}

Os processos devem ser criados exclusivamente em uma comunicação backend-to-backend, devido à nossa política de CORS, que impede a criação de processos em uma comunicação frontend-to-backend.

O conteúdo retornado no parâmetro process.services.documents.doc.data, referente à tecnologia de OCR Extração, pode ser consultado abaixo:

  • Type: CNH

  • Content: Carteira Nacional de Habilitação

    • string numero;

    • string rgNumero;

    • string cpfNumero;

    • string nomeCivil;

    • array <string> filiacao;

    • datetime dataNascimento;

    • datetime dataHabilitacao;

    • datetime dataExpiracao;

    • string localEmissao;

    • string categoria;

"content": {
    "numero": "044589731564",
    "rgNumero": "123456789 SESP PR",
    "cpfNumero": "54858809080"
    "nomeCivil": "Homer Simpson",
    "filiacao": [
        "Monasimpson",
        "Monasimpson"
    ],
    "dataNascimento": "1990-05-12T00:00:00Z",
    "dataHabilitacao": "1997-11-18T00:00:00Z",
    "dataExpiracao": "2017-12-07T00:00:00Z",
    "localEmissao": "Curitiba PR",
    "categoria": "B",
}
  • Type: RG

  • Content: Registro Geral

    • string numero;

    • string cpfNumero;

    • string nomeCivil;

    • array <string> filiacao;

    • datetime dataNascimento;

    • datetime dataEmissao;

    • string naturalidade;

    • string orgaoEmissor;

    • string ufEmissor;

"content": {
    "numero": "4815162342",
    "cpfNumero": "54858809080",
    "nomeCivil": "Daniel Coelho Da Costa",
    "filiacao": [
        "Rosa Coelho Da Costa",
        "Edivaldo Da Costa",
    ],
    "dataNascimento": "1980-12-19T03:00:00Z",
    "dataEmissao": "2012-12-21T02:00:00Z",
    "naturalidade": "Sao Paulo SP",
    "orgaoEmissor": "Secretaria Da Segurança Pública (SSP)",
    "ufEmissor": "UF_SP"
}
  • Type: CIN

  • Content: Carteira de Identidade Nacional

    • string cpfNumero;

    • string nomeCivil;

    • array <string> filiacao;

    • datetime dataNascimento;

    • datetime dataEmissao;

    • datetime dataExpiracao;

    • string orgaoEmissor;

    • string naturalidade;

    • string nacionalidade;

    • string localEmissao;

"content": {
    "cpfNumero": "54858809080",
    "nomeCivil": "Vitor Ra",
    "filiacao": [
        "Danilo Luis Renan Ramos",
        "Giovanna Vitoria",
    ],
    "dataNascimento": "1980-12-19T03:00:00Z",
    "dataEmissao": "2024-03-02T00:00:00Z",
    "dataExpiracao": "2034-03-02T00:00:00Z",
    "orgaoEmissor": "Detran/Rj",
    "naturalidade": "Rio De Janeiro RJ",
    "nacionalidade": "BRA",
    "localEmissao": "Rio De Janeiro RJ",

}
  • Type: PASSAPORTE

  • Content: Passaporte brasileiro

    • string numero;

    • string nome;

    • string sobrenome;

    • string paisEmissor;

    • string nacionalidade;

    • string naturalidade;

    • array <string> filiacao;

    • datetime dataNascimento;

    • datetime dataEmissao;

    • datetime dataExpiracao;

    • string autoridade.

"content": {
    "numero": "AA011906",
    "nome": "CHANCHÃO AMARELO",
    "sobrenome": "PASSAREDO",
    "paisEmissor": "BRA",
    "nacionalidade": "BRASILEIRO(A)",
    "naturalidade": "<null>",
    "filiacao": [
         "Monasimpson",
         "Monasimpson"
    ],
    "dataNascimento": "1920-06-01T00:00:00Z",
    "dataEmissao": "2000-01-01T00:00:00Z",
    "dataExpiracao": "2010-01-01T00:00:00Z",
    "autoridade": "SR/DPF/DF"
}
  • Type: UNKNOWN

  • Content: Documento desconhecido. Significa que não foi possível detectar o tipo daquele documento.

content {
}

Caso não consigamos extrair algum campo do documento, ele não é listado no retorno da API.

Dicas:

  • Para implementar suas regras de negócio, sempre valide o retorno das capacidades analisando os parâmetros do response na seguinte ordem:

    • state = PROCESS_STATE_FINISHED E result = PROCESS_RESULT_OK;

      • ENTÃO, pode realizar a tomada de decisão analisando os retornos do parâmetro authenticationInfo.

      • Caso receba o state = PROCESS_STATE_FINISHED E result = PROCESS_RESULT_ERROR, interprete que houve algum erro no processamento da biometria e tente novamente.

  • Para melhorar a performance da sua operação, você pode utilizar nossos Webhooks e só consultar o resultado de processos que estiverem nos status finalizados;

  • Para mais informações sobre os erros possíveis para este endpoint, consulte a seção Erros.


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.

Obter Selfie do Usuário

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


Introdução


Nesta seção, você encontrará a documentação detalhada sobre o funcionamento do endpoint de Obtenção da Selfie do Usuário no by Unico. Este endpoint fornecerá a selfie, com marca d'água, do usuário final em processos concluídos, permitindo que você a utilize como suporte em casos de contestação por parte do usuário.

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.cadastro.uat.unico.app;

  • Produção: https://api.cadastro.unico.app.


Obtenção da Selfie do Usuário


Obter Selfie do Usuário

get

Endpoint para obter a selfie do processo do by Unico.

Autorizações
Parâmetros de rota
processIdstringObrigatório

ID do processo.

Respostas
200
Selfie obtida com sucesso.
application/json
400
Quando o ID de processo é inválido.
application/json
401
Erro no access-token.
application/json
403
Quando a conta de serviço não possui a permissão para obter a selfie.
application/json
404
Quando não foi possível encontrar o processo.
application/json
500
Erro inesperado (Erro interno ou problema de parâmetro).
application/json
get
GET /client/v1/process/{processId}/selfie HTTP/1.1
Host: api.cadastro.uat.unico.app
Authorization: Bearer JWT
Accept: */*
{
  "fileContents": "/9j/4AAQSkZJRgABAQA[...]QkeQUjE",
  "contentType": "image/jpeg"
}

Os processos devem ser criados exclusivamente em uma comunicação backend-to-backend, devido à nossa política de CORS, que impede a criação de processos em uma comunicação frontend-to-backend.

Pontos importantes:

  • A liberação da permissão para obter a selfie do usuário dependerá de avaliação interna da Unico. Entenda com o responsável do seu projeto se poderá consumir este serviço;

  • Só é possível recuperar a selfie com a marca d'água.

Para mais informações sobre os erros possíveis para este endpoint, consulte a seção Erros.


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.

Obter Conjunto Probatório

Nesta seção, você encontrará como obter o conjunto probatório de um processo no by Unico através da API REST


Introdução


Nesta seção, você encontrará a documentação detalhada sobre o funcionamento do endpoint de Obtenção do Conjunto Probatório no by Unico. Este endpoint fornecerá o conjunto probatório da transação biométrica finalizada, permitindo que você o armazene para possíveis contestações futuras por parte do usuário final.

Para entender mais sobre o conjunto probatório, veja a seção Especificação do Conjunto Probatório.

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.cadastro.uat.unico.app;

  • Produção: https://api.cadastro.unico.app.


Obtenção do Conjunto Probatório


Obter Conjunto Probatório

get

Endpoint para obter o conjunto probatório do processo no by Unico.

Autorizações
Parâmetros de rota
processIdstringObrigatório

ID do processo.

Respostas
200
Conjunto probatório obtido com sucesso.
application/json
400
Quando o ID de processo é inválido.
application/json
401
Erro no access-token.
application/json
404
Quando não foi possível encontrar o processo.
application/json
500
Erro inesperado (Erro interno ou problema de parâmetro).
application/json
get
GET /client/v1/process/{processId}/evidenceset HTTP/1.1
Host: api.cadastro.uat.unico.app
Authorization: Bearer JWT
Accept: */*
{
  "fileContents": "JVBERi0xLjUNCiWDk[...]NCg==",
  "contentType": "x-pdf"
}

Os processos devem ser criados exclusivamente em uma comunicação backend-to-backend, devido à nossa política de CORS, que impede a criação de processos em uma comunicação frontend-to-backend.

O conjunto probatório só está disponível para os processos finalizados.

Para mais informações sobre os erros possíveis para este endpoint, consulte a seção Erros.


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 do conjunto probatório

Nesta seção, você encontrará todas as especificações do conjunto probatório do by Unico


O conjunto probatório é um documento em .pdf contendo evidências de autenticação de um usuário que realizou a validação de identidade no by Unico.

A seguir, veja como este documento é representado, bem como a especificação de seus campos de retorno:

Exemplo de conjunto probatório

Campos do Conjunto Probatório (clique em cada um para saber mais)

Usuário
  • Foto com marca d'água;

  • Nome - indica o nome da pessoa autenticada. Esse dado é obtido através do parâmetro person.friendly_name do CreateProcess;

  • CPF do titular - indica o CPF da pessoa autenticada. Esse dado é obtido através do parâmetro person.dui_value do CreateProcess;

  • Canal de contato - indica o canal de comunicação com a pessoa autenticada. Esse dado é obtido através do parâmetro person.notifications do CreateProcess.

Processo
  • Fluxo executado - indica qual fluxo foi executado. Esse dado é obtido através do parâmetro flow do CreateProcess;

  • Identificador do processo - indica o id do processo. Esse dado é obtido através do parâmetro procees.id no retorno do CreateProcess;

  • URL - indica a URL de autenticação do processo;

  • Criação - indica a data da criação do processo. Esse dado é obtido através do parâmetro createdAt no retorno do CreateProcess;

  • Finalização - indica a data de finalização do processo. Esse dado é obtido através do parâmetro finishedAt no retorno do CreateProcess;

  • Estado - indica o status do processo. Esse dado é obtido através do parâmetro state no retorno do CreateProces;

  • Empresa - indica a empresa.

Validações
  • Tipo de validação - indica o tipo de validação da autenticação do processo;

  • Identidade - indica resultado da Verificação de Identidade;

  • Detecção de vida - indica resultado da Prova de vida.

Dados de navegação
  • Sistema operacional e navegador - indica os dados do dispositivo;

  • Endereço do IP - indica o IP do dispositivo.

Evidências de uso dos módulos nos flows iddocs, idsign e iddocssign

Quando o processo envolve os fluxos de IDDocs e Sign, o conjunto probatório também retorna dados desses fluxos como:

Documentos:

  • Tipo de documento - identifica o documento compartilhado pela pessoa. Ex: CNH / RG;

  • Modulo de coleta - caso Sim, identifica se houve a captura de um documento;

  • Documento validado - caso Sim, identifica que o documento compartilhado/reutilizado foi validado.

Assinatura:

  • Dados do Envelope - indica os documentos e seus assinantes;

  • ID do envelope - UUID que identifica o envelope no Unico Sign

Essas evidências podem ser utilizadas para garantir a autenticidade do processo.

O conjunto probatório só está disponível para os processos finalizados.


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.

Obter Documento Assinado

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


Introdução


Nesta seção, você encontrará a documentação detalhada sobre o funcionamento do endpoint de Obtenção do Documento Assinado no by Unico. Este endpoint fornecerá o documento assinado do usuário final em fluxos que possuem a capacidade Assinatura Eletrônica.

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://signhom.acesso.io;

  • Produção: https://sign.acesso.io.


Obtenção do Documento Assinado


Obter Documento Assinado

get

Endpoint para obter o documento assinado em PDF no by Unico. Somente para fluxos com assinatura eletrônica.

Autorizações
Parâmetros de rota
documentIdstringObrigatório

ID do documento.

Respostas
200
Documento assinado obtido com sucesso.
application/pdf
Respostastring · binary

Arquivo PDF gerado pelo sistema.

401
Erro no access-token.
application/json
500
Erro inesperado (Erro interno ou problema de parâmetro).
application/json
get
GET /api/v1/service/file/{documentId} HTTP/1.1
Host: signhom.acesso.io
Authorization: Bearer JWT
Accept: */*
binary

Exemplo de um documento gerado:

Caso o retorno do documento assinado via by Unico apresente atraso no processamento, recomendamos aguardar pelo menos um minuto após a conclusão do processo antes de realizar a consulta. Adicionalmente, é importante configurar uma política de tentativa automática (retry) para os casos em que o documento assinado ainda não esteja disponível, como realizar até 10 tentativas com intervalos de 1 a 5 minutos entre elas.

Para mais informações sobre os erros possíveis para este endpoint, consulte a seção Erros.


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.

Obter Conjunto Probatório do Documento Assinado

Nesta seção, você encontrará como obter o conjunto probatório do Sign de um processo no by Unico através da API REST


Introdução


Nesta seção, você encontrará a documentação detalhada sobre o funcionamento do endpoint de Obtenção do Conjunto Probatório do Documento Assinado no by Unico. Este endpoint fornecerá o conjunto probatório da assinatura do usuário final em fluxos que possuem a capacidade Assinatura Eletrônica.

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://signhom.acesso.io;

  • Produção: https://sign.acesso.io.


Obtenção do Conjunto Probatório do Documento Assinado


Obter Conjunto Probatório do Documento Assinado

get

Endpoint para obter o conjunto probatório da assinatura no by Unico. Somente para fluxos com assinatura eletrônica.

Autorizações
Parâmetros de rota
documentIdstringObrigatório

ID do documento.

Respostas
200
Conjunto probatório obtido com sucesso.
application/pdf
Respostastring · binary

Arquivo PDF gerado pelo sistema.

401
Erro no access-token.
application/json
500
Erro inesperado (Erro interno ou problema de parâmetro).
application/json
get
GET /api/v1/service/evidence/{documentId} HTTP/1.1
Host: signhom.acesso.io
Authorization: Bearer JWT
Accept: */*
binary

Exemplo de um documento gerado:

53KB
Conjunto Probatório do Documento Assinado.pdf
pdf

Para mais informações sobre os erros possíveis para este endpoint, consulte a seção Erros.


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.

Erros

Nesta seção, você encontrará a visão geral sobre os erros que pode receber nos endpoints da plataforma Unico IDCloud


Introdução


A plataforma IDCloud utiliza códigos de resposta HTTP convencionais para indicar o sucesso ou falha de uma solicitação de API.

Como regra geral:

  • Códigos no intervalo 2xx indicam sucesso na requisição;

  • Códigos no intervalo 4xx indicam parâmetros incorretos ou incompletos (por exemplo, um parâmetro obrigatório foi omitido ou uma operação falhou com terceiros, etc.);

  • Códigos no intervalo 5xx indicam que houve um erro nos servidores da plataforma Unico IDCloud.

A plataforma Unico IDCloud também gera uma mensagem de erro e um código de erro formatado em JSON:

{
    "error": {
        "code": "0000",
        "description": "error description"
    }
}

Erros possíveis


Neste tópico, você encontrará os possíveis erros dos endpoints, separados por seu HTTP response.

Criar Processo


code
message
Descrição

3

invalid flow

Quando o flow específicado não existe.

3

invalid person: friendly name exceeds 50 characters.

Quando o nome excede a quantidade máxima de 50 caracteres.

3

invalid purpose

Quando a proposta informada não é valida.

3

invalid callbackUri: unable to parse callbackUri: parse "": empty url, invalid callbackUri: url:

Quando o callbackUri informado não é válido.

3

invalid person: email required for notification channel NOTIFICATION_CHANNEL_EMAIL, invalid email address for notification channel NOTIFICATION_CHANNEL_EMAIL

Quando o e-mail informado não é válido, mas há a notificação via e-mail.

3

invalid person: phone number required for notification channel NOTIFICATION_CHANNEL_WHATSAPP, phone number does not contain 13 chars for notification channel NOTIFICATION_CHANNEL_WHATSAPP

Quando o telefone informado não é válido, mas há a notificação via SMS ou WhatsApp.

3

idnsv2/GetPublicID request error: rpc error: code = InvalidArgument desc = invalid dui value

Quando o CPF informado não é válido.

9

XX ID Apikeys are not set

Quando alguma API Key não foi configurada corretamente.

message
Descrição

Jwt header is an invalid JSON

Quando o access-token utilizado contém caracteres errados.

Jwt is expired

Quando o access-token utilizado expirou

Não será fornecido nenhum código de erro detalhado para esta situação, apenas o código de status HTTP.

code
message
Descrição

99999

Internal failure! Try again later

Quando há algum erro interno.

Consultar Resultado do Processo


code
message
Descrição

3

process id is invalid

Quando o id de processo é inválido.

message
Descrição

Jwt header is an invalid JSON

Quando o access-token utilizado contém caracteres errados.

Jwt is expired

Quando o access-token utilizado expirou

code
message
Descrição

5

error getting process: rpc error: code = NotFound desc = process not found

Quando o id do processo não foi encontrado

Não será fornecido nenhum código de erro detalhado para esta situação, apenas o código de status HTTP.

code
message
Descrição

99999

Internal failure! Try again later

Quando há algum erro interno.

Obter Selfie do Usuário


code
message
Descrição

3

process id is invalid

Quando o id de processo é inválido.

message
Descrição

Jwt header is an invalid JSON

Quando o access-token utilizado contém caracteres errados.

Jwt is expired

Quando o access-token utilizado expirou

code
message
Descrição

7

no permission

Quando a conta de serviço não possui a permissão para obter a selfie

code
message
Descrição

5

error getting process: rpc error: code = NotFound desc = process not found

Quando o id do processo não foi encontrado

Não será fornecido nenhum código de erro detalhado para esta situação, apenas o código de status HTTP.

code
message
Descrição

99999

Internal failure! Try again later

Quando há algum erro interno.

Obter Conjunto Probatório


code
message
Descrição

3

process id is invalid

Quando o id de processo é inválido.

message
Descrição

Jwt header is an invalid JSON

Quando o access-token utilizado contém caracteres errados.

Jwt is expired

Quando o access-token utilizado expirou

code
message
Descrição

7

no permission

Quando a conta de serviço não possui a permissão para obter a selfie

code
message
Descrição

5

error getting process: rpc error: code = NotFound desc = process not found

Quando o id do processo não foi encontrado

Não será fornecido nenhum código de erro detalhado para esta situação, apenas o código de status HTTP.

code
message
Descrição

99999

Internal failure! Try again later

Quando há algum erro interno.

Obter Documento Assinado


Não será fornecido nenhum código de erro detalhado para esta situação, apenas o código de status HTTP.

sucess
message
data
Descrição

false

Falha ao consultar o arquivo do documento.

Documento não existe.

O id do documento informado não existe

Obter Conjunto Probatório do Documento Assinado


Message
StatusCode
Errors

Not Found - Documento não existe

404

null

Não será fornecido nenhum código de erro detalhado para esta situação, apenas o código de status HTTP.

sucess
message
data
Descrição

false

Falha ao consultar o arquivo do documento.

Documento não existe.

O id do documento informado não existe


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.

Controlando a experiência

Nesta seção, você entrará os componentes de experiência que podem ser utilizados com o by Unico

Redirecionando o usuário

Nesta seção, você encontrará como informações redirecionar um usuário em suas aplicações na experiência do by Unico


O campo userRedirectUrl é usado para direcionar o usuário. Esse campo é recebido na resposta de sucesso da criação do processo ao realizar a requisição CreateProcess.

Aqui você encontrará as 3 formas de gerenciar a experiência do usuário em suas aplicações:

(1) Usando Redirect:

Recomenda-se seguir os seguintes passos:

  • Em seu fluxo comum (que está inserido o Cadastro by Unico) você irá redirecionar o cliente para o link gerado através da API;

  • Após isso o cliente de dentro da plataforma realiza os procedimentos necessários para continuar o fluxo;

  • Quando concluído, ele é redirecionado para a sua página (utilizando o redirectUrl passado na criação do processo).

(2) Usando window.open():

A opção window.open() consiste em abrir uma nova aba do navegador do usuário para que ele possa completar o processo. Ao final essa aba é fechada e redirecionada para sua aplicação.

Para isso é recomendado:

  • Seguir a documentação pública sobre isso, que se encontra aqui;

  • Monitorar se houve alteração de URL (para a redirectUrl) e então fechar a aba utilizando window.close().

Passo 1: Usando CustomTabs para integração

1 - Insira no app/build.gradle a dependência necessária para o uso de CustomTabs:

implementation("androidx.browser:browser:1.5.0")

Passo 2: Abrindo uma CustomTab

import android.net.Uri
import androidx.activity.ComponentActivity
import androidx.browser.customtabs.CustomTabsClient
import androidx.browser.customtabs.CustomTabsIntent

class CustomTabActivity : ComponentActivity() {
    override fun onCreate(savedInstanceState: Bundle?) {
       super.onCreate(savedInstanceState)

       openCustomTab(<URL_CBU>)
    }

    fun openCustomTab(url: String) {
        val builder = CustomTabsIntent.Builder()
        val customTabsIntent = builder.build()
        customTabsIntent.launchUrl(this, Uri.parse(url))
    }
}

Passo 3: Modificando AndroidManifest

Coloque no AndroidManifest.xml as permissões e intents necessários na Activity que deseja receber a callback_uri. É necessário incluir o atributo android:launchMode="singleTop" como também a tag <data> informando os dados da URI.

<uses-feature android:name="android.hardware.camera" android:required="false"/>
<uses-permission android:name="android.permission.CAMERA"/> 
// necessário ter as permissões de câmera e geolocalização 

<activity
    android:name=".CustomTabActivity"
    android:exported="true"
    android:label="@string/app_name"
    android:theme="@style/Theme.Customtabs"
    android:launchMode="singleTop">

    <intent-filter android:label="Custom Tab">
        <action android:name="android.intent.action.VIEW" />

        <category android:name="android.intent.category.DEFAULT" />
        <category android:name="android.intent.category.BROWSABLE" />

        <!-- scheme e host são os dados fornecidos na criação de um processo no campo callback_uri
        callback_uri: "foobar://success?code=1234" -->
        <data android:scheme="foobar" android:host="success"/>
    </intent-filter>

</activity>

As seguintes permissões são necessárias para funcionar corretamente:

  • Câmera;

  • Geolocalização.

Passo 4: Pegando informações de retorno

Para pegar as informações de redirect com os dados fornecidos, você pode usar o seguinte código no método onNewIntent da sua Activity:

override fun onNewIntent(intent: Intent) {
    super.onNewIntent(intent)

    val url = intent.data
    val scheme = url.scheme // "foobar"
    val host = url.host // "success"
    val code = url.getQueryParameter("code") // "1234"
}

Passo 1: Criar o controlador de autenticação

1 - O primeiro passo é criar o controlador de autenticação, e, para isso crie uma classe chamada UnicoAuthenticationController (ou como preferir chamar).

2 - Na sequência, importe o framework AuthenticationServices no topo da classe.

3 - Declare a classe como NSObject e implemente o protocolo ASWebAuthenticationPresentationContextProviding.

  • O resultado deve ser:

import AuthenticationServices

class UnicoAuthenticationController: NSObject, ASWebAuthenticationPresentationContextProviding {
    func presentationAnchor(for session: ASWebAuthenticationSession) -> ASPresentationAnchor {
           if let windowScene = UIApplication.shared.connectedScenes.first as? UIWindowScene {
               if let mainWindow = windowScene.windows.first {
                   return mainWindow
               }
           }
           return ASPresentationAnchor()
       }
}

Passo 2: Implementar a autenticação

1 - Abra o arquivo onde você executa a autenticação e adicione as importações necessárias (como exemplo, o ContentView.swift é usado).

import SwiftUI
import AuthenticationServices

2 - Para controlar o estado do fluxo é preciso criar a propriedade @State.

@State private var finished = false

3 - Crie uma instância da classe UnicoAuthenticationController fora do corpo da estrutura ContentView.

let unicoController = UnicoAuthenticationController()

4 - Para a validação do processo, crie uma função chamada redirectUser.

func redirectUser() {
        guard let url = URL(string: "URL_AUTHENTICATION") else { return }

        var session: ASWebAuthenticationSession?
        session = ASWebAuthenticationSession(url: url, callbackURLScheme: "BUNDLE") { callbackURL, error in
            guard callbackURL != nil else {
                if let error = error {
                    return print("Erro durante o processo: \(error.localizedDescription)")
                }
                return
            }

            // Processa o URL de callback para verificar se o processo foi finalizado
            session?.cancel()
            finished = true
        }

        session?.presentationContextProvider = unicoController
        session?.prefersEphemeralWebBrowserSession = true
        session?.start()
    }

Ambientes:

Lembre-se de alterar a url URL_AUTHENTICATION para a URL de autenticação recebida em seu processo e também o callbackURLScheme BUNDLE para o redirect informado na criação do processo (o uso do Bundle Identifier de seu aplicativo é recomendado).

Autenticação única:

É importante setar prefersEphemeralWebBrowserSession para true para garantir uma autenticação única por processo.

Também é possível utilizar o link gerado pelo by Unico em frameworks híbridos. Para isso, você pode criar uma bridge entre o framework utilizado com o nativo e seguir como sugerimos na documentação ou utilizar de alguma biblioteca que disponibilize essas opções de integração.

A integração da WebView na sua aplicação é de total responsabilidade do cliente, uma vez que esta funcionalidade não é oferecida como parte das bibliotecas ou SDKs da Unico. Por conta disso, não oferecemos suporte técnico para dúvidas ou problemas relacionados à implementação da WebView em seu aplicativo. Para obter orientações sobre a configuração, recomendamos consultar a documentação oficial da tecnologia utilizada em seu projeto (por exemplo, React Native, Flutter, etc).


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.

SDK

Nesta seção, você encontrará como implementar o SDK da Unico na sua aplicação web para uso do by Unico


O uso de integrações que não estejam em conformidade com os padrões estabelecidos nesta documentação pode resultar em interrupções inesperadas no funcionamento do sistema, as quais não serão cobertas ou suportadas pelo by Unico.

Ex: Implementar o SDK (iFrame) dentro de uma webview, implementar iFrame através de uma tag de HTML, etc.

Como começar


Para utilizar o by Unico por meio do SDK do by Unico, o primeiro passo é cadastrar os domínios, sempre utilizando o protocolo HTTPS, que serão utilizados como host para exibir o iFrame da jornada do usuário no by Unico.

Sinalize o responsável pelo seu projeto de integração ou o time de suporte da Unico para realizar essa configuração.

Para começar a usar o SDK, é necessário realizar a instalação do SDK Web da Unico. Vale destacar que o "by Unico" utiliza o mesmo SDK empregado no IDPay:

$ npm install idpay-b2b-sdk

Quando instalar o pacote do SDK da Unico, implemente sem especificar a versão que está utilizando e de modo que seu gerenciador de dependências atualize sempre os minors e patches para a versão mais recente.

Para verificar versões anteriores, acesse https://www.npmjs.com/package/idpay-b2b-sdk?activeTab=versions.

Métodos disponíveis:


1

init(options)

Esse método inicializa o SDK, fazendo um pré-carregamento de assets, criando a experiência mais fluida para o usuário final. Nesse momento é preciso enviar o token recebido como resultado do CreateProcess.

Parâmetros:

  • options - é um objeto com as seguintes propriedades de configuração:

    • type

      • O tipo de fluxo que será inicializado. No by Unico utilizamos a opção "IFRAME".

    • token

      • Recebe o token do processo criado. Esse token é importante para conseguirmos autenticar a jornada e garantir que somente domínios autorizados utilizem-na (pode ser obtido na criação do processo via API).

import { ByUnicoSDK } from “idpay-b2b-sdk”;

ByUnicoSDK.init({
  type: 'IFRAME',
  env: 'uat'// Só irá ser preenchido se for ambiente de testes.
  token,
});
2

open(options)

Esse método realiza a abertura da experiência do by Unico. Para o fluxo do tipo IFRAME, essa função exibe o iframe já pré-carregado, e inicia o fluxo de mensageria entre a página do cliente e a experiência do by Unico.

Parâmetros:

options - é um objeto com propriedades de configuração:

  • processId

    • Recebe o ID do processo criado. Esse ID é importante para conseguirmos obter os detalhes do processo e realizarmos todo o fluxo da maneira correta (pode ser obtido na criação do processo via API).

  • token

    • Recebe o token do processo criado. Esse token é importante para conseguirmos autenticar a jornada e garantir que somente domínios autorizados utilizem-na (pode ser obtido na criação do processo via API).

  • onFinish(process)

    • Recebe uma função de callback que será executada no término da jornada do by Unico, passando como argumento o objeto do processo com os seguintes dados: { captureConcluded, concluded, id }

const processId = '9bc22bac-1e64-49a5-94d6-9e4f8ec9a1bf';
const token = 'eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiaWF0IjoxNTE2MjM5MDIyfQ.SflKxwRJSMeKKF2QT4fwpMeJf36POk6yJV_adQssw5c';

const process = {
  id: '9bc22bac-1e64-49a5-94d6-9e4f8ec9a1bf',
  concluded: true,
  captureConcluded: true
};

const onFinishCallback = process => {
  console.log('Process', process);
}

ByUnicoSDK.open({
  transactionId: processId,
  token: token,
  onFinish: onFinishCallback
});

O diagrama de sequência abaixo demonstra como utilizar o SDK e o resultado da API do by Unico para configurar o iFrame:

Segurança​


Escolha pela Solução de Iframe com Auth Token em vez de CSP


​Após uma análise cuidadosa das necessidades e desafios que enfrentamos, decidimos adotar uma solução baseada em iframes com tokens de autenticação ao invés de implementar uma política de Content Security Policy (CSP). Essa escolha foi motivada por diversas considerações relacionadas à segurança e à flexibilidade necessárias para atender às demandas dos nossos clientes.

Contexto e Desafios com CSP


​O Content Security Policy (CSP) é uma ferramenta poderosa para proteger aplicações web contra diversos tipos de ataques, como Cross-Site Scripting (XSS) e injeção de código. No entanto, ao configurar uma política CSP, é necessário definir uma lista rígida de domínios confiáveis. Essa abordagem é eficaz quando os domínios são fixos e previsíveis. No entanto, para nossos clientes, que frequentemente utilizam domínios dinâmicos e variáveis, essa configuração rígida apresenta desafios significativos.

Vulnerabilidade com Domínios Dinâmicos


Os domínios dinâmicos representam um risco substancial para a segurança ao usar CSP. Quando um cliente possui domínios que mudam com frequência ou são criados dinamicamente, seria necessário atualizar constantemente a política CSP para incluir esses novos domínios. Isso não só aumenta o esforço de manutenção, mas também expõe os domínios aos quais a política CSP se aplica. Cada domínio adicionado à política CSP é potencialmente um ponto de vulnerabilidade se não for adequadamente gerenciado.

Solução com Iframe e Auth Token


Para mitigar esses riscos e atender à flexibilidade exigida pelos nossos clientes, optamos por utilizar iframes combinados com tokens de autenticação. Esta solução oferece uma camada adicional de segurança e evita a necessidade de expor ou gerenciar uma lista extensa e dinâmica de domínios.

Como funciona​


  • Autenticação Segura: Cada iframe é carregado com um token de autenticação exclusivo para cada transação, garantindo que apenas usuários autorizados possam acessar o conteúdo. Esse token é verificado em tempo real, proporcionando uma camada adicional de segurança e controle.

  • Isolamento de Conteúdo: O uso de iframes permite isolar o conteúdo em um contexto separado, reduzindo o risco de interferência entre diferentes origens e mitigando potenciais ataques.

  • Flexibilidade para Domínios Dinâmicos: Ao não depender de uma política CSP estática, nossa solução se adapta facilmente aos domínios dinâmicos dos clientes, sem a necessidade de atualização constante das políticas de segurança.


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.

QR Code

Nesta seção, você encontrará o funcionamento do fluxo com QR Code para experiências desktop


O by Unico disponibiliza a funcionalidade de QR code para facilitar o fluxo em dispositivos desktop. Através do QR code, é possível iniciar o By Unico em uma experiência web sem ter que se preocupar se o dispositivo do usuário possui câmera ou não. Dessa forma:

  • Diminuímos a chance de falha na captura biométrica;

  • Garantimos uma melhor experiência em outras capacidades;

  • Aumentamos as chances de conversão.

Solicite a ativação da funcionalidade para o responsável pelo seu projeto.

Como funciona?​


Quando o usuário inicia o By Unico através de um dispositivo desktop:

Identificamos que é um dispositivo desktop e oferecemos o QR code para possa continuar a jornada pelo celular:

Uma vez escaneado, o usuário segue sua jornada no celular normalmente, enquanto o dispositivo desktop aguarda sua conclusão:

O dispositivo desktop identifica que a jornada foi concluída no celular e redireciona o usuário para a experiência de origem:

Critérios de qualificação do dispositivo como desktop


  • Tamanho da tela: mínimo de 961px de largura;

  • Orientação da tela: paisagem;

  • User-Agent: não ser um dispositivo móvel.


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.

Personalizações

Nesta seção, você encontrará todas as personalizações disponíveis no by Unico


O by Unico oferece algumas opções de personalização em sua interface, permitindo que você a adapte à identidade visual da empresa e proporcione um visual personalizado da jornada.

Personalizações disponíveis:


Logotipo

Botões

Contextualização

Personalização do Logotipo


É possível personalizar o logotipo exibido aos usuários que acessam as jornadas do by Unico. Essa personalização reforça a parceria entre a empresa e a Unico, indicando que a verificação é realizada pela Unico a pedido do cliente ou parceiro.

Para solicitar a inclusão do logotipo, envie ao time da Unico uma URL onde o logotipo esteja hospedado em um diretório online (ou seja, o logotipo precisa ser acessível via URL no navegador).

  • Ex: https://storage.googleapis.com/portal-orca-unico-prod/apps/orca/logo-default.png.

Não é possível cadastrar uma URL que seja um base64 (geralmente essas URLs iniciam em "data:image/jpeg;base64,/9j/4AAQ...").

Personalização do logotipo
Grids de logotipo aceitos

Recomendações:

  • Envie o logotipo preferencialmente no formato de logo ícone, devido à sua melhor legibilidade em tamanhos reduzidos.

Regras:

  • Certifique-se de que o logotipo seja quadrado, respeite o grid proporcional e garanta que seja exportado com no mínimo 192x192 pixels.

  • Formatos aceitos: SVG, PNG e JPEG.

Formatos de logotipo não aceitos


Formato de logotipo não aceitos

Regras:

  • Priorize a aplicação do logotipo em planos de fundo que garantam a legibilidade.

  • Não utilize logotipos que não respeitem o grid quadrado.

  • Evite o uso de logotipos em baixa resolução.

  • Não aplique o logotipo em fundos transparentes.

Recomendações:

  • Priorize cores com contraste legível de no mínimo 4.5:1, seguindo os parâmetros de acessibilidade da WCAG.

    • Utilize o hexadecimal das cores para verificar a escala de contraste. Exemplo: Foreground ColorPicker: #000000, Background Color: #FFFFFF, Contrast Ratio: 21.00:1.

Personalização da cor e formato dos botões


Personalize os botões de ação do by Unico. Defina a cor do texto, fundo e arredondamento dos cantos do botão para reforçar a identidade visual da sua empresa.

Personalização do botão
Exemplos de contraste

Recomendações:

  • Escolha cores acessíveis: Ao personalizar as cores dos botões no by Unico, opte por um esquema de cores acessível, que garanta a visualização para todos os usuários, incluindo aqueles com deficiência visual.

  • Taxas de contraste: Busque uma taxa de contraste superior a 4.51:1 para obter os melhores resultados.

Cores acessíveis facilitam a navegação para todos, especialmente para pessoas com baixa visão. Utilize o hexadecimal das cores para verificar o contraste e siga as recomendações da WCAG.

  • Exemplo: #FFFFFF (texto) em #000000 (fundo) resulta em uma taxa de contraste de 21.00:1.

Arredondamento dos cantos no botão


Além das cores do texto e de fundo, você também pode definir o arredondamento dos cantos (border radius) em pixels, conforme a escala abaixo:

Arredondamento dos cantos no botão

Configurações de personalização


Para realizar as configurações da identidade visual do cliente ou parceiro para o botão, compartilhe com o time de implantação da Unico as seguintes informações:

  • Código hexadecimal da cor de background no botão.

    • Ex: #000000.

  • Código hexadecimal da cor de texto no botão.

    • Ex: #ffffff.

  • Arredondamento dos cantos no botão em pixels.

    • Ex: 10px.

Personalização da tela de contextualização


O módulo de contextualização do by Unico permite que o cliente ou parceiro forneça informações sobre a verificação, como empresa solicitante, motivo e valor da operação, tornando o processo mais seguro

Tela de contextualização no by Unico

Para personalizar as informações na tela de contextualização, altere os valores dos parâmetros contidos no objeto contextualization no momento de realizar a chamada CreateProcess.

O trecho da requisição a ser alterado é o seguinte:

"contextualization": {
    "currency": "BRL",
    "price": "<FLOAT_NUMBER>",
    "locale": {
      "ptBr": {
        "reason": "<REASON_PTBR>"
      },
      "enUs": {
        "reason": "<REASON_ENUS>"
      },
      "esMX": {
        "reason": "<REASON_ESMX>"
      }

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 Unico

Postman Collection

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


132KB
Plataforma Unico.postman_collection.json

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.

PoCs disponíveis

Nesta seção, você encontrará a lista de todas as PoCs do by Unico disponíveis para apoiar a sua implementação.


Os seguintes exemplos de projetos são disponibilizados para facilitar o entendimento do funcionamento do by Unico.

Caso não encontre a POC nesta seção, solicite a POC ao seu Gerente de Projetos e ela será compartilhada através de um diretório SFTP.

PoCs em ambiente nativo


Linguagem de programação
Descrição
Repositório

Swift

PoC em Swift que implementa o by Unico na WebView em iOS

GitHub

Kotlin

PoC em Kotlin que implementa o by Unico na WebView em Android

GitHub

Nosso suporte é restrito a aplicativos desenvolvidos diretamente nas plataformas nativas Android e iOS, utilizando seus respectivos módulos nativos, além do framework Flutter (se a implementação for utilizando nosso plugin). No momento, não oferecemos suporte para aplicativos desenvolvidos em frameworks híbridos, como React Native, Ionic ou outras tecnologias de desenvolvimento multiplataforma.

PoCs em ambiente web


Linguagem de programação
Descrição
Repositório

Angular

PoC em Angular que implementa o by Unico através do SDK da Unico

GitHub

React

PoC em React que implementa o by Unico através do SDK da Unico

GitHub

JavaScript

PoC em JavaScript que implementa o by Unico através do SDK da Unico

GitHub

Vue JS

PoC em Vue JS que implementa o by Unico através do SDK da Unico

GitHub

NextsJS

PoC em NextsJS que implementa o by Unico através do SDK da Unico

GitHub


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.