Criar Processo

Este é o ponto de entrada de toda integração Web & SDK. Seu back-end o chama para criar um processo; seu front-end usa os tokens retornados para renderizar o iFrame, redirecionar o usuário ou inicializar um SDK nativo.

Para o fluxo completo de integração, consulte Visão geral de Web & SDK.

Endpoint

Ambiente	URL
Produção	POST https://api.idcloud.unico.app/client/v1/process
Sandbox	POST https://api.idcloud.uat.unico.app/client/v1/process

Requisição

Headers

Header	Valor
Authorization	Bearer <access_token> (consulte Autenticação)
Content-Type	application/json

Parâmetros do corpo

Campo	Tipo	Obrigatório	Descrição
callbackUri	string	sim	URL para a qual o usuário é redirecionado após o término da jornada. Use / para fluxos de SDK nativo em que o callback é tratado dentro do app.
flow	string	sim	Identificador do fluxo — determina quais capacidades serão executadas. Exemplos: idunicodocs, idunicosign, idchecktrust, idtoken, idsmart. Consulte Fluxos disponíveis.
purpose	string	sim	Finalidade de negócio. Valores aceitos: creditprocess, biometryonboarding, carpurchase, ageverification.
person.duiType	enum	sim	Tipo de documento. Valores aceitos: DUI_TYPE_BR_CPF, DUI_TYPE_MX_CURP, DUI_TYPE_US_SSN, DUI_TYPE_BR_PASSPORT, DUI_TYPE_AR_PASSPORT, DUI_TYPE_AR_DNI, DUI_TYPE_NG_NIN, DUI_TYPE_CL_RUN, DUI_TYPE_EC_NI, DUI_TYPE_US_PASSPORT, DUI_TYPE_GT_CUI, DUI_TYPE_UY_CI, DUI_TYPE_ZZ_EMAIL, DUI_TYPE_ID_NIK, DUI_TYPE_ZZ_PHONE_NUMBER, DUI_TYPE_US_DRIVER_LICENSE, DUI_TYPE_NG_BVN.
person.duiValue	string	sim	Número do documento, sem formatação.
person.friendlyName	string	não	Nome de exibição do usuário mostrado na interface da jornada. Máximo de 50 caracteres.
person.phone	string	não	Número de telefone no formato DDI + DDD + número, sem separadores. Obrigatório ao enviar notificações via SMS ou WhatsApp.
person.email	string	não	Endereço de e-mail. Obrigatório para fluxos com Assinatura Eletrônica.
person.notifications	array	não	Canais de notificação para envio do link da jornada. Cada item possui notificationChannel: NOTIFICATION_CHANNEL_WHATSAPP, NOTIFICATION_CHANNEL_SMS ou NOTIFICATION_CHANNEL_EMAIL.
bioTokenId	string (UUID)	condicional	Descontinuado. Use references no lugar. ID do processo biométrico de referência. Obrigatório para fluxos de validação 1:1 (idtoken, idtokentrust, idtokensign) e Smart Revalidation (idsmart).
references	array	condicional	Entradas de referência para fluxos de validação 1:1 e Smart Revalidation, substituindo bioTokenId. Cada item contém referenceType (REFERENCE_TYPE_IMAGE_BASE64 ou REFERENCE_TYPE_PROCESS_ID) e referenceContent (imagem em base64 ou UUID do processo).
useCase	string	condicional	Caso de uso de Smart Revalidation. Obrigatório para idsmart. Exemplos: USE_CASE_LOGIN, USE_CASE_IDENTITY_REVALIDATION_7_DAYS, USE_CASE_FIN_TRANSACTIONS.
clientReference	string	não	Seu identificador interno para este processo (chave estrangeira para referência cruzada no portal).
companyBranchId	string (UUID)	não	ID da filial. Obrigatório somente se a conta de serviço tiver mais de uma filial associada.
expiresIn	string	não	Janela de validade do processo a partir da criação. Formato: "3600s". Padrão de 7 dias se omitido.
flow_config	object	não	Configurações específicas por fluxo.
flow_config.biometry_capture.enabled_back_camera	boolean	não	Usar a câmera traseira do dispositivo. Não compatível com fluxos de captura de documento ou Assinatura Eletrônica.
contextualization	object	não	Contexto da transação exibido ao usuário durante a jornada para explicar a captura.
contextualization.currency	string	não	Código de moeda exibido ao usuário. Valores aceitos: BRL, MXN, USD.
contextualization.price	number	não	Valor da transação exibido ao usuário.
contextualization.locale	object	não	Texto de motivo localizado. Chaves: ptBr, enUs, esMx — cada uma com uma string reason exibida durante a jornada.

Exemplo

cURL

curl -X POST https://api.idcloud.unico.app/client/v1/process \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "callbackUri": "https://app.client.com/callback",
    "flow": "idunicodocs",
    "purpose": "biometryonboarding",
    "person": {
      "duiType": "DUI_TYPE_BR_CPF",
      "duiValue": "12345678909",
      "friendlyName": "Luke Skywalker",
      "phone": "5511912345678",
      "email": "[email protected]"
    }
  }'

Node.js

import fetch from 'node-fetch';

