Criar Processo

MarkdownChatGPTClaude

Este é o ponto de entrada de toda integração com a Unico API. 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 de integração completo, veja Fluxos.

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 body

Os requisitos de campo dependem do fluxo

Se um campo é obrigatório, opcional ou não aplicável depende do flow que você está integrando — consulte Fluxos para a receita específica que você está usando antes de assumir o requisito de um campo apenas por esta tabela.

Campo	Tipo	Descrição
callbackUri	string	URL para a qual o usuário é redirecionado após o fim da jornada. Use / para fluxos de SDK nativo em que o callback é tratado dentro do app.
flow	string	Identificador do fluxo — determina quais capacidades são executadas. Exemplos: idunicodocs, idunicosign, idchecktrust, idtoken, idsmart. Veja Fluxos disponíveis.
purpose	string	Finalidade de negócio. Valores aceitos: creditprocess, biometryonboarding, carpurchase, ageverification.
person.duiType	enum	Tipo de documento. Veja os valores de duiType abaixo.
person.duiValue	string	Número do documento, sem formatação.
person.friendlyName	string	Nome de exibição do usuário mostrado na UI da jornada. Máximo de 50 caracteres.
person.phone	string	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	Endereço de e-mail. Obrigatório para fluxos com Assinatura Eletrônica.
person.​notifications	array	Canais de notificação para o envio do link da jornada. Cada item tem notificationChannel: NOTIFICATION_CHANNEL_WHATSAPP, NOTIFICATION_CHANNEL_SMS, ou NOTIFICATION_CHANNEL_EMAIL.
references	array	Entradas de referência para fluxos de Validação 1:1 e Revalidação Inteligente. Cada item contém referenceType (REFERENCE_TYPE_IMAGE_BASE64 ou REFERENCE_TYPE_PROCESS_ID) e referenceContent (imagem codificada em base64 ou UUID do processo). Envie no máximo um item — um array maior é rejeitado com 400, e referenceContent não pode estar vazio.
useCase	string	Cenário de Revalidação Inteligente. Obrigatório para 🇧🇷 idsmart, idsmart_r2, idsmart_tp1. Exemplos: USE_CASE_LOGIN, USE_CASE_FIN_TRANSACTIONS.
clientReference	string	Identificador único do usuário no seu sistema. Obrigatória para a capacidade Multi Contas. Único na sua base, máximo de 256 caracteres, sem espaços.
companyBranchId	string (UUID)	ID da filial. Obrigatório apenas se a service account tiver mais de uma filial associada.
expiresIn	string	Janela de validade do processo a partir da criação. Formato: "3600s". O padrão é 7 dias se omitido.
flowConfig	object	Sobreposições de configuração por fluxo.
flowConfig.​biometryCapture.​enabledBackCamera	boolean	Usa a câmera traseira do dispositivo. Não compatível com fluxos de captura de documento ou Assinatura Eletrônica.
contextualization	object	Contexto da transação mostrado ao usuário durante a jornada para explicar a captura. Disponível para clientes de qualquer região — não se limita a um país específico.
contextualization.​company_name	string	Nome da empresa exibido durante a jornada. Máximo de 20 caracteres.
contextualization.​currency	string	Código de moeda exibido ao usuário. Valores aceitos: BRL, MXN, USD.
contextualization.​price	number	Valor da transação exibido ao usuário.
contextualization.​locale	object	Texto localizado mostrado durante a jornada. Chaves: ptBr, enUs, esMx — esses são os únicos idiomas suportados para o texto, independentemente da região do cliente.
contextualization.locale.{ptBr|enUs|esMx}.reason	string	Motivo curto para a captura, mostrado durante a jornada. Máximo de 50 caracteres.
contextualization.locale.{ptBr|enUs|esMx}.title	string	Título do aviso ao cliente mostrado 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	Corpo do aviso ao cliente mostrado durante a jornada. Máximo de 210 caracteres. Deve ser fornecido junto com title. Tags HTML são removidas.
imageBase64	string	A selfie, enviada diretamente. Aceita o JWT de captura do SDK.
document.purpose	enum	Para que o documento é usado. Vocabulário fixo: DOCUMENT_PURPOSE_ONBOARDING, DOCUMENT_PURPOSE_CREDIT_PROCESS, DOCUMENT_PURPOSE_CAR_PURCHASE, DOCUMENT_PURPOSE_PAY_BY_PAYCHECK, DOCUMENT_PURPOSE_FGTS. Usado apenas com fluxos Face Document Match.
document.​files[].​data	bytes	Nova captura de documento, codificada em base64. Disponível globalmente, não se limita ao Brasil. Mutuamente exclusivo com document.documentId.
document.documentId	string (UUID)	Reutiliza um documento já capturado pela mesma pessoa, em vez de uma nova captura. Mutuamente exclusivo com document.files[].
expectedResult	object	Simula o resultado de uma capacidade em ambientes de teste/sandbox e marca a resposta com simulated: true. Veja Simulação de Resultados (Test Mock).

