Changelog da Identity Link API

Este changelog registra as mudanças da Identity Link API da VU Security. As entradas estão ordenadas da mais recente para a mais antiga. Mudanças que quebram compatibilidade são marcadas explicitamente.

​

v2.4.1 (versão atual)

​

VU Cloud Services disponível

• Api-keys self-service para todas as contas Premium e Pro: a seção Cloud Services do portal já está habilitada. ID Analysis, Face Analysis e Antispoofing Facial são integrados com api-keys que você cria, rotaciona, pausa e revoga no portal, sem abrir um ticket. O Connection Fingerprint é contratado com um comercial e não usa api-keys. Veja a documentação.
• Período de teste: até 5 api-keys por serviço, com 10.000 chamadas de teste cada uma. Durante o período de lançamento o consumo não é faturado.
• Motivo visível ao recusar uma api-key: quando o serviço não está habilitado para a conta, o portal explica o motivo em vez de mostrar um erro genérico.

​

Mudanças de comportamento

• GET /verifications/{size}/{page} aplica o máximo de 100 por página: um size maior que 100 é servido como 100, e um size ausente, zero ou negativo também é servido como 100 (antes, um size negativo respondia 500). Se você pedia mais de 100 por página, percorra as páginas.

​

Novos recursos

• Voltar à tela pedida depois de entrar: um link para qualquer tela do portal leva a essa tela depois do login.

​

Melhorias

• Link de verificação com uma sessão do portal expirada: quando o navegador da pessoa tinha uma sessão expirada do portal, o link de verificação a mandava para a tela de login. Agora a verificação continua.
• E-mail de contato com o suporte: chegava com o assunto de confirmação de conta. Agora tem o assunto de suporte.

​

v2.3.2

​

Novos recursos

• Botão Compartilhar ao criar um link: fica ao lado de Copiar, na tela do link recém-criado. No celular, abre a folha de compartilhamento do sistema. No computador, abre um menu com E-mail, WhatsApp, Copiar link curto e Mostrar QR. O QR é gerado no navegador, sem enviar o link a nenhum serviço externo.
• Documentação pelo menu lateral: novo item Documentação, visível em todos os planos, com duas entradas: os guias de docs.vu-one.com e a referência da API (Swagger).

​

Melhorias

• Compartilhar o link pelo QR hand-off no Android: às vezes o link não era compartilhado nem copiado, e nenhum aviso aparecia. Agora o link é copiado antes de abrir a folha de compartilhamento. Se a folha falhar ou for cancelada, uma mensagem confirma que o link foi copiado. Se a cópia também falhar, o link aparece na tela para ser copiado manualmente.

​

v2.3.1

​

Melhorias

• Voltar a pagar depois que o cartão vence: cadastrar um método de pagamento falhava quando a conta não tinha mais um cartão associado. Agora POST /billing/paymentMethod funciona sem cartão prévio e, se a assinatura tiver uma fatura em aberto, faz a cobrança. Se o emissor recusar o pagamento, a conta fica como estava e o portal mostra o motivo.
• Mapa de localização do cliente: exibia o aviso “Access blocked” do OpenStreetMap em vez do mapa. Agora o mapa carrega.

​

v2.3.0

​

VU Cloud Services (em breve)

Estes recursos já estão na plataforma e são habilitados quando o VU Cloud Services estiver disponível para todas as contas. A documentação já está publicada.

• Seção VU Cloud Services no portal: nova seção com o catálogo de serviços disponíveis —ID Analysis, Face Analysis, Antispoofing Facial e Connection Fingerprint—, cada um com sua descrição, seu preço e sua documentação de integração, em espanhol, inglês e português.
• Api-keys autogerenciadas: criação, rotação, pausa e revogação de api-keys pelo portal, sem abrir chamado. O segredo é exibido uma única vez, ao criar a key ou ao confirmar a rotação. O Connection Fingerprint é contratado com um comercial e não usa api-keys.
• Consumo por api-key: cada api-key tem sua tela de uso, com o que foi consumido, o limite do período de teste, o saldo restante e sua valorização. Durante o período de lançamento o consumo não é faturado.
• Aviso aos 80 % da cota: quando uma api-key passa de 80 % da sua cota, o titular da conta recebe um e-mail com o serviço, o consumo e o limite. Não é preciso acompanhar a tela de consumo para saber.
• Solicitação de contato comercial dentro do produto: disponível no catálogo, na tela de consumo e quando o período de teste se esgota. É idempotente por empresa: uma vez enviada a solicitação, um novo clique devolve a mesma e não gera outra.