const res = await fetch('https://api.idcloud.unico.app/client/v1/process', {
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${process.env.UNICO_ACCESS_TOKEN}`,
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    callbackUri: 'https://app.client.com/callback',
    flow: 'idunicodocs',
    purpose: 'biometryonboarding',
    person: {
      duiType: 'DUI_TYPE_BR_CPF',
      duiValue: '12345678909',
      friendlyName: 'Luke Skywalker',
      phone: '5511912345678',
      email: '[email protected]'
    }
  })
});

const { process: proc } = await res.json();
// proc.userRedirectUrl, proc.token, proc.webAppToken

Respostas

200 OK

{
  "process": {
    "id": "53060f52-f146-4c12-a234-5bb5031f6f5b",
    "state": "PROCESS_STATE_CREATED",
    "flow": "idunicosign",
    "purpose": "biometryonboarding",
    "callbackUri": "https://app.client.com/callback",
    "clientReference": "your-internal-id-123",
    "companyBranchId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "userRedirectUrl": "https://cadastro.unico.app/process/53060f52-f146-4c12-a234-5bb5031f6f5b",
    "token": "eyJhbGciOiJSUzI1NiIs...",
    "webAppToken": "eyJhbGciOiJSUzI1NiIs...",
    "createdAt": "2023-10-09T09:15:25.417105Z",
    "expiresAt": "2023-10-09T16:15:25.417105Z",
    "capacities": [],
    "authenticationInfo": {},
    "person": {
      "duiType": "DUI_TYPE_BR_CPF",
      "duiValue": "12345678909",
      "friendlyName": "Luke Skywalker",
      "phone": "5511912345678",
      "email": "[email protected]",
      "notifications": []
    },
    "companyData": {
      "branchId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
      "countryCode": "BR"
    }
  }
}

Campo	Tipo	Descrição
process.id	string (UUID)	Identificador do processo. Use-o para buscar o resultado via Obter Processo.
process.state	enum	PROCESS_STATE_CREATED — processo criado, jornada ainda não iniciada. PROCESS_STATE_FAILED — falha na criação do processo.
process.flow	string	Identificador do fluxo enviado na criação.
process.purpose	string	Finalidade de negócio enviada na criação.
process.callbackUri	string	URI de callback enviada na criação.
process.clientReference	string	Seu identificador interno enviado na criação. Presente apenas se fornecido na requisição.
process.companyBranchId	string (UUID)	ID da filial. Presente apenas se fornecido na requisição.
process.userRedirectUrl	string	URL para redirecionar o usuário (integrações via Web Redirect e iFrame). Não modifique esta URL.
process.token	string	JWT para inicializar o iFrame do Web SDK.
process.webAppToken	string	JWT para inicializar SDKs nativos (Android, iOS, Flutter).
process.createdAt	string (date-time)	Timestamp de quando o processo foi criado.
process.expiresAt	string (date-time)	Timestamp após o qual o processo expira e não pode mais ser concluído.
process.capacities	array	Capacidades configuradas para este processo.
process.authenticationInfo	object	Informações de autenticação do processo (vazio no momento da criação).
process.person	object	Espelho do objeto person enviado na criação.
process.companyData.branchId	string (UUID)	ID da filial associada ao processo.
process.companyData.countryCode	string	Código do país associado à filial (ex.: BR, MX).

400 Bad Request

Retornado quando o payload da requisição está malformado, campos obrigatórios estão ausentes ou o valor de flow é desconhecido.

401 Unauthorized

Token Bearer ausente, expirado ou inválido. Consulte Autenticação.

429 Too Many Requests

Limite de requisições atingido. Tente novamente após o intervalo indicado nos cabeçalhos da resposta.

Códigos de Erro

400 Bad Request

Código	Mensagem	Descrição
3	invalid flow	Quando o fluxo especificado não existe.
3	invalid person: friendly name exceeds 50 characters.	Quando o nome de exibição ultrapassa 50 caracteres.
3	invalid purpose	Quando a finalidade fornecida é inválida.
3	invalid callbackUri: unable to parse callbackUri: parse "": empty url, invalid callbackUri: url:	Quando a callbackUri fornecida é inválida.
3	invalid person: email required for notification channel NOTIFICATION_CHANNEL_EMAIL, invalid email address for notification channel NOTIFICATION_CHANNEL_EMAIL	Quando o e-mail fornecido é inválido e a notificação por e-mail está configurada.
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 número de telefone fornecido é inválido e a notificação por SMS ou WhatsApp está configurada.
3	idnsv2/GetPublicID request error: rpc error: code = InvalidArgument desc = invalid dui value	Quando o identificador fornecido (duiValue) é inválido.
3	invalid expiresIn argument	Quando o valor de expiresIn é inválido.
9	XX ID Apikeys are not set	Quando a API Key não está configurada corretamente.

401 Unauthorized

Mensagem	Descrição
Jwt header is an invalid JSON	Quando o token de acesso utilizado contém caracteres incorretos.
Jwt is expired	Quando o token de acesso utilizado expirou.

429 Too Many Requests

Nenhum código de erro detalhado é fornecido para este status — apenas o status HTTP.

500 Internal Server Error

Código	Mensagem	Descrição
99999	Internal failure! Try again later	Quando ocorre um erro interno.

Próximos passos

• Após o usuário concluir a jornada, chame Obter Processo para buscar o resultado ou aguarde o webhook.