Valores de duiType

País	Valor	Descrição
AR	DUI_TYPE_AR_PASSPORT	Passaporte Argentino
AR	DUI_TYPE_AR_DNI	DNI Argentino
AR	DUI_TYPE_AR_LNC	Carteira de motorista Argentina (Licencia Nacional de Conducir)
AT	DUI_TYPE_AT_STNR	Número de Contribuinte Austríaco (STNR)
BE	DUI_TYPE_BE_NN	Número Nacional Belga (NN)
BR	DUI_TYPE_BR_CPF	CPF Brasileiro
BR	DUI_TYPE_BR_PASSPORT	Passaporte Brasileiro
BR	DUI_TYPE_BR_CNPJ	CNPJ Brasileiro
CA	DUI_TYPE_CA_SIN	SIN Canadense
CH	DUI_TYPE_CH_AHV	Número AHV/AVS Suíço
CL	DUI_TYPE_CL_RUN	RUN Chileno
CL	DUI_TYPE_CL_PASSPORT	Passaporte Chileno
CL	DUI_TYPE_CL_LICENCIA_CONDUCIR	Carteira de motorista Chilena (Licencia de Conducir)
CO	DUI_TYPE_CO_NIT	NIT Colombiano
CO	DUI_TYPE_CO_PASSPORT	Passaporte Colombiano
CO	DUI_TYPE_CO_LICENCIA_CONDUCCION	Carteira de motorista Colombiana (Licencia de Conducción)
CO	DUI_TYPE_CO_CC	Cédula de Cidadania Colombiana (Cédula de Ciudadanía)
DE	DUI_TYPE_DE_IDNR	Número de Identificação Fiscal Alemão (IdNr)
DK	DUI_TYPE_DK_CPR	CPR Dinamarquês
EC	DUI_TYPE_EC_NI	NI Equatoriano
ES	DUI_TYPE_ES_NIE	Número de Identidade de Estrangeiro Espanhol (NIE)
ES	DUI_TYPE_ES_DNI	Documento Nacional de Identidade Espanhol (DNI)
FI	DUI_TYPE_FI_HETU	Código de Identidade Pessoal Finlandês (HETU)
FR	DUI_TYPE_FR_SPI	Número de Referência Fiscal Francês (SPI)
GB	DUI_TYPE_GB_NINO	Número de Seguro Nacional Britânico (NINO)
GT	DUI_TYPE_GT_CUI	CUI Guatemalteco
ID	DUI_TYPE_ID_NIK	NIK Indonésio
IE	DUI_TYPE_IE_PPSN	Número de Serviço Público Pessoal Irlandês (PPSN)
IT	DUI_TYPE_IT_CF	Codice Fiscale Italiano (CF)
LK	DUI_TYPE_LK_NIC	NIC do Sri Lanka
LU	DUI_TYPE_LU_MATRICULE	Número de Identificação Nacional de Luxemburgo (Matricule)
MX	DUI_TYPE_MX_CURP	CURP Mexicano
MX	DUI_TYPE_MX_RFC_PERSONA_FISICA	RFC Mexicano (Pessoa Física)
MX	DUI_TYPE_MX_LICENCIA_CONDUCIR	Carteira de motorista Mexicana (Licencia de Conducir)
NG	DUI_TYPE_NG_NIN	NIN Nigeriano
NG	DUI_TYPE_NG_BVN	Número de Verificação Bancária Nigeriano (BVN)
NG	DUI_TYPE_NG_BVN_TOKEN	Token de BVN Nigeriano (hash)
NG	DUI_TYPE_NG_NIN_TOKEN	Token de NIN Nigeriano (hash)
NL	DUI_TYPE_NL_BSN	Número de Serviço ao Cidadão Holandês (BSN)
NO	DUI_TYPE_NO_FNR	Número de Identidade Nacional Norueguês (Fødselsnummer)
PE	DUI_TYPE_PE_RUC	RUC Peruano
PE	DUI_TYPE_PE_DNI	DNI Peruano
PE	DUI_TYPE_PE_PASSPORT	Passaporte Peruano
PL	DUI_TYPE_PL_PESEL	PESEL Polonês
PT	DUI_TYPE_PT_NIF	Número de Identificação Fiscal Português (NIF)
SE	DUI_TYPE_SE_PNR	Número Pessoal Sueco (PNR)
SE	DUI_TYPE_SE_SAMORDNINGSNUMMER	Número de Coordenação Sueco (Samordningsnummer)
TR	DUI_TYPE_TR_TCKN	Número de Identificação Turco (TCKN)
US	DUI_TYPE_US_SSN	SSN dos Estados Unidos
US	DUI_TYPE_US_PASSPORT	Passaporte dos Estados Unidos
US	DUI_TYPE_US_DRIVER_LICENSE	Carteira de motorista dos Estados Unidos
US	DUI_TYPE_US_PASSPORT_CARD	Cartão de Passaporte dos Estados Unidos
US	DUI_TYPE_US_POLYCARBONATE_PASSPORT	Passaporte de Policarbonato dos Estados Unidos
US	DUI_TYPE_US_ID_CARD	Carteira de Identidade dos Estados Unidos
UY	DUI_TYPE_UY_CI	CI Uruguaia
ZZ	DUI_TYPE_ZZ_EMAIL	Endereço de e-mail
ZZ	DUI_TYPE_ZZ_PHONE_NUMBER	Número de telefone

