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

# Serviço

> Crie sessões de liveness FaceTec v10 via API antes de iniciar o SDK

O serviço de sessões FaceTec autoriza o seu projeto e devolve ao seu cliente o token que o `LivenessFacetecSDK` precisa para abrir a captura. Sem essa chamada, o SDK não consegue inicializar.

A base URL de produção é `https://api.valid.com/facetec-vendor` e a rota fica abaixo de `/api/v2`. A autenticação usa a sua `x-api-key`, gerada na Plataforma ID — veja [Chaves de API](/plataforma/chaves-de-api).

<Warning>
  **A URL do seu backend que faz essas chamadas precisa ser liberada pela equipe da Valid antes da primeira chamada.** Sem essa liberação, as chamadas a este serviço são rejeitadas mesmo com uma `x-api-key` válida. Envie a URL (produção e homologação, se houver) à equipe da Valid antes de integrar.
</Warning>

<Info>
  O domínio (Web), Package Name (Android) ou Bundle Identifier (iOS) do seu app também precisam ser liberados na licença FaceTec — veja os pré-requisitos de [instalação Web](/plataforma/liveness/facetec/v10/sdk/web/instalacao#requisitos), [Android](/plataforma/liveness/facetec/v10/sdk/android/instalacao#pré-requisitos) e [iOS](/plataforma/liveness/facetec/v10/sdk/ios/instalacao#pré-requisitos).
</Info>

## Por que essa chamada existe

O `LivenessFacetecSDK` é apenas um cliente: quem cria a sessão é o seu backend. Na v10, ao contrário da v9, o SDK Web se comunica diretamente com o serviço FaceTec para todo o resto do fluxo (inicialização do motor, captura, status) usando o `sessionToken` emitido nesta chamada — você não precisa implementar nem fazer proxy dessas outras chamadas.

* **`POST /api/v2/sessions`** — cria a sessão de liveness e devolve o `sessionToken` que o SDK usa para todo o resto do fluxo.
* **`POST /api/v2/sessions/:sessionId/fail`** — encerra uma sessão ativa quando o problema acontece **entre o SDK e o seu servidor**, antes da captura começar (usuário cancela na sua tela, validação de negócio rejeita, timeout do front, etc.), deixando o motivo registrado para auditoria no painel. Evite chamar depois que o SDK já foi inicializado: a sessão é marcada como encerrada mesmo assim, o que pode interromper uma captura em andamento.

<Warning>
  **Faça essa chamada no seu backend, não no app ou na página.**

  A `x-api-key` da Plataforma ID identifica o seu projeto e libera acesso à cobrança e às credenciais FaceTec. Embuti-la no binário Android, no IPA ou no bundle JS de uma SPA é equivalente a publicar a chave no repositório — qualquer pessoa consegue extrair, reusar e gerar custo no seu projeto com ferramentas comuns (`jadx`, `Hopper`, DevTools).

  **A única integração segura é proxy-server-side:** o seu cliente fala com o seu backend, o seu backend fala com a Plataforma ID. O cliente nunca toca na `x-api-key`.
</Warning>

## Fluxo recomendado

<Steps>
  <Step title="Cliente solicita sessão ao seu backend">
    O app/web invoca um endpoint do seu próprio backend (com a sua autenticação de usuário), repassando opcionalmente o `ssid` que o SDK Web obtém durante a inicialização — veja [Metadados Complementares](#metadados-complementares).
  </Step>

  <Step title="Seu backend chama POST /api/v2/sessions">
    Servidor para servidor, com o header `x-api-key`. O serviço retorna `sessionId` e `sessionToken`.
  </Step>

  <Step title="Seu backend devolve os tokens ao cliente">
    Envie ao cliente apenas o que ele precisa: `sessionId`, `sessionToken` e `expiresAt`.
  </Step>

  <Step title="Cliente inicializa o Liveness com esses tokens">
    O `LivenessFacetecSDK` consome os tokens e abre a captura. Veja [Implementação Web](/plataforma/liveness/facetec/v10/sdk/web/implementacao).
  </Step>

  <Step title="Se a captura falhar, tente novamente">
    Não existe retry dentro da mesma sessão: se a captura falhar, o app simplesmente chama o SDK de novo — o que cria automaticamente uma **nova sessão**.
  </Step>

  <Step title="Se o problema for entre o SDK e o seu servidor, falhe a sessão">
    Caso o usuário cancele ou o seu backend rejeite o fluxo antes da captura começar, chame `POST /api/v2/sessions/:sessionId/fail` para marcar a sessão como falha — o motivo fica registrado para auditoria no painel. Chame somente nessa janela: se disparado depois que o SDK já foi inicializado, a chamada continua funcionando e encerra a sessão do mesmo jeito, mas como o SDK pode já estar em captura nesse ponto, isso derruba um fluxo que ainda estava em andamento. Sessões não finalizadas também expiram sozinhas por TTL.
  </Step>
</Steps>

## POST /api/v2/sessions

Cria uma nova sessão de liveness FaceTec e retorna o token que o SDK precisa para inicializar a captura.

**Endpoint:** `POST https://api.valid.com/facetec-vendor/api/v2/sessions`

<Info>
  **Essa resposta também pode trazer sinais antifraude.** Quando você informa o `ssid`, o serviço retorna adicionalmente `deviceSignals` (sinais de risco do dispositivo) e `geolocation`/`ipGeolocation` (localização aproximada) — veja [Metadados Complementares](#metadados-complementares).
</Info>

### Headers

| Header         | Valor                                                                   |
| -------------- | ----------------------------------------------------------------------- |
| `x-api-key`    | Chave da Plataforma ID — ver [Chaves de API](/plataforma/chaves-de-api) |
| `Content-Type` | `application/json`                                                      |

### Body

<ParamField body="clientRequestId" type="string (uuid)" required>
  UUID gerado pelo seu backend para esta tentativa. Funciona como chave de idempotência: reenvios com o mesmo `(projeto, clientRequestId)` retornam a mesma sessão em vez de criar uma nova.
</ParamField>

<ParamField body="ssid" type="string">
  Identificador de sessão de dispositivo obtido pelo SDK Web durante a inicialização. Quando informado, o serviço enriquece a resposta com `deviceSignals`, `geolocation` e `ipGeolocation`. Veja [Metadados Complementares](#metadados-complementares).
</ParamField>

<ParamField body="platform" type="string">
  Plataforma de origem da chamada. Valores aceitos: `APP` ou `WEB`.
</ParamField>

### Resposta 201

<ResponseField name="sessionId" type="string (uuid)">
  ID da sessão criada. Use-o no SDK e para correlacionar logs.
</ResponseField>

<ResponseField name="sessionToken" type="string (jwt)">
  Token emitido pelo serviço. O SDK Web utiliza este token para todo o restante do fluxo de captura — você não precisa repassá-lo para mais nenhuma chamada própria.
</ResponseField>

<ResponseField name="createdAt" type="string (iso-8601)">
  Data/hora de criação da sessão.
</ResponseField>

<ResponseField name="expiresAt" type="string (iso-8601)">
  Data/hora de expiração. Após esse instante a sessão não aceita mais captura.
</ResponseField>

<ResponseField name="notice" type="string">
  Texto de consentimento / aviso legal. Exiba ao usuário antes de iniciar a captura.
</ResponseField>

<ResponseField name="deviceSignals" type="object">
  Sinais de risco do dispositivo, obtidos via Shield. Presente quando o `ssid` é informado e o enriquecimento é bem-sucedido. O conjunto de flags varia por plataforma (ex.: `appTampering`, `hooking`, `emulated`, `jailbroken`, `proxy`, `clonedApps` para APP; `bot`, `tor`, `incognito`, `browserSpoofed` para WEB).
</ResponseField>

<ResponseField name="geolocation" type="object">
  Geolocalização do dispositivo (`latitude`, `longitude`), obtida via GPS/navegador. Só vem preenchida se a sua aplicação já tiver pedido e recebido permissão de localização do usuário **antes** dessa chamada — veja [Metadados Complementares](#metadados-complementares). Opcional.
</ResponseField>

<ResponseField name="ipGeolocation" type="object">
  Geolocalização derivada do IP da requisição (`latitude`, `longitude`). Também depende do `ssid`, mas **não** depende de permissão de localização do usuário — só do enriquecimento via `ssid` ter sido bem-sucedido. Opcional.
</ResponseField>

### Códigos de erro

| Status | Quando ocorre                                                                       |
| ------ | ----------------------------------------------------------------------------------- |
| `400`  | `clientRequestId` ausente ou fora do formato UUID, ou `platform` com valor inválido |
| `401`  | Header `x-api-key` ausente ou inválido                                              |
| `403`  | Chave válida, mas o projeto não tem o produto Liveness habilitado                   |
| `500`  | Falha interna ao criar a sessão                                                     |

## POST /api/v2/sessions/:sessionId/fail

Encerra explicitamente uma sessão ativa sem captura submetida. Use apenas para problemas **entre o SDK e o seu próprio servidor**, antes da captura começar — cancelamento do usuário antes de iniciar, falha de validação no seu backend, timeout do front, etc. O motivo enviado fica registrado e visível para auditoria no painel. Evite chamar depois que o SDK já foi inicializado: a chamada continua funcionando e encerra a sessão do mesmo jeito, mas como o SDK pode já estar em captura nesse ponto, isso derruba um fluxo que ainda estava em andamento — o backend passa a considerar a sessão finalizada enquanto o SDK ainda está processando. É a mesma operação da v9, só na rota `/api/v2`.

**Endpoint:** `POST https://api.valid.com/facetec-vendor/api/v2/sessions/:sessionId/fail`

### Headers

| Header         | Valor                                                                   |
| -------------- | ----------------------------------------------------------------------- |
| `x-api-key`    | Chave da Plataforma ID — ver [Chaves de API](/plataforma/chaves-de-api) |
| `Content-Type` | `application/json`                                                      |

### Path params

| Param       | Tipo | Descrição                                          |
| ----------- | ---- | -------------------------------------------------- |
| `sessionId` | UUID | `sessionId` retornado pelo `POST /api/v2/sessions` |

### Body

<ParamField body="reason" type="string" required>
  Motivo do encerramento (1 a 500 caracteres). Persistido para auditoria — não inclua dados sensíveis do usuário aqui.
</ParamField>

### Resposta 200

<ResponseField name="sessionId" type="string (uuid)">
  ID da sessão finalizada.
</ResponseField>

<ResponseField name="status" type="string">
  Sempre `"failed"`.
</ResponseField>

<ResponseField name="failureReason" type="string">
  Eco do `reason` enviado.
</ResponseField>

<ResponseField name="finalizedAt" type="string (iso-8601)">
  Data/hora em que a sessão foi marcada como falha.
</ResponseField>

### Códigos de erro

| Status | Quando ocorre                                                        |
| ------ | -------------------------------------------------------------------- |
| `400`  | `sessionId` não é UUID ou `reason` ausente/fora do tamanho permitido |
| `401`  | `x-api-key` ausente ou inválido                                      |
| `404`  | Sessão não encontrada para o projeto                                 |
| `409`  | Sessão já está finalizada (`completed` ou `failed`)                  |

## Metadados Complementares

O `ssid` é um identificador de sessão de dispositivo que o `LivenessFacetecSDK` Web obtém **durante a inicialização**, antes de qualquer chamada ao serviço de sessão. Quando você o repassa em `POST /api/v2/sessions`, o serviço enriquece a resposta com dois tipos de dado adicional:

* **`deviceSignals`** — sinais de risco do dispositivo (emulador, root/jailbreak, proxy, bot, etc.), sempre que o `ssid` é aceito.
* **`geolocation`** — latitude/longitude do dispositivo, mas **só quando o usuário já concedeu permissão de localização ao navegador**. O SDK **não solicita** essa permissão por conta própria: se a sua aplicação quiser esse dado, ela precisa pedir a permissão de localização ao usuário (via `navigator.geolocation` do próprio navegador) em algum momento **antes** de criar a sessão — por exemplo, ao carregar a página. Sem esse pedido prévio feito pela sua aplicação, o campo simplesmente não vem na resposta.

<Info>
  **Nem sempre o SDK consegue obter o `ssid`.** A coleta depende de conectividade no momento da inicialização e do ambiente de execução. Por isso o campo é **opcional**: quando ausente, o serviço cria a sessão normalmente, apenas sem nenhum dos três campos de enriquecimento (`deviceSignals`, `geolocation`, `ipGeolocation`).
</Info>

## Boas práticas

<AccordionGroup>
  <Accordion title="Nunca embuta a x-api-key no cliente">
    Mesmo ofuscada, qualquer chave embarcada no bundle JS pode ser extraída com ferramentas comuns (DevTools). Mantenha a chave **apenas** no seu backend, idealmente em um Secret Manager. O cliente só deve receber `sessionId` e `sessionToken`.
  </Accordion>

  <Accordion title="Use clientRequestId para idempotência">
    Gere o UUID no início do fluxo e reutilize-o em retries de rede do seu backend. Reenvios com o mesmo `(projeto, clientRequestId)` retornam a mesma sessão, evitando duplicar consumo e tokens.
  </Accordion>

  <Accordion title="Repasse o ssid quando disponível">
    Quando o SDK Web conseguir obter o `ssid`, repasse-o ao seu backend e inclua-o no `POST /api/v2/sessions`. Você recebe `deviceSignals`, `geolocation` e `ipGeolocation` em troca — úteis para regras antifraude.
  </Accordion>

  <Accordion title="Não implemente lógica de retry manual">
    Não existe mais `maxAttempts` nem retry dentro da mesma sessão. Para tentar de novo após uma falha de captura, basta chamar o SDK Web mais uma vez — ele cria uma nova sessão automaticamente.
  </Accordion>

  <Accordion title="Falhe sessões abandonadas explicitamente">
    Sessões não finalizadas expiram sozinhas por TTL, mas chamar `/fail` com um `reason` significativo melhora auditoria, reconciliação de métricas e investigação de incidentes.
  </Accordion>
</AccordionGroup>

## Próximos passos

<CardGroup cols={2}>
  <Card title="Instalação Web" icon="download" iconType="regular" href="/plataforma/liveness/facetec/v10/sdk/web/instalacao">
    Carregue o SDK via uma única tag de script, direto do CDN
  </Card>

  <Card title="Implementação Web" icon="code" iconType="regular" href="/plataforma/liveness/facetec/v10/sdk/web/implementacao">
    Inicialize o SDK com o token de sessão emitido pelo serviço
  </Card>

  <Card title="Chaves de API" icon="key" iconType="regular" href="/plataforma/chaves-de-api">
    Gere e gerencie a sua chave da Plataforma ID
  </Card>

  <Card title="Autenticação" icon="lock" iconType="regular" href="/plataforma/autenticacao-api">
    Como o header x-api-key funciona em todas as APIs
  </Card>
</CardGroup>