Criar e Gerenciar Links de Verificação

Um link de verificação é o ponto de entrada do usuário final no fluxo de identidade. Você cria o link pela API, recebe uma URL única e a compartilha pelo canal de sua preferência. O usuário acessa o link pelo navegador, captura o documento e, se configurado, realiza a prova de vida.

Tipos de link

Tipo	Descrição
`FULL FLOW`	Captura do documento (frente e verso) mais prova de vida facial
`ID ONLY`	Apenas captura do documento (frente e verso), sem biometria

Escolha FULL FLOW quando precisar confirmar que a pessoa é real e corresponde ao documento. Use ID ONLY para cenários em que a prova de vida não é necessária.

Criar link

curl -X POST https://api.identity.vu-one.com/api/v1/links \
  -H "Authorization: Bearer <TOKEN>" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "FULL FLOW",
    "callbackUrl": "https://meuservico.com/verificacao-concluida",
    "externalUserId": "usuario-123",
    "adaptiveFlow": true,
    "metadata": { "campanha": "onboarding-janeiro" }
  }'

const response = await fetch('https://api.identity.vu-one.com/api/v1/links', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer ' + token,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    type: 'FULL FLOW',
    callbackUrl: 'https://meuservico.com/verificacao-concluida',
    externalUserId: 'usuario-123',
    adaptiveFlow: true,
    metadata: { campanha: 'onboarding-janeiro' },
  }),
});

const data = await response.json();
console.log(data.linkUrl);

import requests

response = requests.post(
    "https://api.identity.vu-one.com/api/v1/links",
    headers={"Authorization": f"Bearer {token}", "Content-Type": "application/json"},
    json={
        "type": "FULL FLOW",
        "callbackUrl": "https://meuservico.com/verificacao-concluida",
        "externalUserId": "usuario-123",
        "adaptiveFlow": True,
        "metadata": {"campanha": "onboarding-janeiro"},
    },
)

data = response.json()
print(data["linkUrl"])

Parâmetros do corpo

Campo	Tipo	Obrigatório	Descrição
`type`	string	Sim	`FULL FLOW` ou `ID ONLY`
`callbackUrl`	string	Não	URL para onde o usuário é redirecionado ao concluir a verificação
`externalUserId`	string	Não	ID do usuário no seu sistema, para correlacionar. Se enviado, o usuário não vê o campo de e-mail no fluxo
`adaptiveFlow`	boolean	Não	Permite que este link pule a captura documental e reverifique um cliente conhecido apenas com a selfie. Veja Fluxo adaptativo
`metadata`	objeto	Não	Dados arbitrários anexados ao link e repassados aos webhooks

Resposta

{
  "linkId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "linkUrl": "https://identity.vu-one.com/l/a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "verificationId": "f1e2d3c4-b5a6-7890-1234-567890abcdef"
}

Guarde linkId, linkUrl e verificationId. O verificationId é a chave para consultar status e resultados posteriormente.

Fluxo adaptativo

Introduzido na versão 2.2.0, o fluxo adaptativo permite que um cliente já verificado antes se reverifique apenas com uma selfie, sem repetir a captura do documento. adaptiveFlow tem três estados em POST /links:

Valor enviado	Comportamento
Omitido	Aplica a configuração da empresa (`linkConfig.adaptiveFlow`), desativada salvo se você a habilitar
`true`	Este link pode resolver para a ramificação apenas selfie mesmo com a configuração da empresa desativada
`false`	Este link sempre executa o fluxo documental completo, mesmo em uma empresa que habilitou a configuração

Omitir o campo e enviar false não são a mesma coisa. false é uma sobreposição explícita que garante o fluxo documental completo.

adaptiveFlow exige externalUserId para ter efeito. Sem esse identificador não há como localizar a verificação anterior, e o link executa silenciosamente o fluxo completo.

Se você não conhece o externalUserId ao criar o link, o usuário pode informá-lo durante o fluxo pelo endpoint público PATCH /verifications/identify. Veja Identificar a pessoa durante o fluxo. A ramificação efetivamente resolvida aparece como method em GET /verifications/{id}/status?include=operationGuid, com os valores FACE (ramificação adaptativa) ou DOCUMENT (fluxo completo).

Compartilhar o link

Após criar o link, envie o linkUrl ao usuário final por qualquer canal:

E-mail: link direto no corpo da mensagem
WhatsApp/SMS: mensagem curta com o link
QR code: gere um QR a partir do linkUrl para leitura em totens ou aplicativos

