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, veja Visão Geral 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> (veja 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 onde o callback é tratado no app.
flow	string	sim	Identificador do fluxo — determina quais capacidades são executadas. Exemplos: idunicodocs, idunicosign, idchecktrust, idtoken, idsmart. Veja 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, DUI_TYPE_MX_RFC_PERSONA_FISICA, DUI_TYPE_CO_NIT, DUI_TYPE_PE_RUC, DUI_TYPE_CA_SIN, DUI_TYPE_DK_CPR, DUI_TYPE_GB_NINO, DUI_TYPE_PL_PESEL, DUI_TYPE_SE_PNR, DUI_TYPE_AT_STNR, DUI_TYPE_FI_HETU.
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 em vez disso. ID do processo biométrico de referência. Obrigatório para fluxos de Validação 1:1 (idtoken, idtokentrust, idtokensign) e Revalidação Inteligente (idsmart).
references	array	condicional	Entradas de referência para fluxos de Validação 1:1 e Revalidação Inteligente, substituindo bioTokenId. Cada item contém referenceType (REFERENCE_TYPE_IMAGE_BASE64 ou REFERENCE_TYPE_PROCESS_ID) e referenceContent (imagem codificada em base64 ou UUID de processo).
useCase	string	condicional	Caso de uso de Revalidação Inteligente. 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 apenas 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	Substituições de configuração por fluxo.
flow_config.biometry_capture.enabled_back_camera	boolean	não	Usar a câmera traseira do dispositivo. Não compatível com captura de documento ou fluxos de Assinatura Eletrônica.
contextualization	object	não	Contexto da transação exibido ao usuário durante a jornada para explicar a captura.
contextualization.company_name	string	não	Nome da empresa exibido durante a jornada. Máximo de 20 caracteres.
contextualization.currency	string	não	Código da 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 localizado exibido durante a jornada. Chaves: ptBr, enUs, esMx.
contextualization.locale.{ptBr|enUs|esMx}.reason	string	não	Motivo resumido da captura, exibido durante a jornada. Máximo de 50 caracteres.
contextualization.locale.{ptBr|enUs|esMx}.title	string	não	Título do aviso ao cliente exibido durante a jornada. Máximo de 100 caracteres. Deve ser fornecido junto com text. Tags HTML são removidas.
contextualization.locale.{ptBr|enUs|esMx}.text	string	não	Corpo do aviso ao cliente exibido durante a jornada. Máximo de 210 caracteres. Deve ser fornecido junto com title. Tags HTML são removidas.

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 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 (vazias no momento da criação).
process.person	object	Eco 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

Bearer token ausente, expirado ou inválido. Veja Autenticação.

429 Too Many Requests

Limite de requisições atingido. Quando seu sistema recebe um erro HTTP 429, você deve implementar mecanismos para prevenir falhas em cascata e evitar agravar a restrição.

Boas práticas:

• Período de espera (backoff): Interrompa ou limite imediatamente as requisições subsequentes do seu sistema. Não tente reenviar requisições falhas continuamente em um loop apertado.
• Enfileiramento e controle de fluxo: Armazene ou enfileire as requisições de saída do seu lado para controlar o fluxo de tráfego antes de reenviá-las.
• Backoff exponencial com jitter: Ao tentar novamente, aumente o tempo de espera exponencialmente entre as tentativas (ex.: 1 s, 2 s, 4 s, 8 s) e adicione um pequeno atraso aleatório ("jitter") para evitar um efeito manada onde todas as requisições enfileiradas tentam novamente no exato mesmo milissegundo.

aviso

Continuar acessando um endpoint com limite de taxa sem aplicar backoff pode prolongar o período de restrição e impactar severamente a taxa de transferência operacional do seu sistema. Controlar adequadamente as requisições do seu lado garante uma integração mais suave e resiliente.

Para limites padrão, aumento de requisições e detalhes adicionais, veja Limites de Taxa.

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 amigável excede 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.
3	invalid company_name argument in process contextualization, max length is 20	Quando contextualization.company_name excede 20 caracteres.
3	title and text must be provided together in process contexts	Quando apenas um de title ou text é fornecido em um locale.
3	invalid title argument in process contexts, max length is 100	Quando o title de um locale excede 100 caracteres.
3	invalid text argument in process contexts, max length is 210	Quando o text de um locale excede 210 caracteres.
3	invalid reason argument in process contexts, max length is 50	Quando o reason de um locale excede 50 caracteres.
9	XX ID Apikeys are not set	Quando a API Key não está devidamente configurada.

401 Unauthorized

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

429 Too Many Requests

Nenhum código de erro detalhado é fornecido para este status — apenas o status HTTP. Consulte a seção 429 Too Many Requests acima para boas práticas.

500 Internal Server Error

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

Próximos passos

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