> ## Documentation Index
> Fetch the complete documentation index at: https://docs.vu-one.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Changelog da Identity Link API

> Histórico de versões e mudanças da Identity Link API da VU, incluindo novos recursos, melhorias e mudanças de comportamento.

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)

<Note>
  O VU Cloud Services já está disponível para todas as contas Premium e Pro. A integração de verificação não muda: não há mudanças de contrato na Identity Link API, exceto o limite de 100 por página na listagem de verificações, que agora é aplicado.
</Note>

### 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](/pt/vucs/introducao).
* **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

<Note>
  Melhorias do portal. Nada muda na API: nenhum endpoint, campo ou código de resposta é afetado.
</Note>

### 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

<Note>
  Correções. Não há mudanças de contrato na API.
</Note>

### 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

<Note>
  Esta versão adiciona ao portal a base do VU Cloud Services, que será habilitado em breve. A integração de verificação não muda: não há mudanças de contrato na Identity Link API, e uma integração existente não precisa de nenhuma modificação.
</Note>

### 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](/pt/vucs/introducao) 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

<Note>
  Atualização dos documentos legais que a plataforma exibe para a pessoa que se verifica. Nada muda na API: nenhum endpoint, campo ou código de resposta é afetado.
</Note>

### 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

<Warning>
  Esta versão introduz mudanças de comportamento nos endpoints de status e de reporte. Planeje a migração antes de atualizar.
</Warning>

* **`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)

<Warning>
  Esta versão contém mudanças que quebram compatibilidade. Atualize sua integração antes de migrar.
</Warning>

### 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.


## Related topics

- [Identity Link API: Guia de Integração Completo](/pt/identity-link/introducao.md)
- [Códigos de Erro e Respostas da Identity Link API](/pt/identity-link/erros.md)
- [Documentação técnica da VU](/pt/index.md)
- [Planos do Identity Link](/pt/identity-link/planos.md)
- [Prova de Vida e Biometria Facial no Identity Link](/pt/identity-link/prova-de-vida.md)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.