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.

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:

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:

[
  {
    "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):

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:

[
  {
    "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
CAPTURE_COMPLETED	Captura concluída, aguardando análise
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:

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:

{
  "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:

{
  "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:

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:

{
  "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:

{
  "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