> For the complete documentation index, see [llms.txt](https://docs.barte.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.barte.com/banking/api/abertura-de-contas-v2/biometric-sessions.md).

# Sessões Biométricas

Os endpoints de sessões biométricas são agnósticos ao tipo de conta — funcionam tanto para contas PJ quanto para contas PF. O `{id}` é sempre o UUID da conta, independente do tipo.

O GET retorna **todas** as sessões da conta: uma por entidade. Contas PJ podem ter múltiplas sessões (uma por sócio e por representante legal); contas PF têm apenas uma (o próprio titular).

> As notificações de aprovação de **KYC** e de **biometria** chegam como dois eventos separados (em desenvolvimento).

***

## GET /v2/accounts/{id}/biometric-sessions

Retorna todas as sessões biométricas da conta, incluindo sessões com status `EXPIRED` ou `REPROVED`. Use o `biometricUrl` de cada entidade para enviar o link de biometria facial ao respectivo indivíduo.

> O link tem validade de **72 horas**. Após expirar, utilize o endpoint de [refresh](#post-v2accountsidbiometric-sessionsrefresh).

**Path Parameters:**

| Parâmetro | Tipo | Descrição             |
| --------- | ---- | --------------------- |
| `id`      | UUID | ID da conta (UUID v4) |

**Query Parameters:**

| Parâmetro  | Tipo   | Obrigatório | Descrição                                                                             |
| ---------- | ------ | ----------- | ------------------------------------------------------------------------------------- |
| `document` | String | Não         | CPF da entidade. Quando informado, retorna apenas a sessão da entidade correspondente |

**Request — todas as sessões:**

```bash
curl --request GET \
  --url 'https://api-banking.barte.com/v2/accounts/f47ac10b-58cc-4372-a567-0e02b2c3d479/biometric-sessions' \
  --cert client.pem \
  --key client-key.pem \
  --header 'Authorization: Bearer {token}' \
  --header 'X-Seller-Id: 12345'
```

**Response — 200 OK:**

```json
[
  {
    "document": "12345678900",
    "personType": "INDIVIDUAL",
    "role": ["SHAREHOLDER"],
    "sessionStatus": "IN_ANALYSIS",
    "biometricUrl": "https://biometria.provider.com/session/abc123?token=...",
    "expiresAt": "2026-01-31T15:30:00Z"
  },
  {
    "document": "98765432100",
    "personType": "INDIVIDUAL",
    "role": ["LEGAL_REPRESENTATIVE", "ATTORNEY_IN_FACT"],
    "sessionStatus": "CREATED",
    "biometricUrl": "https://biometria.provider.com/session/def456?token=...",
    "expiresAt": "2026-01-31T15:30:00Z"
  }
]
```

**Request — filtrado por entidade (`?document`):**

```bash
curl --request GET \
  --url 'https://api-banking.barte.com/v2/accounts/f47ac10b-58cc-4372-a567-0e02b2c3d479/biometric-sessions?document=12345678900' \
  --cert client.pem \
  --key client-key.pem \
  --header 'Authorization: Bearer {token}' \
  --header 'X-Seller-Id: 12345'
```

**Response — 200 OK:**

```json
[
  {
    "document": "12345678900",
    "personType": "INDIVIDUAL",
    "role": ["SHAREHOLDER"],
    "sessionStatus": "IN_ANALYSIS",
    "biometricUrl": "https://biometria.provider.com/session/abc123?token=...",
    "expiresAt": "2026-01-31T15:30:00Z"
  }
]
```

### Campos — BiometricSessionResponse

| Campo           | Tipo           | Descrição                                                                                                                                                                                                      |
| --------------- | -------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `document`      | String         | CPF da entidade                                                                                                                                                                                                |
| `personType`    | String         | Tipo da pessoa: `INDIVIDUAL` (pessoa física) ou `BUSINESS` (pessoa jurídica)                                                                                                                                   |
| `role`          | Array\<String> | Papéis da entidade na conta. Uma entidade pode acumular mais de um papel. Valores possíveis: `SHAREHOLDER`, `LEGAL_REPRESENTATIVE`, `ATTORNEY_IN_FACT`, `REPRESENTATIVE_FOREIGN`, `TUTOR`, `EMANCIPATED_MINOR` |
| `sessionStatus` | String         | Status da sessão biométrica (ver tabela abaixo)                                                                                                                                                                |
| `biometricUrl`  | String         | Link para a entidade completar a biometria facial                                                                                                                                                              |
| `expiresAt`     | String         | Timestamp de expiração do link em UTC (ISO 8601). TTL: 72h.                                                                                                                                                    |

### Status da Sessão Biométrica

| Status        | Descrição                                            |
| ------------- | ---------------------------------------------------- |
| `CREATED`     | Sessão criada, aguardando início                     |
| `IN_ANALYSIS` | Em análise                                           |
| `APPROVED`    | Biometria aprovada                                   |
| `REPROVED`    | Biometria reprovada                                  |
| `EXPIRED`     | Token expirado (TTL: 72h), use o endpoint de refresh |

**Status Codes:**

| Status             | Descrição                      |
| ------------------ | ------------------------------ |
| `200 OK`           | Sessões retornadas com sucesso |
| `401 Unauthorized` | Token inválido ou expirado     |
| `403 Forbidden`    | Conta não pertence ao parceiro |
| `404 Not Found`    | Conta não encontrada           |

***

## POST /v2/accounts/{id}/biometric-sessions/retry

Cria uma nova sessão biométrica para uma entidade após reprovação. Retorna um novo `biometricUrl` válido por 72 horas.

**Path Parameters:**

| Parâmetro | Tipo | Descrição             |
| --------- | ---- | --------------------- |
| `id`      | UUID | ID da conta (UUID v4) |

**Request:**

```bash
curl --request POST \
  --url 'https://api-banking.barte.com/v2/accounts/f47ac10b-58cc-4372-a567-0e02b2c3d479/biometric-sessions/retry' \
  --cert client.pem \
  --key client-key.pem \
  --header 'Authorization: Bearer {token}' \
  --header 'Content-Type: application/json' \
  --header 'X-Seller-Id: 12345' \
  --data '{
    "document": "12345678900"
  }'
```

### Campos — Request

| Campo      | Tipo   | Obrigatório | Descrição                                    |
| ---------- | ------ | ----------- | -------------------------------------------- |
| `document` | String | Sim         | CPF da entidade que irá retentar a biometria |

**Response — 202 Accepted:**

```json
{
  "document": "12345678900",
  "biometricUrl": "https://biometria.provider.com/session/xyz789?token=...",
  "expiresAt": "2026-01-31T18:00:00Z"
}
```

### Campos — BiometricRenewalResponse

| Campo          | Tipo   | Descrição                                                   |
| -------------- | ------ | ----------------------------------------------------------- |
| `document`     | String | CPF da entidade                                             |
| `biometricUrl` | String | Novo link para completar a biometria facial                 |
| `expiresAt`    | String | Timestamp de expiração do link em UTC (ISO 8601). TTL: 72h. |

**Response — 404 Not Found:**

```json
{
  "errors": [
    {
      "code": "BNK-0040",
      "title": "Banking flow error",
      "description": "Business account f47ac10b-58cc-4372-a567-0e02b2c3d479 not found"
    }
  ],
  "metadata": {
    "totalRecords": 1,
    "totalPages": 1,
    "requestDatetime": "2026-01-30T15:30:00Z"
  }
}
```

**Status Codes:**

| Status             | Descrição                            |
| ------------------ | ------------------------------------ |
| `202 Accepted`     | Nova sessão biométrica criada        |
| `400 Bad Request`  | Campo `document` ausente ou inválido |
| `401 Unauthorized` | Token inválido ou expirado           |
| `403 Forbidden`    | Conta não pertence ao parceiro       |
| `404 Not Found`    | Conta não encontrada                 |

***

## POST /v2/accounts/{id}/biometric-sessions/refresh

Renova o token de biometria expirado de uma entidade, sem criar nova sessão de análise. Use quando o link anterior expirou (após 72 horas) e a entidade ainda não completou a biometria.

**Path Parameters:**

| Parâmetro | Tipo | Descrição             |
| --------- | ---- | --------------------- |
| `id`      | UUID | ID da conta (UUID v4) |

**Request:**

```bash
curl --request POST \
  --url 'https://api-banking.barte.com/v2/accounts/f47ac10b-58cc-4372-a567-0e02b2c3d479/biometric-sessions/refresh' \
  --cert client.pem \
  --key client-key.pem \
  --header 'Authorization: Bearer {token}' \
  --header 'Content-Type: application/json' \
  --header 'X-Seller-Id: 12345' \
  --data '{
    "document": "12345678900"
  }'
```

### Campos — Request

| Campo      | Tipo   | Obrigatório | Descrição                                |
| ---------- | ------ | ----------- | ---------------------------------------- |
| `document` | String | Sim         | CPF da entidade cujo token será renovado |

**Response — 202 Accepted:**

```json
{
  "document": "12345678900",
  "biometricUrl": "https://biometria.provider.com/session/abc456?token=...",
  "expiresAt": "2026-01-31T20:00:00Z"
}
```

Retorna os dados no mesmo formato do retry.

**Response — 404 Not Found:**

```json
{
  "errors": [
    {
      "code": "BNK-0040",
      "title": "Banking flow error",
      "description": "Biometric token not found for document 12345678900 in account f47ac10b-58cc-4372-a567-0e02b2c3d479"
    }
  ],
  "metadata": {
    "totalRecords": 1,
    "totalPages": 1,
    "requestDatetime": "2026-01-30T15:30:00Z"
  }
}
```

**Status Codes:**

| Status             | Descrição                                |
| ------------------ | ---------------------------------------- |
| `202 Accepted`     | Token renovado, novo link gerado         |
| `400 Bad Request`  | Campo `document` ausente ou inválido     |
| `401 Unauthorized` | Token inválido ou expirado               |
| `403 Forbidden`    | Conta não pertence ao parceiro           |
| `404 Not Found`    | Conta ou token biométrico não encontrado |

***

## Códigos de Erro

| Código     | Endpoint                        | Descrição                                |
| ---------- | ------------------------------- | ---------------------------------------- |
| `BNK-0040` | GET, POST /retry, POST /refresh | Conta ou token biométrico não encontrado |


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://docs.barte.com/banking/api/abertura-de-contas-v2/biometric-sessions.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.