Create Process

Este artigo explica como criar um processo no By Unico através da API REST.

Como usar?

Faça uma requisição POST para o endpoint:

• Homologação: https://api.cadastro.uat.unico.app/client/v1/process
• Produção: https://api.cadastro.unico.app/client/v1/process

Com o token de acesso válido, faça uma requisição para o endpoint enviando os seguintes parâmetros:

{
  "callbackUri": "/path/to/url",
  "flow": "<FLOW_TYPE>",
  "person": {
    "duiType": "<DUI_TYPE>",
    "duiValue": "<DUI_VALUE>",
    "friendlyName": "<USER_FRIENDLY_NAME>",
    "phone": "<USER_PHONE_NUMBER>",
    "email": "<USER_EMAIL>",
    "notifications": [
      {
        "notificationChannel": "NOTIFICATION_CHANNEL_WHATSAPP"
      },
      {
        "notificationChannel": "NOTIFICATION_CHANNEL_SMS"
      }
    ],
  },
  "purpose": "<DATA_COLLECT_PURPOSE>",
  "payload": [],
  "expiresIn": "<EXPIRES_IN>",
  "contextualization": {
    "currency": "BRL",
    "price": "<FLOAT_NUMBER>",
    "locale": {
      "ptBr": {
        "reason": "<REASON_PTBR>"
      },
      "enUs": {
        "reason": "<REASON_ENUS>"
      },
      "esMX": {
        "reason": "<REASON_ESMX>"
      }
    }
  }
}

Parâmetros de requisição

Nome	Tipo	Mandatorio/Opcional	Descrição
flow	String	Mandatório	Define a jornada que a ser executada. idlive: Fluxo com prova de vida, sem validação de identidade. id: Fluxo de validação de identidade com biometria facial. idcheck: Fluxo de validação de identidade com biometria facial com score no caso de inclonclusivo. iddocs: Fluxo de validação de identidade com captura e reaproveitamento de documentos (RG ou CNH). idsign: Fluxo de validação de identidade com assinatura eletrônica. iddocssign: Fluxo de validação de identidade, captura/reaproveitamento de documentos (RG ou CNH) e assinatura eletrônica. idtoken: Fluxo para verificar a autenticidade de uma biometria facial em relação a um processo já realizado anteriormente. idcheckserpro: Fluxo de consulta no SERPRO e validação de identidade com biometria facial e score no caso de inconclusivo.

| callbackUri | String | Mandatório | Define para onde o usuário será redirecionado ao fim do processo.

URL: Você pode utilizar uma URL para uma página web de seu fluxo. Exemplo: https://developers.unico.io/callback. Você pode personalizar como desejar.

URL Scheme: Você também pode realizar o redirecionamento para aplicações móveis nativas. Exemplo: br.com.meupacote.app://callback. Esse callback precisa estar registrado em sua aplicação móvel.

Sem redirecionamento: Caso você esteja usando a solução em um fluxo de mensagem, utilize o valor / para evitar um redirecionamento ao final do fluxo. | | person.personDuiType | String | Mandatório | Define o tipo de identificador do usuário.

DUI_TYPE_BR_CPF: Para utilizar CPF como identificador. | | person.personDuiValue | String | Mandatório | Define o valor do identificador do usuário especificado no campo personDuiType.

Exemplo: No caso de uso do identificador DUI_TYPE_BR_CPF para CPF utilize um CPF válido sem formatação: 73689290074.

Nota: Obrigatório nos fluxos de SMS e WhatsAPP. | | person.friendlyName | String | Opcional | Define o nome do usuário. Ex.: John Doe. | | person.phone | String | Opcional(*) | Define o telefone do usuário. Ex.: 551190000-0000| | person.email | String | Opcional | Define o email do usuário. | | notifications.notificationChannel | String | Opcional | notifications:É um array que define o canal de envio das notificações. O campo deve ser preenchido com as notificações desejadas: SMS, ou WhatsApp, ou os dois canais.