​

Mudanças de comportamento

• Baixar de plano ou cancelá-lo avisa antes de confirmar: a tela detalha quais integrações deixam de estar disponíveis e o que acontece com cada api-key.

​

Melhorias

• iOS e a permissão de localização: quem já havia recusado a localização era informado de que o navegador tinha bloqueado o pedido e, nos fluxos em que a localização é obrigatória, ficava sem saída. Agora a mensagem explica a situação real e há sempre um caminho de volta.
• Tradutor automático do navegador: deformava os textos do fluxo de verificação. O fluxo declara seu idioma corretamente e o tradutor o respeita.
• Nome do negócio em Configurações: a ficha da empresa exibia um identificador interno sob o rótulo “Id de Negócio”. Agora o rótulo diz Nome do Negócio e mostra o nome da conta.
• Seletor de idioma no celular: volta a ficar acessível no login, no cadastro, na confirmação de e-mail e no cabeçalho do painel.
• Ajustes visuais do portal: tipografias distorcidas, o menu lateral que se sobrepunha em larguras intermediárias, a navegação em telas estreitas, a mensagem da solicitação de contato e o acesso a uma URL do portal sem sessão iniciada, que agora leva ao login em vez de a uma tela vazia.

​

v2.2.1

​

Mudanças

• Termos e Condições de usuário final e Política de Privacidade atualizados para a versão 2.1.
• Documentos legais em português: o fluxo de verificação em português já serve os Termos e Condições e a Política de Privacidade nesse idioma.

​

v2.2.0

​

Novos recursos

• Fluxo adaptativo: novo campo adaptiveFlow em POST /links que reverifica um cliente conhecido apenas com a selfie, pulando a captura documental. Tem três estados: omitido segue a configuração da empresa, true e false a sobrepõem para aquele link. Exige externalUserId para ter efeito.
• Configuração linkConfig.adaptiveFlow: chave por empresa, desativada por padrão, que rege os links que não a sobrepõem explicitamente. Disponível em GET e PATCH /users/me/company.
• Ramificação resolvida no link: GET /links/{id} agora retorna adaptiveFlow já resolvido (link.adaptiveFlow ou a configuração da empresa), e não o valor de três estados.
• PATCH /verifications/identify: novo endpoint público que permite a um link adaptativo criado sem externalUserId receber o e-mail da pessoa durante o fluxo e resolver novamente a ramificação adaptativa.
• GET /verifications/{id}/related: novo endpoint autenticado que lista as demais verificações do mesmo cliente (mesma empresa, mesmo externalUserId), da mais recente para a mais antiga, com o indicador dataExpired para as linhas já anonimizadas pela retenção.
• method no polling de status: GET /verifications/{id}/status?include=operationGuid agora também retorna method, com os valores FACE (ramificação adaptativa) ou DOCUMENT (fluxo completo), ou null enquanto não resolvido.
• Regras de gate no link: GET /links/{id} expõe company.gateRules, um conjunto de regras resolvido e somente leitura que decide quais grupos de dispositivos ficam bloqueados, junto de defaultTemplateVersion, a versão do template global ativo.
• locationPermission: nova política, sempre resolvida no servidor, com os valores never, optional e required. Aparece em company.locationPermission no GET /links/{id} e em verificationConfig.locationPermission da empresa. Planos FREE sempre resolvem para never.
• onboardingBusinessId restaurado: GET /users/me/company volta a incluir o id de negócio da integração de onboarding, removido no pentest #30. Settings agora tem uma necessidade documentada de exibi-lo para suporte e depuração.
• POST /vuone/contact-request: novo endpoint para solicitar contato comercial a partir da própria conta. É idempotente por empresa: um segundo clique retorna a solicitação existente (200) em vez de criar outra (201). Empresa, plano e cota são derivados da sessão autenticada, nunca do corpo da requisição.

​

Mudanças de comportamento

