Cómo Usar un PDF en Base64 en una Solicitud de API JSON

Las APIs REST y JSON están construidas alrededor del texto, no del binario puro, así que no hay forma nativa de poner los bytes de un PDF directamente en un campo JSON. Codificar el archivo en Base64 primero lo convierte en una cadena, que JSON trata como cualquier otro valor de texto.

Si aún no has convertido un archivo, la guía de PDF a Base64 cubre el paso de conversión en sí.

Una solicitud típica combina la cadena codificada con algunos campos de metadatos: un campo — a menudo llamado file, document o content — contiene el texto Base64, un campo filename lleva el nombre original del archivo, y un campo contentType o mimeType establecido en application/pdf le indica al receptor cómo interpretar los bytes una vez decodificados.

Mantén el campo codificado como una sola cadena sin interrupciones. Los saltos de línea o espacios extra que inserte un editor o un paso de copiar y pegar corromperán el valor antes de que llegue al servidor.

La mayoría de los clientes HTTP — fetch en el navegador, una librería HTTP del lado del servidor o una herramienta como curl — envían el cuerpo JSON igual que enviarían cualquier otro payload, siempre que el encabezado Content-Type esté configurado como application/json. El campo Base64 es solo una cadena larga dentro de ese cuerpo.

Vigila el tamaño total de la solicitud: el PDF codificado forma parte del JSON, así que un adjunto grande aumenta directamente el tamaño del cuerpo, y algunos gateways de API o proxies inversos imponen un tamaño máximo de solicitud.

La mayoría de los lenguajes del lado del servidor incluyen un decodificador Base64 incorporado. Decodificar convierte la cadena de vuelta en los bytes exactos originales, que el servidor puede entonces escribir en disco, guardar en una base de datos, reenviar a otro servicio o transmitir de vuelta a un cliente.

Si el archivo decodificado no se abre como un PDF válido, revisa si quedó un prefijo de data URI o alguna corrupción de copiar y pegar — consulta problemas comunes de PDF a Base64.

Para PDFs grandes, subidas frecuentes o archivos que necesitan transmitirse en streaming en lugar de cargarse por completo en memoria, una subida multipart o una carga directa a almacenamiento suele ser mejor que incrustar el archivo en JSON. Base64 dentro de JSON funciona mejor para archivos pequeños o medianos que se mueven ocasionalmente — certificados, formularios firmados, informes cortos.