Health Check do Webservice

Endpoints públicos (não exigem Authorization, X-Api-Token nem X-Emp) para balanceadores de carga, orquestradores (Docker/Kubernetes) e monitoramento externo verificarem a saúde da instância.

Rota	Uso	O que valida
GET /health/	Readiness — a instância está apta a atender?	Conexão com o banco de dados, espaço em APP_DATA e modo de manutenção
GET /health/live/	Liveness — o processo PHP está de pé?	Apenas que o PHP responde (não toca no banco)

URL completa: {APP_URL}/webservice/index.php/health/.

Códigos HTTP

Código	status	Significado
200	ok	Todas as checagens passaram
200	degradado	Operacional, mas com alerta (ex.: pouco espaço em disco)
503	indisponivel	Uma dependência essencial falhou (ex.: banco de dados)
503	manutencao	Modo de manutenção ativo (parâmetro manutencao = 'S')

Detalhes restritos a administrador

Sem autenticação a resposta traz apenas o essencial. Os campos abaixo só aparecem quando a requisição está autenticada como administrador — via token de sessão de usuário com admin (Authorization: Bearer …) ou pela sessão do painel (/login/validar_admin/):

• php — versão do PHP;
• em checagens.armazenamento: livre_mb, total_mb, livre_percentual, gravavel.

O status de cada checagem (inclusive armazenamento) é sempre retornado — apenas os números de capacidade ficam ocultos.

Exemplo — GET /health/ (sem autenticação)

{
    "servico": "nextbp-webservice",
    "versao": "24.156.2",
    "status": "ok",
    "hora": "2026-09-10T15:07:15-03:00",
    "duracao_ms": 6.4,
    "checagens": {
        "banco_dados":   { "status": "ok", "duracao_ms": 3.1 },
        "armazenamento": { "status": "ok" },
        "manutencao":    { "status": "ok", "ativa": false }
    }
}

Exemplo — GET /health/ (autenticado como administrador)

{
    "servico": "nextbp-webservice",
    "versao": "24.156.2",
    "php": "8.1.18",
    "status": "ok",
    "hora": "2026-09-10T15:07:15-03:00",
    "duracao_ms": 6.4,
    "checagens": {
        "banco_dados":   { "status": "ok", "duracao_ms": 3.1 },
        "armazenamento": {
            "status": "ok",
            "livre_mb": 45123,
            "total_mb": 102400,
            "livre_percentual": 44.1,
            "gravavel": true
        },
        "manutencao": { "status": "ok", "ativa": false }
    }
}

Exemplo — GET /health/live/

{
    "servico": "nextbp-webservice",
    "versao": "24.156.2",
    "status": "ok",
    "hora": "2026-09-10T15:07:15-03:00"
}

Limiares de armazenamento

O status vira degradado quando o espaço livre em APP_DATA fica abaixo de 512 MB ou de 5% do total. Constantes em controller/Health.controller.php: ARMAZENAMENTO_MINIMO_BYTES e ARMAZENAMENTO_MINIMO_PERCENTUAL.

Docker

A imagem publicada (bp_build/dockerfile) já declara:

HEALTHCHECK --interval=30s --timeout=5s --start-period=40s --retries=3 \
    CMD curl -fsS http://localhost/webservice/index.php/health/ || exit 1