O link é de uso único. Após a primeira sessão iniciada, ele fica vinculado àquela tentativa de verificação.

Listar links

curl -H "Authorization: Bearer <TOKEN>" \
  https://api.identity.vu-one.com/api/v1/links

Retorna um array de objetos com a mesma estrutura de GET /links/{id}.

Consultar link por ID

curl -H "Authorization: Bearer <TOKEN>" \
  https://api.identity.vu-one.com/api/v1/links/a1b2c3d4-e5f6-7890-abcd-ef1234567890

{
  "_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "verificationId": "f1e2d3c4-b5a6-7890-1234-567890abcdef",
  "active": true,
  "expiresAt": "2026-08-23T14:00:00Z",
  "createdAt": "2026-08-22T14:00:00Z",
  "callbackUrl": "https://meuservico.com/verificacao-concluida",
  "externalUserId": "usuario-123",
  "metadata": { "campanha": "onboarding-janeiro" },
  "defaultTemplateVersion": "2026-07-01",
  "adaptiveFlow": true,
  "company": {
    "name": "Minha Empresa",
    "antiSpoofing": true,
    "color": "#ff4e08",
    "plan": "PRO",
    "handoffMode": "suggest",
    "gateRules": {
      "version": "2026-07-01",
      "rules": [
        {
          "id": "ios-legacy",
          "reason": "unsupported_os",
          "match": { "formFactor": "mobile", "platform": "ios", "osVersionMax": "14" }
        }
      ]
    },
    "locationPermission": "optional"
  }
}

Campo	Tipo	Descrição
`_id`	uuid	Identificador do link
`verificationId`	uuid	Verificação associada
`active`	boolean	Se o link ainda pode ser usado
`expiresAt`	date-time	Momento da expiração
`createdAt`	date-time	Momento da criação
`callbackUrl`	string	URL de redirecionamento configurada
`externalUserId`	string	Identificador do usuário no seu sistema
`metadata`	objeto	Metadados enviados na criação
`defaultTemplateVersion`	string, nullable	Versão do template global ativo de regras de gate. É estado global, idêntico para todas as empresas. `null` quando não há template ativo
`adaptiveFlow`	boolean	Ramificação já resolvida para este link (`link.adaptiveFlow` se enviado, ou a configuração da empresa). Nunca o valor de três estados aceito por `POST /links`
`company.name`	string	Nome da empresa
`company.antiSpoofing`	boolean	Se os controles anti-spoofing estão ativos
`company.color`	string	Cor da marca
`company.plan`	string	Plano contratado
`company.handoffMode`	string	Se a empresa oferece a transferência de dispositivo e com que insistência: `never`, `suggest` ou `require`. Padrão `never`
`company.gateRules`	objeto	Conjunto de regras resolvido e somente leitura que decide quais dispositivos ficam bloqueados. Gerenciado pela VU e nunca aceito em um `PATCH`
`company.locationPermission`	string	Política efetiva de permissão de localização: `never`, `optional` ou `required`. Sempre resolvida no servidor

gateRules é somente leitura. Cada regra traz id, reason e um bloco match com formFactor, platform e osVersionMax.

Configuração da empresa

Duas configurações da empresa afetam diretamente os links que você cria:

Campo	Padrão	Descrição
`linkConfig.expirationTime`	1	Tempo de validade de um novo link
`linkConfig.adaptiveFlow`	`false`	Se os links podem resolver para a ramificação apenas selfie quando o próprio link não sobrepõe o valor

Consulte e ajuste ambos em GET /users/me/company e PATCH /users/me/company. Links expirados não permitem iniciar uma nova verificação.

Primeiros Passos

Conceitos-Chave

Referência

Criar e Gerenciar Links de Verificação

Tipos de link

Criar link

Parâmetros do corpo

Resposta

Fluxo adaptativo

Compartilhar o link

Listar links

Consultar link por ID

Configuração da empresa

Próximos passos

KYC

Webhooks

​Tipos de link

​Criar link

​Parâmetros do corpo

​Resposta

​Fluxo adaptativo

​Compartilhar o link

​Listar links

​Consultar link por ID

​Configuração da empresa

​Próximos passos

KYC

Webhooks

Tipos de link

Criar link

Parâmetros do corpo

Resposta

Fluxo adaptativo

Compartilhar o link

Listar links

Consultar link por ID

Configuração da empresa

Próximos passos