Como Usar um PDF em Base64 em uma Requisição de API JSON

APIs REST e JSON são construídas em torno de texto, não de binário puro, então não existe forma nativa de colocar os bytes de um PDF diretamente em um campo JSON. Codificar o arquivo em Base64 primeiro o transforma em uma string, que o JSON trata como qualquer outro valor de texto.

Se você ainda não converteu um arquivo, o guia de PDF para Base64 cobre a etapa de conversão em si.

Uma requisição típica combina a string codificada com alguns campos de metadados: um campo — geralmente chamado file, document ou content — guarda o texto Base64, um campo filename traz o nome original do arquivo e um campo contentType ou mimeType definido como application/pdf diz ao receptor como interpretar os bytes após decodificá-los.

Mantenha o campo codificado como uma única string ininterrupta. Quebras de linha ou espaços extras inseridos por um editor ou uma etapa de copiar e colar corrompem o valor antes que ele chegue ao servidor.

A maioria dos clientes HTTP — fetch no navegador, uma biblioteca HTTP do lado do servidor ou uma ferramenta como curl — envia o corpo JSON da mesma forma que enviaria qualquer outro payload, desde que o cabeçalho Content-Type esteja definido como application/json. O campo Base64 é apenas uma string longa dentro desse corpo.

Fique atento ao tamanho total da requisição: o PDF codificado faz parte do JSON, então um anexo grande aumenta diretamente o tamanho do corpo, e alguns gateways de API ou proxies reversos impõem um tamanho máximo de requisição.

A maioria das linguagens do lado do servidor inclui um decodificador Base64 nativo. Decodificar transforma a string de volta nos bytes exatos originais, que o servidor pode então gravar em disco, guardar em um banco de dados, repassar a outro serviço ou transmitir de volta para um cliente.

Se o arquivo decodificado não abrir como um PDF válido, verifique se sobrou um prefixo de data URI ou alguma corrupção de copiar e colar — veja problemas comuns de PDF para Base64.

Para PDFs grandes, uploads frequentes ou arquivos que precisam ser transmitidos em streaming em vez de carregados inteiramente na memória, um upload multipart ou um envio direto para um armazenamento costuma ser melhor do que embutir o arquivo no JSON. Base64 dentro de JSON funciona melhor para arquivos pequenos a médios movidos ocasionalmente — certificados, formulários assinados, relatórios curtos.