Enviar archivos a una API: multipart o Base64 y cómo evitar cargas dañadas

El endpoint decide cómo se envía el archivo

Enviar un archivo a una API consiste en incluir su contenido en una solicitud HTTP que el servidor pueda interpretar. No hay un formato universal que sirva para todos los endpoints: uno puede esperar una carga multipart/form-data, otro un objeto JSON con contenido codificado y otro un mecanismo distinto descrito por su contrato. La extensión del archivo o el hecho de que una solicitud use POST no bastan para decidir qué estructura enviar. La primera tarea es identificar la operación concreta y seguir lo que esa operación declara.

Separar la representación del archivo de la lógica de negocio ayuda a diagnosticar problemas. La representación determina cómo viajan los bytes y los campos; el endpoint determina qué campos exige, qué tipos acepta y qué respuesta produce. Si se envía un cuerpo válido para una operación distinta, el servidor puede rechazarlo o procesarlo de forma inesperada. Antes de escribir código, anota método, ruta, autenticación, tipo de contenido, campos requeridos, límites documentados y respuestas de error.

• No deduzcas el formato aceptado por el nombre de la ruta ni por una integración de otro proveedor.
• Trata los ejemplos de solicitud como guía, pero comprueba que correspondan a la misma versión y operación.

Multipart/form-data y Base64 en JSON

Con multipart/form-data, el cuerpo se divide en partes separadas. Cada parte tiene sus propios encabezados y contenido, por lo que una solicitud puede combinar el archivo con campos adicionales, si el endpoint los admite. El cliente construye la separación entre partes; por eso, al usar una biblioteca HTTP, normalmente conviene dejar que la biblioteca genere el encabezado Content-Type completo y su delimitador. Establecerlo manualmente sin conservar el delimitador que corresponde al cuerpo es una causa frecuente de solicitudes que el servidor no puede analizar.

Con Base64, los bytes del archivo se convierten en texto y ese texto se incorpora a un documento JSON, por ejemplo en una propiedad definida por el contrato. Esta codificación suele aumentar el tamaño transmitido respecto del archivo binario y añade una conversión al preparar y procesar el contenido. No presupongas el nombre de la propiedad, si se exige un prefijo de tipo de medio o si el endpoint acepta Base64: son decisiones del esquema. Para cargas grandes, compara el coste y los límites documentados antes de elegir.

• Multipart resulta adecuado cuando el contrato describe partes de formulario y una parte de archivo.
• Base64 solo es opción si el endpoint declara esa representación; no basta con que el cuerpo sea JSON.

Inspeccionar OpenAPI sin hacer suposiciones

Consulta la especificación OpenAPI disponible y localiza la operación exacta por ruta y método. Revisa el tipo de contenido que acepta el cuerpo de la solicitud, el esquema asociado y las propiedades requeridas. Para multipart, verifica cómo se declara el archivo y qué nombres tienen las partes; para JSON, busca la estructura y el tipo de dato indicados para cada campo. La documentación de OpenAPI es relevante porque la aceptación de cargas multipart debe quedar especificada en el contrato, en lugar de inferirse por intuición.

Lee también las respuestas documentadas, los requisitos de autenticación y cualquier límite o restricción que acompañe a la operación. Un ejemplo no documenta necesariamente todos los casos válidos, y una ausencia de información no equivale a permiso para enviar archivos arbitrarios. Si falta el esquema, si el tipo de contenido no está claro o si las instrucciones se contradicen, pide confirmación al responsable de la API antes de codificar. Mantén anotada la versión del contrato usada para implementar y probar.

• Confirma: método, ruta, Content-Type, esquema del cuerpo, campos obligatorios y respuestas posibles.
• No infieras límites, permisos, formatos admitidos ni almacenamiento a partir de una descripción general del producto.

Construcción de la solicitud y errores comunes