Criando um processo sem documento

Quando o fluxo permite documento opcional, você pode omitir person.duiType e person.duiValue. Após a captura, o processo aguarda em AWAITING_FOR_DOCUMENT até que seu back-end envie o documento com Definir Documento do Processo.

Exemplo

cURL

curl -X POST https://api.idcloud.unico.app/client/v1/process \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "flow": "idunicodocs_r2",
    "purpose": "biometryonboarding",
    "clientReference": "pedido-88216",
    "callbackUri": "https://your-app.example.com/onboarding/callback",
    "person": {
      "duiType": "DUI_TYPE_BR_CPF",
      "duiValue": "12345678909"
    }
  }'

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({
    flow: 'idunicodocs_r2',
    purpose: 'biometryonboarding',
    clientReference: 'pedido-88216',
    callbackUri: 'https://your-app.example.com/onboarding/callback',
    person: {
      duiType: 'DUI_TYPE_BR_CPF',
      duiValue: '12345678909',
    },
  }),
});

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

Respostas

200 OK

{
  "process": {
    "id": "b7c1f0a2-63d4-4f3e-9a17-2c8e5d41b0aa",
    "flow": "idunicodocs_r2",
    "state": "PROCESS_STATE_CREATED",
    "result": "PROCESS_RESULT_UNSPECIFIED",
    "purpose": "biometryonboarding",
    "clientReference": "pedido-88216",
    "person": {
      "duiType": "DUI_TYPE_BR_CPF",
      "duiValue": "12345678909"
    },
    "capacities": [
      "PROCESS_CAPACITY_IDLIVE",
      "PROCESS_CAPACITY_IDUNICO",
      "PROCESS_CAPACITY_IDDOCS"
    ],
    "authenticationInfo": {
      "authenticationId": ""
    },
    "companyData": {
      "branchId": "",
      "countryCode": "BRA"
    },
    "callbackUri": "https://your-app.example.com/onboarding/callback",
    "userRedirectUrl": "https://cadastro.unico.app/flow?id=b7c1f0a2-63d4-4f3e-9a17-2c8e5d41b0aa",
    "token": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9…",
    "webAppToken": "eyJlbmMiOiJBMjU2R0NNIiwiYWxnIjoiZGlyIn0…",
    "simulated": false
  }
}