Exemplo de uso:

notificationChannel": NOTIFICATION_CHANNEL_SMS

notificationChannel: NOTIFICATION_CHANNEL_WHATSAPP

Não enviar campos de notifications em caso de recebimento de URL apenas.| | purpose | String | Mandatório | Define o propósito de uso e coleta de dados do usuário. Tem como objetivo dar transparência e garantir o tratamento de dados correto pela LGPD.

creditprocess: Caso você esteja utilizando a solução para oferecer um crédito ao usuário.

biometryonboarding: Caso você esteja utilizando a solução para realizar onboarding do usuário.

carpurchase: Caso você esteja utilizando a solução para realizar commpra de um veículo. | | bioTokenId | String | Opcional() | Define o Id da transação que deseja comparar com a validação do fluxo idtoken.

O valor desse campo pode ser o valor do campo id ou authenticationInfo.authenticationId do processo retornado ao realizar o GetProcess de um processo idcheck. | | payload | Array | Mandatório | O campo payload é um Array que oferece um local para inserção de arquivos necessários para alguns fluxos específicos, como por exemplo idsign.

Dentro do Array payload outro Array pode ser utilizado para criação de envelopes de fluxo de assinatura.

O campo documents é um Array recebe o documentos que compoem cada envelope, podendo ser 1 ou mais.

Cada Objeto document possui:
- documentName: Nome do documento.
- fileContents: Base64 do PDF a ser assinado.

Esse campo é obrigatório para integração com o IDSign. | | expiresIn | String | Opcional | Esse campo define o tempo em segundos para a expiração do processo, baseado na data do created_at. Por exemplo, para a expiração ocorrer daqui 24 horas é necessário informar como "expires_in": "86400s". Caso essa informação não seja informada, será usado o valor default de 7 dias. É possível personalizar essa informação, para isso entre em contato com o time de onboarding. | | contextualization.price | float | Opcional | Esse campo define o valor que será exibido na contextualização do processo. | | contextualization.currency | String | Opcional(*) | Esse campo define a moeda que será usada para formatação do campo price. | | contextualization.locale.ptBr.Reason | String | Opcional | Esse campo define a informação que será exibida no campo de Motivo do processo quando for selecionado a linguagem pt-br. | | contextualization.locale.enUs.Reason | String | Opcional | Esse campo define a informação que será exibida no campo de Motivo do processo quando for selecionado a linguagem en-us. | | contextualization.locale.esMx.Reason | String | Opcional | Esse campo define a informação que será exibida no campo de Motivo do processo quando for selecionado a linguagem es-mx. | | companyBranchId | String | Opcional | Esse campo define o id da filial o qual o processo criado é relacionado |

Nota

(*) O parâmetro person.phone se torna mandatório quando o campo notifications.notificationChannel for preenchido.

(**) O parâmetro bioTokenId se torna mandatório quando o campo flow for do tipo idtoken. A criação do fluxo idtoken só é possível após a finalização com sucesso de um fluxo idcheck .

(***) O parâmetro contextualization.currency se torna mandatório quando o campo contextualization.price for preenchido. Exemplo de como ficará a interface do usuário com a contextualização:

Importante

Para o fluxo idtoken o cpf somente é validado se o valor informado for o campo id do processo, caso o valor passado no campo idtoken seja authenticationInfo.authenticationId o cpf não será garantido.

Criação de processo com filial

Para a criação de processos com uma conta de serviço que possui permissão apenas para uma filial, não é necessário informar o campo companyBranchId.

Para conta de serviço que possui permissão para mais de uma filial, é necessário informar o campo companyBranchId com o valor do id da filial desejada.

Exemplo de requisição

