A API respondeu 200, você jogou o corpo no json_decode() e recebeu null. Nenhum warning, nenhuma exception, nenhuma pista. O json_decode() é silencioso por padrão: quando o JSON está quebrado ele devolve null e guarda o motivo num canto que quase ninguém consulta.
Primeiro: pergunte o motivo
Antes de sair mexendo no endpoint, leia o erro que o PHP já tem guardado:
$dados = json_decode($resposta, true);
if ($dados === null && json_last_error() !== JSON_ERROR_NONE) {
error_log('JSON quebrado: ' . json_last_error_msg());
error_log('primeiros 200 bytes: ' . substr($resposta, 0, 200));
}
Repare na comparação dupla. A string null é JSON válido e decodifica para null também, então testar só === null confunde resposta vazia com resposta corrompida. Quem decide é o json_last_error().
Depois: force o PHP a gritar
No PHP 8.3 eu nem escrevo mais aquele if. Passo a flag e trato o problema como qualquer outro erro da aplicação:
try {
$dados = json_decode($resposta, true, 512, JSON_THROW_ON_ERROR);
} catch (JsonException $e) {
error_log('decode falhou: ' . $e->getMessage());
throw new RuntimeException('Resposta inválida do fornecedor', 0, $e);
}
Detalhe que já me fez perder tempo: com JSON_THROW_ON_ERROR o json_last_error() não é atualizado, continua devolvendo o erro da chamada anterior. Escolha um dos dois estilos por fluxo, senão você loga a mensagem errada.
As três causas que mais me pegaram
BOM no começo do arquivo, quando o JSON veio de um .json salvo no Bloco de Notas. Um Warning: ... on line 12 impresso pelo servidor do outro lado antes do corpo, o clássico Syntax error. E resposta gzipada lida crua, quando o cURL rodou sem CURLOPT_ENCODING => ''.
Pro BOM a limpeza é uma linha só, antes do decode:
$resposta = preg_replace('/^xEFxBBxBF/', '', $resposta);
Sempre que aparecer Syntax error, logue o trecho bruto junto com a mensagem. Na maioria das vezes o problema está visível nos primeiros bytes e você mata a dúvida sem abrir o Postman.