• linkId obrigatório no status: GET /verifications/{id}/status é um endpoint público e agora exige linkId como parâmetro de consulta obrigatório. Omiti-lo, ou enviar um que não corresponda à verificação, retorna 403.
• PATCH /verifications retorna 404: se a verificação não existe ou expirou, o endpoint retorna 404 em vez de 200 sem alterações.
• PATCH /verifications/error retorna 404: igual ao item anterior.
• PATCH /verifications retorna 409: se o status da verificação não permite a operação solicitada, retorna 409 em vez de 200 sem alterações.
• PATCH /verifications/error retorna 409: igual ao item anterior.
• Validação estrita de geolocalização: tier, policy, ipDistanceKm e serverIp são derivados no servidor e não são mais aceitos como entrada; enviá-los retorna 400. Um capturedAt que se afaste mais de 24 horas do relógio do servidor também retorna 400.
• GET /billing/{idSubscription} retorna 403: além da falta de token, agora também responde 403 quando a assinatura não pertence à empresa do chamador.

​

Recomendação de migração

1. Adicione linkId a todas as chamadas de GET /verifications/{id}/status e remova o cabeçalho Authorization: o endpoint é público.
2. Trate os códigos 404 e 409 em PATCH /verifications e PATCH /verifications/error. Em versões anteriores à 2.2.0 esses endpoints respondiam 200 mesmo sem realizar nenhuma ação.
3. Revise seu cliente de geolocalização: mova todos os campos para dentro do objeto geolocation e pare de enviar os campos derivados no servidor.
4. Se for usar o fluxo adaptativo, envie externalUserId na criação do link ou chame PATCH /verifications/identify durante o fluxo.

​

v2.1.0 (2024-01)

​

Novos recursos

• Paginação de verificações: endpoint GET /verifications/{size}/{page} para consultar verificações de forma paginada.
• Feedback manual: endpoints POST /verifications/feedback e GET /verification-feedback/reasons para enviar correções e classificações sobre verificações concluídas.
• Geolocalização enriquecida: o objeto geolocation agora inclui campos adicionais como tier, permission, deviceLatitude, deviceLongitude, ipDistanceKm e serverIp (visíveis apenas em requisições autenticadas GET).

​

Melhorias

• Respostas de erro mais descritivas com campos message e error padronizados.
• Melhorias de performance no endpoint GET /verifications/{id}/status para polling de alta frequência.

​

v2.0.0 (2023-06)

​

Mudanças de breaking change

• Renomeação de campos: firstName e lastName foram consolidados em firstNames e lastNames para suportar múltiplos nomes.
• Status unificado: o campo result foi removido. O status final da verificação agora está exclusivamente no campo status com valores pending, started, expired, success e failed.
• Autenticação: o endpoint de token foi movido de /auth/token para /oauth/token e agora segue estritamente o padrão OAuth2.

​

Novos recursos

• Webhooks gerenciáveis: endpoints GET /webhook-endpoints, POST /webhook-endpoints, PATCH /webhook-endpoints/{id} e DELETE /webhook-endpoints/{id} para configurar e gerenciar webhooks via API.
• Assinatura HMAC: todos os payloads de webhook agora incluem assinatura HMAC-SHA256 no cabeçalho X-Signature-SHA256.
• Tipo ID ONLY: novo tipo de link para verificação documental sem prova de vida.

​

v1.2.0 (2023-02)

​

Novos recursos

• Endpoint de saúde: GET /health/status para monitoramento externo da disponibilidade da API.
• Logs de atividade: endpoint GET /users/me/logs com paginação para consultar o histórico de chamadas da conta.
• Estatísticas da conta: endpoint GET /users/me/stats retorna cota, links gerados, verificações usadas e restantes.

​

Melhorias

• Suporte a metadata no corpo de criação de links (POST /links).
• Redução do tempo de expiração padrão de links de 48h para 24h.

​

v1.1.0 (2022-11)

​

Novos recursos

• Configuração da empresa: endpoints GET /users/me/company e PATCH /users/me/company para consultar e ajustar branding, tempo de expiração de links e configurações de verificação.
• Upload de logo: endpoint POST /users/me/company/logo para envio de logo em multipart/form-data.

​

Melhorias

• OCR aprimorado para documentos brasileiros (RG e CNH).
• Adição do campo geolocation nas respostas de verificação.

​

v1.0.0 (2022-08)

Lançamento inicial da Identity Link API.

• Criação e gerenciamento de links de verificação (POST /links, GET /links).
• Verificação de identidade com captura documental e prova de vida (FULL FLOW).
• Consulta de status e resultados de verificações (GET /verifications).
• Webhooks para notificações assíncronas.
• Autenticação com client credentials.