En un ejemplo conceptual multipart, el cliente envía una parte con el nombre de campo declarado por el contrato y el contenido binario del archivo; puede incluir otras partes únicamente si están documentadas. En un ejemplo conceptual JSON, lee los bytes, codifícalos en Base64 y colócalos en la propiedad exacta que define el esquema. Estos ejemplos describen patrones, no una solicitud compatible con un endpoint de Apification concreto. La integración de Apification incluye REST API y OpenAPI, pero la evidencia disponible aquí no especifica qué operación acepta archivos ni qué esquema utiliza.

Comprueba que el archivo se abra correctamente antes de enviarlo y que el programa no esté leyendo una ruta equivocada, un archivo vacío o una versión parcial. No confundas el nombre o la extensión con el MIME type: pueden no coincidir, y el valor que debe transmitirse depende del contrato. Evita truncar Base64 al registrar solicitudes o transportar JSON entre componentes. También controla límites de tamaño en cliente, intermediarios y servidor, porque un rechazo puede ocurrir antes de que el endpoint procese el cuerpo.

• Errores típicos: nombre de campo incorrecto, JSON mal formado, delimitador multipart ausente, contenido Base64 truncado y MIME type no aceptado.
• No registres el contenido completo del archivo en trazas; registra metadatos necesarios para diagnosticar sin exponer el documento.

Verificar de extremo a extremo que no hubo corrupción

Una respuesta HTTP satisfactoria no demuestra por sí sola que el contenido almacenado coincida con el archivo de origen. Diseña una prueba que envíe un archivo representativo y luego obtenga el objeto recibido por el mecanismo que documente la API. Si no hay una forma documentada de recuperarlo, confirma qué comprobación ofrece el servicio; no supongas que la respuesta contiene el archivo ni que existe una operación de descarga. Conserva el original de prueba sin modificar y registra su tamaño y, si el flujo lo permite, una huella calculada localmente.

Compara el archivo recuperado con el original mediante una comparación binaria o calculando la misma huella en ambos. Haz pruebas con varios tipos y tamaños que sean pertinentes para la integración, incluidos archivos pequeños y cercanos al límite documentado. Revisa además el código de respuesta, el cuerpo de error y los registros seguros del cliente. Si el resultado difiere, aísla el punto de cambio: lectura local, codificación, transporte, procesamiento del servidor o descarga posterior.

• Prueba al menos un archivo binario y uno con contenido textual; incluye nombres con espacios o caracteres no ASCII si el contrato lo permite.
• Repite con solicitudes que excedan límites solo en un entorno controlado y confirma que el rechazo sea claro y no deje un objeto parcial.

Lista de comprobación antes de integrar

Antes de desplegar, convierte el contrato en una lista comprobable: operación y versión correctas, tipo de contenido declarado, campos y nombres exactos, autenticación requerida, límites conocidos y forma de interpretar las respuestas. Implementa la solicitud con una biblioteca que gestione correctamente multipart o con una serialización JSON fiable. Define qué ocurrirá ante errores de red, rechazo de tamaño, credenciales inválidas o respuesta mal formada. Reintentar automáticamente una carga no siempre es inocuo: determina si el endpoint permite repetirla sin crear duplicados o resultados ambiguos.

Completa la revisión con controles operativos. Limita el acceso al archivo de origen según las necesidades de la integración, evita incluir credenciales o contenido sensible en registros y elimina temporales cuando ya no hagan falta. Documenta cómo reproducir una carga fallida con un archivo de prueba y cómo validar la recepción. Apification ofrece integración de Cloud y sus servicios mediante REST API, OpenAPI, webhooks, iframe y JavaScript; los detalles de carga, permisos y capacidades de cada endpoint deben confirmarse en la documentación aplicable, no extrapolarse de esa capacidad general.

• Contrato revisado y versionado.
• Representación y límites confirmados para el endpoint concreto.
• Pruebas de integridad, errores y reintentos completadas.
• Acceso, registros y archivos temporales revisados.

Preguntas frecuentes