Como recuperar o nome do arquivo ao baixar usando Fetch API em JavaScript com CORS

Problema Concreto

Ao fazer uma requisição para baixar um arquivo gerado pelo servidor, utilizando a API Fetch em JavaScript, muitos desenvolvedores enfrentam dificuldades em obter o nome do arquivo enviado pelo cabeçalho Content-Disposition. Essa informação é essencial para salvar o arquivo com o nome original, melhorando a experiência do usuário. Porém, devido às políticas de CORS, o acesso a certos cabeçalhos, como Content-Disposition, é bloqueado por padrão, o que impede de recuperá-lo diretamente na resposta.

Diagnóstico do Problema

O principal motivo pelo qual o cabeçalho Content-Disposition não é acessível na resposta da Fetch API é a restrição de CORS. Quando o servidor não expõe explicitamente esse cabeçalho, o navegador impede que o JavaScript acesse seu conteúdo, por questões de segurança. Assim, mesmo que o servidor envie o cabeçalho corretamente, ele não estará disponível para o client-side, resultando em null ao tentar lê-lo com response.headers.get("content-disposition").

Solução ou Abordagem

A solução mais eficaz envolve configurar o servidor para expor explicitamente o cabeçalho Content-Disposition. Para isso, o servidor deve incluir na resposta a seguinte diretiva:

Access-Control-Expose-Headers: Content-Disposition

Essa configuração permite que o browser libere o acesso ao cabeçalho para scripts JavaScript, possibilitando sua leitura via Fetch.

No lado do servidor, a implementação pode variar, mas o conceito é o mesmo: garantir que o cabeçalho seja enviado e listado na resposta de controle de acesso. Sem esse critério, a solução pode parecer simples no começo e cara no suporte.

Exemplo Técnico de Implementação

Suponha que você esteja usando uma API em C# para gerar o arquivo. Você pode ajustar a resposta para incluir o cabeçalho de exposição assim:

public IHttpActionResult GetFile()
{
    var result = new FileResult("meuarquivo.txt", "Conteúdo do arquivo"). var response = result.Execute(). response.Headers.Add("Access-Control-Expose-Headers", "Content-Disposition"). return response. }

O valor aparece melhor quando operação, produto e engenharia olham para o mesmo risco.

Assim, na resposta do fetch, você consegue acessar o cabeçalho normalmente: Por isso, o recorte precisa considerar manutenção, validação e caminho de volta. Esse contexto ajuda a separar ganho real de novidade difícil de sustentar. A decisão fica mais saudável quando o time consegue medir o impacto depois.

fetch(_url)
  .then(response => {
    if (response.ok) {
      console.log(response.headers.get("content-disposition")). // Agora acessível
      return response.blob(). }
    throw new Error("Erro na requisição")
  })
  .then(blob => {
    const filename = response.headers.get("content-disposition")
      ? response.headers.get("content-disposition").split('filename=')[1]
      : 'arquivo'. const url = URL.createObjectURL(blob). // código para salvar o arquivo
  }). 

Esse contexto ajuda a separar ganho real de novidade difícil de sustentar. A decisão fica mais saudável quando o time consegue medir o impacto depois. Sem esse critério, a solução pode parecer simples no começo e cara no suporte. O valor aparece melhor quando operação, produto e engenharia olham para o mesmo risco. Por isso, o recorte precisa considerar manutenção, validação e caminho de volta.

Limites e Cuidados

Esse método depende de o servidor estar sob controle ou ser configurado para incluir o cabeçalho de exposição. Caso o servidor não possa ser alterado, uma alternativa é passar o nome do arquivo via query string ou outro método de metadados, embora não seja tão elegante.

Outro ponto importante é verificar se o cabeçalho Content-Disposition sempre vem corretamente definido pelo servidor. Em ambientes com múltiplas APIs ou sistemas legados, isso pode variar. A decisão fica mais saudável quando o time consegue medir o impacto depois. Sem esse critério, a solução pode parecer simples no começo e cara no suporte. O valor aparece melhor quando operação, produto e engenharia olham para o mesmo risco. Por isso, o recorte precisa considerar manutenção, validação e caminho de volta.

Passos Acionáveis

1. Confirme a configuração do servidor para incluir Access-Control-Expose-Headers: Content-Disposition. 2. Faça a requisição usando Fetch e leia o cabeçalho de content-disposition. 3. Extraia o nome do arquivo do valor do cabeçalho, geralmente usando split ou regex. 4. Use URL.createObjectURL() para criar o link de download. 5. Teste em diferentes navegadores, pois o suporte a CORS pode variar.

Ao seguir esses passos, a recuperação do nome do arquivo ao fazer download via Fetch API torna-se viável, mesmo em ambientes com restrições de CORS. Assim, é possível oferecer uma experiência de download mais amigável e alinhada às expectativas do usuário. Sem esse critério, a solução pode parecer simples no começo e cara no suporte. O valor aparece melhor quando operação, produto e engenharia olham para o mesmo risco. Por isso, o recorte precisa considerar manutenção, validação e caminho de volta. Esse contexto ajuda a separar ganho real de novidade difícil de sustentar.