Definição
Healthcheck de API é uma verificação automática, geralmente feita por um endpoint específico, que informa se uma API está funcionando e pronta para receber requisições. Em integrações fiscais, ajuda o sistema do cliente a saber, antes de emitir uma nota, se o serviço e suas dependências estão disponíveis, evitando falhas e filas paradas.
Também conhecido como: API health check, Health check, Verificação de saúde da API, Checagem de disponibilidade, Endpoint de status, Health endpoint
O que é um healthcheck de API?
Healthcheck, ou verificação de saúde, é uma checagem simples que responde à pergunta: esta API está no ar e funcionando? Normalmente existe um endereço próprio para isso, como /health ou /status, que devolve uma resposta curta indicando se o serviço está saudável.
A resposta costuma usar um código HTTP, como 200 quando tudo está bem ou 503 quando o serviço está indisponível. Às vezes também traz detalhes, como o estado do banco de dados ou de serviços externos dos quais a API depende.
Para que serve o healthcheck em uma API fiscal?
Na emissão fiscal, uma nota que não é emitida pode travar uma venda, um faturamento ou a saída de uma carga. O healthcheck permite que o ERP, a plataforma de vendas ou o marketplace descubram rapidamente se a API está disponível antes de enviar documentos ou durante a operação.
Com essa informação, o sistema pode decidir o que fazer: seguir normalmente, segurar os envios em uma fila, acionar um plano alternativo ou avisar a equipe técnica. Isso reduz erros repetidos e torna a integração mais previsível.
Como funciona um healthcheck na prática?
Um monitor ou o próprio sistema do cliente faz chamadas periódicas ao endpoint de saúde, por exemplo a cada minuto. Se a resposta demorar demais ou vier com erro, o monitor registra o problema e pode disparar um alerta.
Existem dois níveis comuns. O mais básico confirma apenas que a aplicação responde. O mais completo verifica também dependências, como banco de dados, filas de processamento e conexão com os órgãos autorizadores, como SEFAZ e prefeituras.
Qual a diferença entre a API estar no ar e a emissão estar funcionando?
A API pode responder normalmente e, mesmo assim, uma SEFAZ ou prefeitura específica estar fora do ar. Nesse caso, a plataforma de emissão recebe o pedido, mas a autorização do documento depende do órgão externo.
Por isso, um healthcheck de API não substitui o acompanhamento do status de cada documento. Ele indica a saúde do serviço de integração, enquanto o status do documento mostra se aquela nota específica foi autorizada, rejeitada ou continua em processamento.
Quais cuidados tomar ao usar healthchecks?
Não é preciso consultar o endpoint de saúde a cada segundo, pois chamadas excessivas podem esbarrar no limite de requisições e não trazem ganho real. Um intervalo regular e moderado costuma ser suficiente.
Também é importante combinar o healthcheck com outras práticas: timeout bem definido, retry com backoff exponencial, idempotência para evitar notas duplicadas e logs que permitam investigar o que aconteceu durante uma instabilidade.
Exemplos de Healthcheck de API
- Um ERP consulta o endpoint de saúde da API fiscal a cada minuto e, ao receber erro 503 três vezes seguidas, pausa o envio de NF-e e passa a acumular os pedidos em uma fila interna.
- Uma equipe de infraestrutura configura um painel de monitoramento que mostra em verde ou vermelho a disponibilidade da API de emissão e envia alerta quando a resposta ultrapassa o tempo esperado.
- Antes de iniciar o faturamento em lote do fim do mês, um marketplace verifica o healthcheck da API para confirmar que o serviço está disponível e evitar centenas de falhas seguidas.
- Uma empresa de transporte usa o healthcheck para diferenciar uma falha da própria integração de uma instabilidade momentânea no órgão autorizador do CT-e e do MDF-e.
Perguntas frequentes
Healthcheck é a mesma coisa que monitoramento?
Não exatamente. O healthcheck é uma das ferramentas de monitoramento: uma checagem pontual de disponibilidade. O monitoramento completo também inclui métricas de latência, logs, rastreamento de requisições e alertas, compondo a observabilidade da API.
Se o healthcheck estiver OK, minha nota será autorizada?
Não necessariamente. Ele indica que a API está funcionando, mas a autorização depende dos dados enviados e da disponibilidade do órgão autorizador. Rejeições por erro de validação, por exemplo, podem ocorrer mesmo com a API saudável.
Com que frequência devo chamar o healthcheck?
Depende da criticidade da operação, mas intervalos de alguns segundos a um minuto são comuns. Evite chamadas excessivas, que consomem recursos e podem atingir limites de requisições sem melhorar a detecção de falhas.
O healthcheck precisa de autenticação?
Depende do provedor. Alguns endpoints de saúde são públicos e mostram apenas se o serviço responde; outros exigem token por exibirem detalhes internos. Consulte a documentação da API utilizada.
Atualizado em · Como produzimos este glossário