Campo	Tipo	Descrição
process.id	string (UUID)	Identificador do processo. Use 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.result	enum	Resultado da verificação. Presente apenas quando state = PROCESS_STATE_FINISHED — veja Fluxos para os valores de resultado que um dado fluxo pode retornar.
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 Web SDK iFrame.
process.webAppToken	string	JWT para inicializar SDKs nativos (Android, iOS, Flutter).
process.createdAt	string (date-time)	Timestamp de criação do processo.
process.expiresAt	string (date-time)	Timestamp a partir do 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	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 de país associado à filial (ex.: BR, MX).

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 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 entre title ou text é fornecido em um locale.
3	invalid title argument in process contexts, max length is 100	Quando um title de locale excede 100 caracteres.
3	invalid text argument in process contexts, max length is 210	Quando um text de locale excede 210 caracteres.
3	invalid reason argument in process contexts, max length is 50	Quando um reason de locale excede 50 caracteres.
3	The references array must contain at most one element.	Quando mais de um item é enviado em references.
3	The references[].referenceContent field is missing.	Quando referenceContent está vazio.
3	The references[].referenceType field must be IMAGE_BASE64 or PROCESS_ID.	Quando referenceType não é um dos valores suportados.
3	A reference is required for this flow.	Quando o fluxo exige uma referência e nenhuma foi enviada. Envie references[0] com referenceType PROCESS_ID ou IMAGE_BASE64.
9	The referenceProcessId field is invalid.	Quando o processo de referência não existe ou não pode ser reutilizado. Nomeia o campo que você enviou — bioTokenId se foi esse o enviado.
3	INVALID_IMAGE	Quando a imagem não é um base64 válido, ou se parece com uma tentativa de injeção.
3	INVALID_DUI	Quando o número do documento não é padrão ou não existe.
3	IMAGE_TOO_LARGE	Quando a imagem excede o tamanho máximo de 800 KB.
3	UNSUPPORTED_IMAGE_FORMAT	Quando o formato da imagem não é PNG, JPEG ou WebP.
3	MISSING_IMAGE	Quando a imagem é obrigatória para este fluxo e não foi enviada.
3	MISSING_NAME	Quando o nome é obrigatório para este fluxo e não foi enviado.
3	MISSING_DUI	Quando o número do documento é obrigatório para este fluxo e não foi enviado.
3	MISSING_PERSON	Quando o objeto person é obrigatório para este fluxo e não foi enviado.
3	INVALID_REQUEST	Quando o corpo da requisição é nulo ou não pode ser interpretado.
3	TOKEN_ALREADY_USED	Quando o token de captura já foi usado. Ele é de uso único.
3	TOKEN_EXPIRED	Quando o token de captura expirou. Ele deve ser usado dentro de 10 minutos.
3	INVALID_BUNDLE	Quando a requisição não atende aos requisitos de segurança.
3	INVALID_NAME	Quando o nome é maior que o máximo permitido.
3	INVALID_EMAIL	Quando o endereço de e-mail está malformado ou é muito longo.
3	INVALID_PHONE	Quando o número de telefone tem mais de 20 caracteres.
3	INVALID_DUI_TYPE	Quando o tipo de documento não é um dos valores suportados.
3	INVALID_CLIENT_REFERENCE	Quando clientReference é muito longo, ou contém um espaço ou #.
3	INVALID_CONSENT_TYPE	Quando consentType não é NONE, DIRECT ou INDIRECT.
3	INVALID_USE_CASE	Quando useCase não é reconhecido, ou é muito longo.
3	INVALID_DEVICE_TRUST_TOKEN	Quando o token de device-trust é inválido ou já foi consumido.
3	TOO_MANY_REFERENCES	Quando mais de um item é enviado em references.
3	INVALID_REFERENCE_TYPE	Quando referenceType não é IMAGE_BASE64 ou PROCESS_ID.
3	INVALID_REFERENCE_PROCESS	Quando o ID do processo de referência não é um identificador válido.
3	REFERENCE_PROCESS_NOT_FOUND	Quando o processo referenciado não existe.
3	REFERENCE_PROCESS_NOT_READY	Quando o processo referenciado não tem resultado reutilizável, ou já foi consumido.
3	REFERENCE_SELFIE_NOT_FOUND	Quando o processo referenciado não carrega uma selfie para reutilizar.
3	INVALID_CAPTURE_TOKEN	Quando a imagem capturada não é um token válido produzido por um SDK de captura.
3	INVALID_CAPTURE_SIGNATURE	Quando a assinatura do token de captura não é válida.
3	PRIOR_CAPTURE_NOT_FOUND	Quando a captura anterior sobre a qual esta requisição se baseia não pôde ser localizada. Reinicie o processo.
3	PRIOR_CAPTURE_IN_PROGRESS	Quando a captura anterior ainda não terminou. Tente novamente em breve.
3	PRIOR_CAPTURE_FAILED	Quando a captura anterior não pôde ser concluída. Reinicie o processo.
3	INVALID_DOCUMENT	Quando um arquivo de documento não pode ser lido, está protegido por senha, ou está em um formato não suportado.
3	INVALID_AUTH_PROCESS	Quando document.authProcessId é inválido, expirado, ou pertence a outra pessoa.
3	INVALID_DOCUMENT_PURPOSE	Quando document.purpose não é um dos valores suportados.
3	PROCESS_REUSE_NOT_ENABLED	Quando o fluxo não permite reutilizar um processo anterior sem uma imagem. Envie uma imagem em vez disso.
9	PROCESS_FAILED	Quando o processo atinge uma falha terminal durante a criação.
9	Tenant API key is not configured	Quando a API Key não está configurada corretamente.