{
  "callbackUri": "/path/to/url",
  "flow": "idsign",
  "person": {
    "duiType": "DUI_TYPE_BR_CPF",
    "duiValue": "73689290074",
    "friendlyName": "John Doe",
    "notifications": [
      {
        "notificationChannel": "NOTIFICATION_CHANNEL_WHATSAPP"
      },
      {
        "notificationChannel": "NOTIFICATION_CHANNEL_SMS"
      }
    ],
  },
  "purpose": "creditprocess",
  "payload": [
    {
      "envelopePayload": {
        "documents": [
          {
            "documentName": "teste",
            "fileContents": "JVBERi0xLjMNCiXi48/[...]DQoNCnN0YXJ0eHJlZg0KMjcxNA0KJSVFT0YNCg=="
          }
        ]
      }
    }
  ],
  "companyBranchId": "9ea8e39a-188a-4295-b5d7-3dd8791ab199",
  "expiresIn": "86400s",
  "contextualization": {
    "currency": "BRL",
    "price": 15990.9,
    "locale": {
      "ptBr": {
        "reason": "Validação de identidade"
      },
      "enUs": {
        "reason": "Identity validation"
      }
    }
  }
}

Para mais exemplos, consulte Exemplos de Request

Formas de fazer uma rquisição (request)

cURL

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"
}'

Postman

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"
}

NodeJS

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);
  });

Java

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();
        }
    }
}

C#

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);
        }
    }
}

Go

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)
    }
}

Requisição executada com sucesso

Se a requisição foi executada com sucesso, a resposta de retorno é um 200 OK e um JSON contendo os seguintes parâmetros:

{
  "process": {
      "id": "057f8d90-6ff6-4f52-ba05-ead6123f73bd",
      "flow": "idcheck",
      "callbackUri": "https://unico.io",
      "userRedirectUrl": "https://cadastro.dev.unico.app/process/6291d10b-0450-453e-a5e8-5a6b2fe060e0",
      "state": "PROCESS_STATE_CREATED",
      "createdAt": "2024-07-18T18:34:30.328743Z",
      "expiresAt": "2024-07-25T18:34:30.328743Z",
      "person": {
        "duiType": "DUI_TYPE_BR_CPF",
        "duiValue": "73689290074",
        "friendlyName": "John Doe"
      },
      "purpose": "creditprocess",
      "authenticationInfo": {},
      "capacities": [
        "PROCESS_CAPACITY_IDLIVE",
        "PROCESS_CAPACITY_IDUNICO",
        "PROCESS_CAPACITY_IDCHECK"
      ],
      "token": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9.eyJhdWQiOiI3YzE1MDE3Yi0zYzlmLTQ1ZTktOTgzMy01M2ZjYzgyMjQ3YTgiLCJjbGlkIjoiNTdjMDlkMmYtMTAzOC00OGU0LWFiYTMtODhjOWIxYjdjY2JjIiwiZXhwIjoxNzI4NDE2NjYwLCJleHRyYSQiOnsiY29uZmlncyI6eyJzaWxlbnRTdGFydCI6ZmFsc2V9LCJkb21haW5zIjpudWxsLCJwcm9jZXNzUGF0aCI6Ii9wcm9jZXNzL2JiNjNlMTVlLWExYWEtNDY2YS1iMzQ2LTgwOTVlMmE4YjIyNCJ9LCJpYXQiOjE3MjgzMzAyNjAsImlzcyI6Imh0dHBzOi8vY2FkYXN0cm8udWF0LnVuaWNvLmFwcC8iLCJqdGkiOiJiYjYzZTE1ZS1hMWFhLTQ2NmEtYjM0Ni04MDk1ZTJhOGIyMjQiLCJuYmYiOjE3MjgzMzAyNjAsInNjb3BlIjoiKiIsInN1YiI6ImM4MmU5Y2Y1LWE1ZmQtNDVmMy1hMTNiLTRiYzgxNGVkZDU2NCIsInZlcnNpb24iOiIxLjAifQ.r2Id5aaLUGvmUS-2WbHsYCKqUBZj-icOK_79-xRBeaz0F10I5-UTYEtFKrhJQM3CIybGkfRcKub6leevIGIoslC8EMVLl-DIXd9ofyzC3r1lh9KQ-VQqA4vJivMqH3HZyoKjCoMsXSKWu0SfMeRzz5p4U6I98KXj0TpIfiU0gMYXT8OlhXszscR1vlCSlZoxr1EhwJSa_gDjASlNey75fKMY9qPa61_MGnxDlQyAomqNCZi4txNHSkTWl8P9YpQQ7AXhCV8__zyMWkCgz5T30P46ybPMaAsX0Mit5eHEedtY7ucfxhA7K5uAc1k8_wtpj1UUy02JIIA0Xi28Jou8KhrC7NUbXgR-0d-5vCYHcgkPgPkp4acLSB6g6tUxafMMuKVBnL3tPkQCSO9X_gFYVaRuBn5oS6LBiWQew-gYJ0Ry0ck3P1o15K_I2nDGI4-FFvpClrPncYK4zhAOiAUcaC4c2JtPaWl9p9O4PoZGv2iTMcyOBE_ZpwDww8VMDWutgj983OGnY91EzCsr84DAZO6ieTz79bC6IcqajBZi7IA_ZGUxr4DbnMtDJTBJuCthGfn_e4-9I7XbIecQKmKkbOXVvLVGY4ob2mGRva6sl5y_wZRVgpij1AhPqoG1A-SDlmy2_KPnNxPhG90O5uD6Wqas9J7K4jmfnniaQ7d_jhQ"
  }
}

