Status da Plataforma (Health Check)

O endpoint de Health Check fornece uma visão em tempo real sobre o estado operacional da plataforma SantoID. Utilize este recurso para monitorar proativamente a disponibilidade dos nossos serviços e construir aplicações mais robustas e resilientes.

A verificação agrega o status de diversas funcionalidades, como Tipificação, OCR, Face Match e Prova de vida, e consolida tudo em uma única resposta.

Autenticação

Este endpoint requer autenticação via Bearer Token. O token JWT deve ser enviado no cabeçalho Authorization.

info

Para mais detalhes sobre como gerar seu token, veja: Autenticação

Requisição HTTP

Para consultar o status atual da plataforma, envie uma requisição GET para o seguinte endpoint, incluindo seu token de autenticação.

    GET https://api.santoid.com.br/api/v1/status
    Authorization: Bearer SEU_TOKEN_JWT_AQUI

Entendendo a Resposta

A resposta JSON contém dois campos principais: status e checks.

Campo	Descrição
status	string O status consolidado de toda a plataforma. Este deve ser o principal campo a ser monitorado. Os valores possíveis são: UP, DEGRADED, DOWN.
checks	array Uma lista detalhando o status de cada serviço principal disponível publicamente. Serviços internos ou de infraestrutura crítica não são expostos aqui.

Status Possíveis

• UP: Todos os sistemas estão operando normalmente.
• DEGRADED: A plataforma está operacional, mas uma ou mais funcionalidades não críticas estão com performance limitada ou indisponíveis. Sua aplicação pode continuar operando, mas talvez com algumas funcionalidades afetadas.
• DOWN: A plataforma está enfrentando uma instabilidade crítica que afeta a maioria dos serviços. É recomendado pausar as requisições até que o status retorne para UP.

---

✅ Status: UP (Tudo Operacional)

{
    "status": "UP",
    "checks": [
        {
            "Name": "Face Match",
            "Status": "UP",
            "Message": "OK"
        },
        {
            "Name": "Prova de vida",
            "Status": "UP",
            "Message": "OK"
        },
        {
            "Name": "Ocr",
            "Status": "UP",
            "Message": "OK"
        },
        {
            "Name": "Tipificação",
            "Status": "UP",
            "Message": "OK"
        }
    ]
}

⚠️ Status: DEGRADED (Operação Limitada)

Ainda retorna HTTP 200 OK, mas indica que uma funcionalidade específica (neste caso, o OCR) está com problemas em suas dependências.

{
    "status": "DEGRADED",
    "checks": [
        {
            "Name": "Face Match",
            "Status": "UP",
            "Message": "OK"
        },
        {
            "Name": "Prova de vida",
            "Status": "UP",
            "Message": "OK"
        },
        {
            "Name": "Ocr",
            "Status": "DEGRADED",
            "Message": "Funcionalidade limitada. Falha nos subserviços: Ocr para modelos Gen AI"
        },
        {
            "Name": "Tipificação",
            "Status": "UP",
            "Message": "OK"
        }
    ]
}

🚫 Status: DOWN (Falha Crítica)

Retorna HTTP 503 Service Unavailable. Isso ocorre quando um serviço essencial da plataforma está indisponível, impactando todos os outros.

{
    "status": "DOWN",
    "checks": [
        {
            "Name": "Face Match",
            "Status": "DOWN",
            "Message": "Indisponível devido a falha em dependência crítica: Serviço de entrega do processamento"
        },
        {
            "Name": "Prova de vida",
            "Status": "DOWN",
            "Message": "Indisponível devido a falha em dependência crítica: Serviço de entrega do processamento"
        },
        {
            "Name": "Ocr",
            "Status": "DOWN",
            "Message": "Indisponível devido a falha em dependência crítica: Serviço de entrega do processamento"
        },
        {
            "Name": "Tipificação",
            "Status": "DOWN",
            "Message": "Indisponível devido a falha em dependência crítica: Serviço de entrega do processamento"
        }
    ]
}

Melhores Práticas de Monitoramento

1. Frequência de Polling: Evite fazer requisições em um intervalo muito curto. Recomendamos verificar o status a cada 180 segundos para não sobrecarregar seu sistema.
2. Foco no status: Sua lógica de monitoramento deve primariamente reagir ao status. A lista Checks é mais útil para depuração e registro de logs.
3. Implemente um Circuit Breaker: 💡 Dica profissional: Se o status for DOWN, sua aplicação deve entrar em um estado de "circuito aberto" e pausar o envio de novas requisições à API SantoID por um período, retomando apenas quando o status voltar para UP.
4. Logs Informativos: Em caso de status DEGRADED ou DOWN, utilize o campo Message dos Checks para enriquecer seus logs de monitoramento, facilitando a identificação da causa raiz.