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

# Obter sessão biométrica atual

> Recupera a sessão biométrica embarcada mais recente de uma entidade — mesmo padrão de GET /api/kyc/entities/:entityId/current para validações KYC.

## Visão geral

Este endpoint retorna a **sessão biométrica mais recente** de uma entidade (por `createdAt`), **independente do status**: `pending`, `in_progress`, `approved`, `rejected`, etc.

É o equivalente biométrico de `GET /api/kyc/entities/{entityId}/current` para validações KYC.

<Note>
  Se a entidade nunca teve sessão biométrica, a API responde **`200` com `null`** (não 404), igual ao endpoint KYC atual.
</Note>

## Quando usar

* **Recuperar uma sessão pendente** para reembarcar o `sessionUrl` ou cancelá-la
* **Consultar o status** da última tentativa biométrica (`status`, `rejectionCode`, `decision`)
* **Resolver `ACTIVE_SESSION_EXISTS`** ao criar nova sessão: o `id` da sessão ativa está neste endpoint (ou em `activeSessionId` no erro 409)

## Solicitação

```
GET https://api.gu1.ai/api/kyc/biometric/entities/{entityId}/current
```

### Cabeçalhos

```json theme={null}
{
  "Authorization": "Bearer SUA_API_KEY",
  "X-Organization-ID": "uuid-da-sua-organizacao"
}
```

## Resposta

### 200 OK — sessão encontrada

```json theme={null}
{
  "id": "7618e10c-b1b1-408b-b361-1901077ced73",
  "entityId": "c16b457b-500a-4250-aefe-6d69bdf71fb2",
  "organizationId": "org-uuid",
  "status": "pending",
  "mode": "face_match",
  "sessionUrl": "https://kyc.example.com/session/abc123",
  "hostedSessionId": "e291f904-9c3f-490e-a51e-73434a14ba9a",
  "iframeAllow": "camera; microphone; fullscreen; autoplay; encrypted-media",
  "rejectionCode": null,
  "rejectionMessage": null,
  "createdAt": "2026-06-19T14:40:00.000Z",
  "updatedAt": "2026-06-19T14:40:00.000Z",
  "completedAt": null
}
```

### 200 OK — sem sessões

```json theme={null}
null
```

## Fluxo recomendado

1. `POST /api/kyc/biometric/sessions` → guardar `id` e `sessionUrl`
2. Embarcar `sessionUrl` em iframe
3. Polling: `GET /api/kyc/biometric/entities/{entityId}/current` ou `GET /api/kyc/biometric/sessions/{id}`
4. Para reiniciar: `POST /api/kyc/biometric/sessions/{id}/cancel` (apenas `pending` / `in_progress`)

## Diferença do `currentSessionId` na listagem

`GET /api/kyc/biometric/sessions?entityId=...` inclui `currentSessionId`: a última sessão **`approved`** (verificação biométrica vigente). Este `/current` retorna a **última sessão criada**, que pode estar `pending`.

| Campo / endpoint                     | Significado                            |
| ------------------------------------ | -------------------------------------- |
| `GET .../entities/:entityId/current` | Última sessão criada (qualquer status) |
| `currentSessionId` na listagem       | Última sessão **aprovada**             |

## Erro ao criar segunda sessão

Se tentar criar outra sessão com uma ativa (`pending` / `in_progress`), recebe `409 ACTIVE_SESSION_EXISTS` com o ID bloqueante:

```json theme={null}
{
  "error": "ACTIVE_SESSION_EXISTS",
  "message": "Cannot create new biometric session. There is already a pending session for this entity. Please cancel or complete the existing session first.",
  "activeSessionId": "7618e10c-b1b1-408b-b361-1901077ced73"
}
```

Cancele com `POST /api/kyc/biometric/sessions/{activeSessionId}/cancel` e crie novamente.

## Relacionados

* [Sessão biométrica embarcada](/pt/use-cases/kyc/embedded-biometric) — criar sessão
* [Eventos webhook biométricos](/pt/webhooks/events/biometric-events)