401 Unauthorized

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

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.

403 Forbidden

Código	Mensagem	Descrição
7	INVALID_API_KEY	Quando a API key é inválida ou está ausente.
7	INVALID_AUTH_TOKEN	Quando o token de autenticação é inválido.
7	PERMISSION_DENIED	Quando as credenciais são válidas mas não têm permissão para esta ação.
7	TOKEN_TENANT_MISMATCH	Quando o token de captura foi emitido para um tenant diferente.
7	MISSING_ACCESS_TOKEN	Quando o header de autorização está ausente.

404 Not Found

Código	Mensagem	Descrição
5	NO_RESULTS_FOUND	Quando um documento referenciado pela requisição não pôde ser encontrado.

429 Too Many Requests

Limite de taxa atingido. Quando seu sistema recebe um erro HTTP 429, você deve implementar mecanismos para prevenir falhas em cascata e evitar o agravamento da restrição.

Boas práticas:

• Período de resfriamento (backoff): Interrompa ou reduza imediatamente as requisições subsequentes do seu sistema. Não reenvie continuamente requisições com falha em um loop curto.
• Filas e limitação (Queueing & throttling): Armazene em buffer 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 retentar, aumente o tempo de espera exponencialmente entre as tentativas (por exemplo, 1 s, 2 s, 4 s, 8 s) e adicione um pequeno atraso aleatório ("jitter") para evitar um efeito de manada onde todas as requisições enfileiradas retentam exatamente no mesmo milissegundo.

aviso

Enviar requisições continuamente a um endpoint com limite de taxa sem aplicar backoff pode prolongar o período de restrição e impactar severamente a capacidade operacional do seu sistema. Limitar 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, consulte Limites de taxa.

500 Internal Server Error

Código	Mensagem	Descrição
13	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 espere pelo webhook.
• Para ver todas as combinações de receitas e seus possíveis valores de resultado, veja Fluxos.
• Para testar um resultado sem uma captura biométrica real, veja Simulação de Resultados (Test Mock).