Os Parâmetros de retorno são:

Nome	Descrição
id	O identificador do processo.
flow	Define a jornada que foi criada. id: Fluxo de validação de identidade com biometria facial. idcheck: Fluxo de validação de identidade com biometria facial com score no caso de inclonclusivo. iddocs: Fluxo de validação de identidade com captura e reaproveitamento de documentos (RG ou CNH). idsign: Fluxo de validação de identidade com assinatura eletrônica. iddocssign: Fluxo de validação de identidade, captura/reaproveitamento de documentos (RG ou CNH) e assinatura eletrônica. idtoken: Fluxo para verificar a autenticidade de uma biometria facial em relação a um processo já realizado anteriormente.
callbackUri	Define para onde o usuário será redirecionado no fim do processo. Mais detalhes em Parametros de requisição.
userRedirectUrl	URL para onde você deverá redirecionar o usuário para finalização da jornada
state	Sinaliza o estado atual do processo, por ser do tipo: PROCESS_STATE_CREATED: Processo criado e ainda não finalizado pelo usuário. PROCESS_STATE_FINISHED: Processo finalizado pelo usuário com sucesso. PROCESS_STATE_FAILED: Processo criado ou finalizado com erro.
result	Sinaliza o resultado do processo da jornada do usuário, podendo ser do tipo: PROCESS_RESULT_OK: Processo finalizado com sucesso. PROCESS_RESULT_WARNING: Processo finalizado com alerta. PROCESS_RESULT_ERROR: Processo finalizado com algum tipo de erro. PROCESS_RESULT_UNSPECIFIED: É retornado quando o cliente utiliza o IDUnico sozinho. Processo finalizado com resultado não especificado.
person.personDuiType	Define o tipo de identificador do usuário. DUI_TYPE_BR_CPF: Para CPF como identificador.
person.personDuiValue	Define o valor do identificador do usuário especificado no campo personDuiType.
person.friendlyName	Define o nome do usuário, por exemplo, Fulano.
createdAt	Sinaliza o momento em que o processo foi criado.
expiresAt	Sinaliza o momento em que o processo será/foi expirado, o valor desse campo é calculado a partir do campo expires_in informado na criação do processo com a data de criação do process, created_at.
token	Token assinado que contém os parâmetros necessários para inicializar o SDK web do by Unico, permitindo integração via iFrame

Erro na Requisição

Para infomações sobre os erros retornados, consulte a lista disponível no artigo Response Errors.

API Reference

Para mais informações sobre este endpoint, consulte a API Reference.

Exemplo de contextualização na interface

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.