---
title: "Identificação facial (1:N Identification)  - Rest PKI Core"
description: "Identificação facial 1:N no Rest PKI Core: busca o rosto capturado em uma base de cadastros para descobrir a quem pertence. Pode não estar habilitada."
canonical: "https://docs.lacunasoftware.com/articles/rest-pki/core/integration/bio-sessions/identification"
locale: "pt-BR"
product: "Rest PKI Core"
last_updated: "2026-10-12"
---

# Identificação facial (1:N Identification)  - Rest PKI Core

 - Busca o rosto capturado em uma base de cadastros para descobrir a quem ele pertence.
 - Ao contrário da autenticação, não parte de um usuário conhecido

> **Observação**
>
> A identificação facial é um processo computacionalmente custoso, também conhecido como **busca 1:N**.
> Dessa forma, pode acontecer que esse recurso não esteja habilitado na instância em que você esteja realizando a integração.
> Caso tenha interesse em habilitar esse recurso, **entre em contato conosco** via [suporte@lacunasoftware.com](mailto:suporte@lacunasoftware.com) para solicitar uma **demonstração**.

## Criação da sessão

Para criar uma sessão de identificação, pode-se utilizar o método `StartIdentificationSessionAsync` das ClientLibs, passando como parâmetro `StartBioIdentificationSessionRequest`.

Esse método realiza uma requisição `POST` para a rota `/api/bio/sessions/identification` [(Swagger)](https://core.pki.rest/swagger/index.html#operations-BioSessions-post_api_bio_sessions_identification).

### Parâmetros (`StartBioIdentificationSessionRequest`)
| **Parâmetro**                     | **Obrigatório?** | **Tipo** | **Descrição** |
| --------------------------------- | ---------------- | -------- | ------------- |
| **ReturnUrl**                     | Condicional*     | String   | URL para redirecionar o usuário após a biometria. [(veja mais detalhes)](https://docs.lacunasoftware.com/articles/rest-pki/core/integration/bio-sessions#fluxo-de-redirecionamento-returnurl)
| **TrustedOrigin**                 | Condicional*     | String   | URL do seu site onde o Widget está incorporado. [(veja mais detalhes)](https://docs.lacunasoftware.com/articles/rest-pki/core/integration/bio-sessions#fluxo-incorporado-widgettrustedorigin)
| **PlatformPreference**            | Não              | Enum     | Define a preferência de plataforma e configuração do QRCode. [(veja mais detalhes)](https://docs.lacunasoftware.com/articles/rest-pki/core/integration/bio-sessions#parâmetros-gerais)
| **FaceCaptureProvider**           | Não              | Enum     | Define o provedor de biometria. [(veja mais detalhes)](https://docs.lacunasoftware.com/articles/rest-pki/core/integration/bio-sessions#parâmetros-das-sessões-com-captura-facial)

> **Dica**
>
> *Você deve informar pelo menos um dos dois parâmetros: [Veja a diferença entre ReturnUrl e TrustedOrigin](https://docs.lacunasoftware.com/articles/rest-pki/core/integration/bio-sessions#fluxos-de-frontend)
> - `ReturnUrl` (para redirecionamento) 
> - `TrustedOrigin` (para widget)

> Os parâmetros não obrigatórios podem ser deixados em branco (`null`) e serão automaticamente preenchidos pelos padrões do sistema.

### Exemplo de resposta da requisição:

```json
{
  "sessionType": "Identification",
  "sessionId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "sessionUrl": "string"
}
```

### Integração do Frontend
Uma vez que o seu backend obteve a `sessionUrl` da API, você deve encaminhá-la para o seu frontend. A partir daí, o fluxo segue de acordo com a sua escolha de interface:

- **Fluxo Incorporado (Widget)**: Sua aplicação passa a URL para o componente Javascript inicializar a captura dentro da sua página.

- **Fluxo de Redirecionamento**: Sua aplicação direciona o usuário para o link recebido, onde a captura ocorrerá.

> **Dica**
>
> Em caso de dúvidas sobre a implementação de cada modelo, consulte nossa documentação de [Fluxos de FrontEnd](https://docs.lacunasoftware.com/articles/rest-pki/core/integration/bio-sessions#fluxos-de-frontend).

---

## Completando a sessão

Para concluir uma sessão de identificação, pode-se utilizar o método `CompleteIdentificationSessionAsync` das ClientLibs, passando como parâmetro `CompleteBioSessionRequest`.

Esse método realiza uma requisição `POST` para a rota `/api/bio/sessions/identification/completion` [(Swagger)](https://core.pki.rest/swagger/index.html#operations-BioSessions-post_api_bio_sessions_identification_completion).

Este método é o ponto final. O ticket pode ser usado apenas uma vez.

> **Dica**
>
> Utilize o Complete apenas ao final do processo, enviando o Ticket recebido para validar o resultado e encerrar a sessão.

### Exemplo de resposta da requisição:

```JSON
{
  "identifiedSubjectId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "identifiedSubjectIdentifier": "string",
  "failure": "CaptureFailed",
  "sessionId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "success": true,
  "resultDataAvailable": true
}
```

#### Detalhes dos campos:

* **identifiedSubjectId**: Em caso de sucesso, é preenchido com o Id do cadastro da pessoa identificada.
* **identifiedSubjectIdentifier**: Em caso de sucesso, é preenchido com o `SubjectIdentifier` da pessoa identificada.
* **failure**: Informa se houve alguma falha ao realizar a sessão, consulte a lista de falhas.
* **sessionId**: ID da sessão do RestPKICore.
* **success**: Informa se a sessão de identificação foi bem-sucedida.
* **resultDataAvailable**: Se true, indica que você pode buscar as fotos coletadas na sessão.

#### Failures

| **Enum**                          | **Descrição**                                      |
| --------------------------------- | -------------------------------------------------- |
| CaptureFailed                     | A captura da imagem não pôde ser finalizada. Geralmente ocorre por interrupção do usuário.
| LivenessFailed                    | O usuário não passou no teste de Prova de Vida. O número de tentativas excedeu o excedeu o limite.
| NoMatch                           | Não houve correspondência mínima entre a biometria coletada e as biometrias cadastradas na base.
| BadImage                          | A imagem capturada não possui qualidade suficiente para processamento. Pode ser causada por baixa iluminação ou desfoque (blur).

## Consultando o status

Você pode consultar o estado atual de uma sessão a qualquer momento utilizando o seu `sessionId`. Isso é útil para monitorar se o usuário já iniciou ou expirou a sessão antes mesmo de ela ser concluída.

> **Dica**
>
> Utilize o `GetIdentificationSessionStatusAsync` para acompanhar o progresso de uma sessão ativa através do seu SessionId

O resultado da requisição para esse endpoint é exatamente igual ao [exemplo de retorno da requisição CompleteIdentificationSessionAsync](https://docs.lacunasoftware.com/articles/rest-pki/core/integration/bio-sessions/identification#exemplo-de-resposta-da-requisição-1).