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

# Migração da v9 para a v10

> O que muda na prática para quem já integrou o FaceTec v9

Este guia resume o que muda para quem já tem uma integração com o [FaceTec v9](/plataforma/liveness/facetec/v9/apresentacao) e precisa migrar para a v10 antes do desligamento em **01/11/2026**. Para o contrato completo de cada chamada, veja [Serviço](/plataforma/liveness/facetec/v10/servico) e a documentação do [SDK Web](/plataforma/liveness/facetec/v10/sdk/web/instalacao).

## O que muda

|                              | v9                                                                                                                       | v10                                                                                                                                                                                                                |
| ---------------------------- | ------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| Criar sessão                 | `POST /api/v1/sessions`                                                                                                  | `POST /api/v2/sessions`                                                                                                                                                                                            |
| Token do FaceTec             | Retornava `facetecSessionToken`, usado pelo SDK para abrir a UI                                                          | Não existe mais — o SDK Web resolve isso sozinho a partir do `sessionToken`                                                                                                                                        |
| Limite de tentativas         | `maxAttempts` (1 a 5) na criação da sessão; retry acontecia **dentro** da mesma sessão                                   | Não existe mais `maxAttempts` — cada tentativa nova é uma **sessão nova**                                                                                                                                          |
| Encerrar sessão abandonada   | Chamada manual a `POST /api/v1/sessions/:sessionId/fail`                                                                 | Mesma ideia: `POST /api/v2/sessions/:sessionId/fail`, com o mesmo corpo e resposta                                                                                                                                 |
| Ponto de montagem do SDK Web | `mount` apontava para um elemento do DOM                                                                                 | Não existe mais — a captura abre como camada full-screen sobre a página                                                                                                                                            |
| Resultado da captura         | Objeto extenso (`captureId`, `status`, `livenessScore`, `confidence`, `securityChecks`, `attemptsLeft`, entre outros)    | Objeto enxuto: `sessionId`, `verified`, `processingTime`, `base64Image`, `ageGroup`                                                                                                                                |
| Customização visual          | `hubOptions.colorTheme` com paleta fixa (`frameColor`, `buttonColor`, `buttonTextColor`, `loadingColor`, `successColor`) | `options.customization`, com grupos que espelham a própria API do FaceTec (`oval`, `frame`, `guidance`, `resultScreen`, entre outros) — veja [Customização](/plataforma/liveness/facetec/v10/sdk/web/customizacao) |

## Como fazer a migração (Web)

<Steps>
  <Step title="Atualize o backend">
    Troque a chamada de criação de sessão para [`POST /api/v2/sessions`](/plataforma/liveness/facetec/v10/servico#post-api-v2-sessions). O corpo da requisição não usa mais `visitorId`/`eventId`/`maxAttempts`; a resposta não traz mais `facetecSessionToken`. Se você chama o endpoint de falha manual, só troque `/api/v1/` por `/api/v2/` na URL — o corpo e a resposta são idênticos.
  </Step>

  <Step title="Aponte para o novo script do SDK">
    Troque a URL do `<script>` carregado via CDN pela [URL da v10](/plataforma/liveness/facetec/v10/sdk/web/instalacao). Não é preciso carregar o motor FaceTec separadamente — o novo bundle já faz isso.
  </Step>

  <Step title="Remova o `mount`">
    A captura da v10 abre como camada full-screen. Remova qualquer elemento do DOM que você reservava só para montar o SDK.
  </Step>

  <Step title="Ajuste os callbacks">
    Atualize `onSuccess`/`onFailure` para o novo formato de resultado e de erro — veja [Implementação](/plataforma/liveness/facetec/v10/sdk/web/implementacao) e [Solução de problemas](/plataforma/liveness/facetec/v10/sdk/web/troubleshooting).
  </Step>

  <Step title="Remova a lógica de retry dentro da sessão">
    Se o seu código tratava `attemptsLeft`/`canRetry` para reexibir a tela sem criar uma nova sessão, remova essa lógica: na v10, uma nova tentativa é sempre uma chamada nova a `run()`, que cria uma sessão nova automaticamente.
  </Step>

  <Step title="Reaplique a customização visual, se houver">
    O sistema de temas mudou de um preset fixo para grupos de campos que espelham a própria API do FaceTec. Reveja sua paleta em [Customização](/plataforma/liveness/facetec/v10/sdk/web/customizacao).
  </Step>
</Steps>

<Info>
  A v9 continua funcionando normalmente até o desligamento. Não é necessário migrar de uma vez — as duas versões podem coexistir enquanto você faz a transição.
</Info>