Header Content-Type

O que é o header Content-Type?

Toda comunicação pela web usando o protocolo HTTP é formada por cabeçalhos (headers) e, muitas vezes, por um corpo (body). Os cabeçalhos são informações extras que acompanham a mensagem, como etiquetas em um pacote.

O Content-Type é uma dessas etiquetas. Ele diz a quem recebe a mensagem que tipo de conteúdo está no corpo: um texto em JSON, um documento XML, um PDF, uma imagem ou um formulário. O valor segue um padrão chamado tipo de mídia (ou MIME type), como application/json.

Para que serve o Content-Type em uma API fiscal?

Quando um ERP ou plataforma de vendas envia os dados de uma nota fiscal para uma API, o servidor precisa saber como ler aquelas informações. Se o corpo está em JSON, o Content-Type deve ser application/json; se está em XML, application/xml ou text/xml.

Na resposta, o mesmo cabeçalho indica o que está voltando: um JSON com o status do documento, o XML autorizado da NF-e ou o PDF do DANFE. Assim, o sistema do cliente sabe se deve processar dados, salvar um arquivo ou exibir um documento.

Como o Content-Type aparece na prática?

Ele é escrito como uma linha no cabeçalho da requisição, por exemplo: Content-Type: application/json. Pode incluir parâmetros adicionais, como a codificação de caracteres: Content-Type: application/json; charset=utf-8.

Bibliotecas e linguagens de programação costumam permitir definir esse cabeçalho com uma linha de código. Em muitas delas, ao enviar um objeto JSON, o valor é preenchido automaticamente, mas é sempre bom conferir.

O que acontece se o Content-Type estiver errado ou ausente?

Se o cabeçalho não corresponder ao conteúdo real, o servidor pode não conseguir interpretar os dados. Em geral, a API devolve um erro, como o código HTTP 415 (tipo de mídia não suportado) ou 400 (requisição inválida).

Em integrações fiscais, isso pode parecer um problema nos dados da nota, quando na verdade é apenas um cabeçalho mal configurado. Verificar o Content-Type é um dos primeiros passos ao investigar falhas de envio.

Qual a diferença entre Content-Type e Accept?

O Content-Type descreve o formato do que está sendo enviado. Já o cabeçalho Accept informa qual formato o cliente prefere receber na resposta.

Por exemplo, um sistema pode enviar os dados da nota em JSON (Content-Type: application/json) e pedir o PDF do documento auxiliar como resposta (Accept: application/pdf). Os dois cabeçalhos trabalham juntos, mas têm papéis diferentes.

Quais caracteres especiais exigem atenção com o charset?

Documentos fiscais brasileiros têm acentos e cedilha em nomes, endereços e descrições de produtos. Se a codificação não for informada ou estiver incorreta, palavras como 'Ação' ou 'São Paulo' podem chegar corrompidas.

Indicar charset=utf-8 no Content-Type, e garantir que o texto realmente esteja nessa codificação, evita esse tipo de problema e reduz rejeições por caracteres inválidos.

Exemplos de Header Content-Type

• Um ERP envia os dados de uma NF-e para a API de emissão com o cabeçalho Content-Type: application/json; charset=utf-8, e o servidor interpreta corretamente os itens e tributos da nota.
• Uma plataforma de marketplace recebe a resposta de uma consulta de documento com Content-Type: application/pdf e salva o arquivo como o DANFE para enviar ao comprador.
• Um desenvolvedor recebe erro 415 ao emitir uma NFS-e porque esqueceu de definir o Content-Type; ao incluir application/json, a requisição passa a ser aceita.
• Ao baixar o XML autorizado de um CT-e, o sistema identifica pelo Content-Type: application/xml que deve armazenar o conteúdo como arquivo fiscal, e não exibi-lo como texto.