Debug de API: do erro 500 ao endpoint funcionando
Dia de debug na API de integração: token Bearer faltando no router, diagnóstico de 500 errors com ping endpoint e processo metódico de isolamento de problema.
Às vezes o dia inteiro gira em torno de um único problema. Hoje foi esse dia.
O symptoma: a API do kmaroteApp estava retornando 500 para chamadas externas. O erro genérico que não diz nada — pode ser qualquer coisa, desde um require_once quebrando até um header malformado.
O primeiro passo foi isolamento. Criei um endpoint de ping mínimo — sem lógica de negócio, sem dependências complexas, só uma resposta JSON simples — para confirmar que o roteamento em si estava funcionando. Quando o ping respondeu corretamente, o problema estava na camada de lógica, não na camada de roteamento.
O culpado foi encontrado: a função obter_bearer_token() estava ausente do router de API. Sem ela, qualquer chamada que dependesse de autenticação via Bearer falhava silenciosamente. Fix direto:
// funcs/api.inc.php — função que faltava no router
function obter_bearer_token(): ?string {
$header = $_SERVER['HTTP_AUTHORIZATION'] ?? '';
if (str_starts_with($header, 'Bearer ')) {
return substr($header, 7);
}
return null;
}Também adicionei verificação de file_exists antes de cada require_once no router. Se um arquivo de módulo não existe e o require_once é chamado diretamente, o PHP lança um erro fatal que não é capturado graciosamente. Pequeno detalhe, mas que faz diferença quando o ambiente tem módulos opcionais.
O dia foi longo — a sessão principal rodou das 00:00 às 15:27, uma continuação de madrugada. É o tipo de problema que você não larga até resolver.
À noite, pausa do código: revisar o perfil profissional e refletir sobre padrões de comunicação. Às vezes o trabalho mais importante não é no terminal.