> For the complete documentation index, see [llms.txt](https://docs.facephi.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.facephi.com/docs.facephi-pt-br/sdks/backend-sdk/selphid/release_notes/6.22.0_releasenotes.md).

# 6.22.0

Esta versão adiciona ao serviço Rest Api dois novos endpoints de métricas operacionais, que permitem monitorar o estado do serviço (tráfego, latência, saturação, saúde do SDK, qualidade dos resultados e alertas) e integrá-lo a sistemas de monitoramento baseados em Prometheus.

Também foi adicionado suporte opcional à autenticação JWT nos endpoints do serviço Rest Api. Ela fica desabilitada por padrão e é habilitada na inicialização do serviço.

Além disso, `/api/v1/selphid/health` passa a responder com `503 Service Unavailable` quando o SDK não está disponível, para que as sondas dos contêineres detectem a falha, e `POST /api/v1/selphid/config` responde com `400 Bad Request`, pois a configuração do serviço não pode ser alterada durante a execução.

Por outro lado, a versão mínima da glibc do SDK on-premise para Linux passa de 2.27 para 2.28, em conformidade com os sistemas Red Hat 8 (glibc 2.28) que continuam em produção.

Por fim, foi corrigido o reconhecimento do valor `Timeout` do campo `reason` nos endpoints de finalização de Custom Events, e a inicialização do servidor de licenças `selphid-license-server` quando o caminho de instalação contém espaços.

### Adicionado

* Novos endpoints de métricas operacionais do serviço Rest Api:
  * `/api/v1/selphid/metrics`: instantâneo em formato JSON com tráfego, latência, saturação, estado de saúde do SDK, qualidade agregada das extrações, autenticações faciais e testes de vida passivos, além de alertas ativos.
  * `/api/v1/selphid/metrics/prometheus`: o mesmo estado operacional no formato de exposição de texto do Prometheus.
  * Assim como `/api/v1/selphid/health` e `/api/v1/selphid/version`, são endpoints públicos: não exigem JWT, mesmo quando a autenticação está habilitada.
  * São configurados na inicialização com `metrics_enabled` e os limites de classificação `metrics_*`, a partir de `config.json` ou por meio das variáveis de ambiente `FACEPHI_SELPHID_REST_METRICS_*`. Consulte [Métricas operacionais](https://docs.facephi.com/docs.facephi-pt-br/sdks/backend-sdk/selphid/installation/installation_instructions_service.md).
* Suporte opcional à autenticação JWT (HS256) nos endpoints do serviço Rest Api:
  * Desabilitada por padrão. É habilitada na inicialização a partir de `config.json` ou por meio das variáveis de ambiente `FACEPHI_SELPHID_REST_AUTH_*`. Consulte [Variáveis de ambiente](https://docs.facephi.com/docs.facephi-pt-br/sdks/backend-sdk/selphid/installation/kubernetes_deployment.md#24-variables-de-entorno) e [Autenticação JWT](https://docs.facephi.com/docs.facephi-pt-br/sdks/backend-sdk/selphid/installation/installation_instructions_service.md).
  * O token é enviado no cabeçalho `Authorization: Bearer <token>` ou em um cabeçalho configurável (por padrão `x-api-key`), e deve incluir uma claim `exp` válida.
  * Os endpoints `/api/v1/selphid/health`, `/api/v1/selphid/version`, `/api/v1/selphid/metrics` e `/api/v1/selphid/metrics/prometheus`, e as requisições `OPTIONS`, são públicas.

### Alterado

* Versão mínima da glibc no SDK on-premise do Linux: de 2.27 para 2.28 (Ubuntu 18.10, Red Hat 8 e sistemas compatíveis). O Ubuntu 18.04 (glibc 2.27) deixa de ter suporte.
* `/api/v1/selphid/health` responde `503 Service Unavailable` quando o SDK não está disponível (antes, `200` com `Unhealthy`). Sua resposta `200` agora inclui o estado detalhado do SDK (`initialized` e `sdk`).
* `POST /api/v1/selphid/config` sempre responde `400 Bad Request` (antes, `200` sem aplicar nenhuma alteração).

### Corrigido

* O valor `Timeout` do campo `reason` não era reconhecido nos endpoints de finalização de Custom Events:
  * `/api/v1/selphid/custom-event/authentication/finish`
  * `/api/v1/selphid/custom-event/onboarding/finish`
  * `/api/v1/selphid/custom-event/ocr/finish`
  * `/api/v1/selphid/custom-event/security/finish`
  * `/api/v1/selphid/custom-event/liveness/finish`
  * `/api/v1/selphid/custom-event/voice/authentication/finish`
* O servidor de licenças `selphid-license-server` não conseguia iniciar quando o caminho de instalação continha espaços (Windows e Linux).

### Atualizações do contrato da API

Foram adicionados dois novos endpoints `GET` ao contrato da API REST. Eles são públicos: não exigem JWT mesmo quando a autenticação está habilitada.

* `/api/v1/selphid/metrics`
* `/api/v1/selphid/metrics/prometheus`

Exemplo (abreviado) da resposta de `/api/v1/selphid/metrics`:

```json
{
  "schemaVersion": "1.0",
  "timestamp": "2026-10-21T10:00:00Z",
  "service": {
    "name": "facephi-selphid-service",
    "version": "6.22.0",
    "pathBase": "/api/v1/selphid",
    "uptimeSeconds": 3600,
    "configuredThreads": 8
  },
  "state": {
    "initialized": true,
    "classification": "ok",
    "sdk": { "healthy": true, ... }
  },
  "traffic": { "totals": { "requests": 1520, "success": 1500, ... }, "windows": { ... }, "byEndpoint": [ ... ] },
  "latency": { "windows": { "1m": { ... }, "5m": { ... }, "15m": { ... } } },
  "saturation": { "inflight": 1, "configuredThreads": 8, ... },
  "usage": { ... },
  "quality": { ... },
  "alerts": [ ... ]
}
```

O endpoint `/api/v1/selphid/metrics/prometheus` retorna o mesmo estado operacional no formato de exposição de texto do Prometheus: primeiro as séries próprias do serviço, com o prefixo `facephi_selphid_` (por exemplo, `facephi_selphid_state_classification` ou `facephi_selphid_alert_active`), e depois as séries de nível HTTP, como `facephi_request_success_total`, `facephi_inflight_requests` ou `facephi_queue_latency_ms`.

Por outro lado, quando a autenticação JWT está habilitada, todos os endpoints, exceto `health`, `version`, `metrics`, `metrics/prometheus` e as solicitações `OPTIONS` exigem um token válido. Se o token não for enviado ou não for válido, o serviço responde `401 Unauthorized`, com o cabeçalho `WWW-Authenticate: Bearer`:

```json
{
  "status": 401,
  "error": "Unauthorized",
  "message": "Missing authentication token",
  "timeStamp": "2026-10-21T10:00:00Z"
}
```

`message` indica o motivo: `Missing authentication token`, `JWT token is expired`, `JWT token is not yet valid`, `JWT token does not include exp claim`, `JWT token validation failed` ou `Authentication secret is not configured`.

Com a autenticação desabilitada (valor padrão), o contrato dos demais endpoints não muda por esse motivo.

O endpoint `/api/v1/selphid/health` muda sua resposta. Quando o SDK está disponível, responde `200` com o estado detalhado do SDK:

```json
{
  "message": "Healthy",
  "initialized": true,
  "sdk": {
    "healthy": true,
    "initialized": true,
    "lastInitStatus": "OK",
    "lastHealthKnown": true,
    "lastHealthCheckAt": "2026-10-21T10:00:00Z",
    "lastError": ""
  }
}
```

Quando o SDK não está disponível, já não responde `200` com `"message": "Unhealthy"`, mas sim `503 Service Unavailable`, com `message` igual a `SDK health check failed` ou `SelphID SDK is not initialized`:

```json
{
  "status": 503,
  "error": "ServiceUnavailable",
  "message": "SDK health check failed",
  "timeStamp": "2026-10-21T10:00:00Z"
}
```

Por fim, `POST /api/v1/selphid/config` já não responde `200` com `"message": "The configuration has been set."`, pois nunca aplicava nenhuma alteração. Agora responde sempre `400 Bad Request`, com uma `message` que indica o motivo: `JWT auth settings are not accessible from the config endpoint` se o corpo incluir chaves de autenticação JWT, uma mensagem de corpo inválido se o corpo não for um objeto JSON, ou `Runtime configuration updates are not supported. Configure the service through config.json or the FACEPHI_SELPHID_REST_* environment variables before starting it` nos demais casos.
