Has creado un endpoint que recibe un archivo. Un usuario sube una imagen de perfil a POST /avatars, o tu aplicación envía un PDF firmado a POST /documents. La ruta funciona en tu cabeza. Ahora necesitas demostrar que funciona a través de HTTP: elige un archivo real, adjúntalo a un campo de formulario, envía la solicitud y comprueba la respuesta.
Aquí es donde muchas herramientas de API se vuelven complicadas. Las cargas de archivos usan multipart/form-data, no JSON, por lo que no puedes simplemente pegar un cuerpo y presionar enviar. Necesitas un constructor de solicitudes que entienda los campos de archivo y un ejecutor de pruebas (test runner) que pueda encontrar el archivo cuando la prueba se ejecute más tarde. Apidog maneja ambos, y esta guía recorre todo el camino: enviar una sola carga, enviar un archivo junto con JSON, verificar la respuesta, y luego la parte honesta de la que nadie te advierte, que es lo que sucede cuando ese mismo paso de carga se ejecuta sin interfaz gráfica (headless) en el Runner o la CLI y no puede encontrar el archivo. Si primero quieres los antecedentes sobre el formato en sí, el manual carga de archivos en APIs cubre cómo se estructuran las solicitudes multipart. La referencia de MDN sobre FormData es un buen complemento para el lado del navegador.
Qué es multipart/form-data y por qué las cargas lo necesitan
El cuerpo de una solicitud API puede adoptar varias formas. En la sección Body de la solicitud de Apidog, puedes elegir form-data, x-www-form-urlencoded, JSON, XML, raw o binario. La mayoría de las veces optas por JSON. Las cargas de archivos son la excepción.
El tipo de cuerpo form-data se asigna al encabezado Content-Type: multipart/form-data. Es el formato diseñado para subir archivos junto con otros datos. En lugar de un solo bloque de datos (blob), el cuerpo se divide en partes, cada una con su propio nombre y su propio contenido. Una parte puede ser una cadena de texto simple como un pie de foto, otra parte pueden ser los bytes en bruto de una imagen. Por eso una carga de foto y sus metadatos pueden viajar en la misma solicitud.
El pariente cercano es x-www-form-urlencoded. Se ve similar en el editor, pares clave-valor enviados en el cuerpo, pero está diseñado para formularios simples sin archivos. Si tu endpoint recibe un archivo, form-data es el que quieres. Recurre a x-www-form-urlencoded solo cuando cada campo es un escalar corto y no hay bytes involucrados.
En form-data, Apidog muestra cada parámetro como un par clave-valor, y cada parámetro lleva un tipo: string, integer, file, etc. Ese tipo por parámetro es todo el truco. Configura un campo como file y Apidog tratará su valor como un archivo para adjuntar en lugar de texto para enviar.
Enviar una única carga de archivo y verificar la respuesta
Supongamos que estás probando POST /avatars. Recibe un campo, avatar, que contiene una imagen, y devuelve JSON con la URL almacenada. Aquí está el paso a paso.
1. Abre la sección Body y elige form-data. En tu endpoint o una nueva solicitud, establece el método en POST y la URL a tu ruta de avatares. Abre la pestaña Body y selecciona el tipo de cuerpo form-data. Apidog configura Content-Type: multipart/form-data por ti.
2. Agrega el parámetro de archivo y establece su tipo como file. Agrega un parámetro con la clave avatar. Junto a la clave, usa el selector de tipo para cambiar su tipo de string a file. La celda de valor se convierte en un selector de archivos en lugar de un cuadro de texto.
3. Haz clic en Upload y elige un archivo local. Haz clic en Upload en la fila avatar y selecciona una imagen de tu máquina, por ejemplo jane-profile.png. Apidog registra la ruta a ese archivo.
4. Envía la solicitud. Pulsa Enviar. Apidog lee el archivo desde la ruta local almacenada, construye el cuerpo multipart y lo envía. Es importante saber de antemano: Apidog envía el archivo en la solicitud pero no lo almacena en la nube. Guarda solo la ruta local, no los bytes. Ese detalle importará más adelante, así que tenlo en cuenta.
Una llamada exitosa devuelve algo como esto:
{
"id": "usr_8842",
"avatarUrl": "https://cdn.example.com/avatars/usr_8842.png",
"sizeBytes": 48210,
"contentType": "image/png"
}
5. Verifica la respuesta. Un envío que devuelve 200 no es una prueba superada por sí solo. Agrega aserciones para que la verificación sea real. En Apidog, las agregas como aserciones post-solicitud en el endpoint o paso del escenario. En términos sencillos, quieres confirmar el estado y que el cuerpo contiene una URL utilizable:
status code == 200
$.avatarUrl exists
$.contentType == "image/png"
Estos se mapean directamente a la interfaz de usuario de aserciones de Apidog: una aserción sobre el código de estado, una sobre la presencia de JSONPath $.avatarUrl, y otra sobre $.contentType. Si eres nuevo en las aserciones, la guía de aserciones de API muestra el conjunto completo de operadores y cómo JSONPath apunta a un campo.
Para una rápida verificación de la realidad fuera de la herramienta, la misma carga en curl se ve así:
curl -X POST https://api.example.com/avatars \
-F "avatar=@jane-profile.png"
El flag -F es la forma en que curl construye una parte multipart, y @ le indica que lea el contenido del archivo. El parámetro de archivo form-data de Apidog hace lo mismo con un selector en lugar de un flag.
Enviar un archivo y JSON juntos
Los endpoints reales rara vez aceptan un archivo solo. POST /documents podría querer el archivo más metadatos: un título, una categoría, quizás un array de etiquetas (tags). Tienes dos formas claras de hacer esto en una sola solicitud multipart.
El caso simple son los campos escalares. Agrega más parámetros form-data junto a tu campo de archivo y déjalos como string o integer. Una cadena title, una cadena category, un file establecido como tipo file. Los tres viajan en la misma solicitud.
Cuando los metadatos están estructurados, como un objeto anidado o un array, los envías como JSON dentro de una parte de cadena de texto. Agrega un parámetro form-data llamado metadata, mantén su tipo como string, y pega el JSON directamente en el valor:
{
"title": "Q3 Invoice",
"category": "billing",
"tags": ["invoice", "2026", "paid"]
}
Así, la solicitud tiene dos partes: file (tipo file) que lleva q3-invoice.pdf, y metadata (tipo string) que lleva ese JSON. El servidor lee el archivo de una parte y analiza el JSON de la otra. Muchas APIs públicas aceptan cargas de esta manera exacta; la documentación de carga de archivos de Stripe es un buen ejemplo de un endpoint multipart real que empareja una parte de archivo con campos planos. Este patrón es lo suficientemente común como para que los usuarios de Postman también lo encuentren; si estás migrando, el tutorial sobre cómo subir un archivo y datos JSON en Postman se mapea limpiamente a los campos form-data de Apidog.
¿Necesitas adjuntar más de un archivo? Agrega otro parámetro con el tipo file. Un POST /documents que acepta un archivo principal y una miniatura obtiene dos filas de archivo, file y thumbnail, cada una con su propio botón Upload. No hay un modo especial para múltiples archivos; simplemente agregas parámetros de tipo archivo hasta que hayas cubierto todas las partes que el endpoint espera.
Convertir la solicitud en un escenario de prueba repetible
Un único envío demuestra que el endpoint funciona una vez. Para detectar regresiones, querrás la carga dentro de un escenario de prueba guardado que se ejecute bajo demanda o en un horario. Encadena los pasos: sube el avatar, captura el id devuelto, luego llama a GET /users/{id} y verifica que la URL del avatar persistió.
Construye esto de la misma manera que construiste la solicitud única, luego guárdalo como un paso en un escenario. La guía cómo escribir un escenario de prueba con Apidog cubre el encadenamiento de pasos y el paso de valores entre ellos. Una vez que la carga reside en un escenario, puedes ejecutarla contra el entorno de staging en cada despliegue, agregar ramas condicionales con lógica condicional en escenarios de prueba de API, o programarla con pruebas de API programadas.
Todo lo anterior funciona bien en tu máquina, porque tu máquina tiene el archivo. Esa suposición es exactamente lo que se rompe a continuación.
La trampa: cargas que se ejecutan en otro lugar
Aquí está la parte que el "happy path" oculta. Apidog almacena la ruta del archivo, no el archivo. En tu portátil eso es invisible, porque la ruta siempre se resuelve a un archivo real. En el momento en que el mismo paso se ejecuta en una máquina diferente, la ruta no apunta a nada.
Te encontrarás con esto en dos lugares.
Colaboración en equipo. Cuando un compañero de equipo abre tu solicitud POST /avatars, ve el parámetro de archivo y la ruta que elegiste, digamos /Users/jane/pics/jane-profile.png. Pueden ver la solicitud, pero no pueden enviarla, porque ese archivo reside en tu disco, no en el suyo. La ruta es local a la máquina que la eligió.
Ejecuciones en el Runner y la CLI. Este es el que causa problemas en la automatización. Tu escenario de carga se aprueba localmente, lo programas en el Runner o lo ejecutas desde la CLI, y el paso de carga de archivos falla. No hay nada malo con tus aserciones. El runner simplemente no puede encontrar un archivo en la ruta que tu portátil guardó, porque esa ruta no existe en el host del runner.
La solución se deriva de la causa. El archivo debe existir en la máquina que realiza el envío, y la ruta del paso debe apuntar a él allí.
Para el Runner: el Runner lee archivos de un directorio del host montado en su volumen. Configuras ese montaje cuando despliegas el Runner, usando el flag -v. Copia tu archivo de carga en ese directorio del host montado. Luego, abre los detalles del paso de carga de archivo en el escenario, haz clic en el botón Batch Edit en la esquina superior derecha, y reemplaza el valor del campo de archivo con la ruta dentro del directorio del Runner, por ejemplo:
/opt/runner/jane-profile.png
Para la CLI: la misma forma. Coloca el archivo en la máquina de la CLI, luego usa Batch Edit en el paso para que la ruta apunte a su ubicación allí, por ejemplo:
/opt/apidog/runner/jane-profile.png
Más limpio que codificar rígidamente: usa una variable. En lugar de fijar una ruta literal en el paso, reemplaza el valor con una variable y establece el valor de la variable a la ruta de archivo real por entorno. Así, el mismo escenario se ejecuta en tu portátil, el Runner y la CI sin editar el paso cada vez. Apuntas la variable a /Users/jane/pics/jane-profile.png localmente y a /opt/runner/jane-profile.png en el runner, y el paso en sí nunca cambia.
Un requisito previo que vale la pena mencionar claramente: el Runner solo accede a los archivos del host que residen bajo el directorio que montaste con -v en el momento del despliegue. Si tu archivo no está bajo ese montaje, ninguna ruta lo encontrará. Eso es un detalle de configuración de despliegue, no una limitación del plan. La documentación de Apidog sobre solicitudes de carga de archivos detalla los pasos de montaje y edición masiva si quieres la versión canónica.
Automatiza el flujo de trabajo con la CLI de Apidog
Una vez que tu escenario de carga esté guardado, puedes ejecutarlo sin interfaz gráfica (headless) en CI. Instala la CLI y autentícate:
npm install -g apidog-cli
apidog login --with-token <YOUR_ACCESS_TOKEN>
Luego ejecuta el escenario guardado por ID, apuntándolo a un entorno:
apidog run --access-token $APIDOG_ACCESS_TOKEN -t <scenario_id> -e <env_id> -r cli
Aquí -t es el ID del escenario de prueba, -e es el ID del entorno, y -r es el reportero (usa cli, html o junit, separados por comas para varios). La CLI ejecuta tus escenarios guardados desde el proyecto en la nube e informa de éxito/fallo con códigos de salida, lo que permite controlar una pipeline. Los detalles de configuración se encuentran en la guía de instalación de la CLI de Apidog.
Una advertencia honesta, y es la misma de la sección anterior: un escenario con un paso de carga de archivo necesita que el archivo esté presente en la máquina de la CLI, y la ruta del paso debe apuntar a él allí. Coloca el archivo en el runner, luego usa Batch Edit para la ruta (o usa una variable) antes de la ejecución. Si omites eso, el paso de carga fallará al no encontrar el archivo, aunque el resto del escenario esté bien. Para una configuración de CI más completa, incluyendo el paso de entradas por fila, consulta las pruebas impulsadas por datos con la CLI de Apidog.
Preguntas Frecuentes
¿Por qué mi compañero de equipo no puede enviar mi solicitud de carga de archivos? Apidog almacena la ruta del archivo local, no el archivo en sí, y nunca sube el archivo a la nube. Tu compañero de equipo ve la solicitud y la ruta que elegiste, pero esa ruta se resuelve a un archivo en tu disco, no en el suyo. Pídeles que coloquen una copia del archivo en su máquina y apunten el campo a su propia ruta. El mismo mecanismo explica por qué las pruebas programadas y los trabajos del Runner necesitan que el archivo esté preparado donde se ejecutan.
¿Cómo envío JSON junto con un archivo en la misma solicitud? Mantén el tipo de cuerpo como form-data. Agrega tu campo de archivo con tipo file, luego agrega otro parámetro con tipo string y pega el JSON en su valor. El servidor recibe ambas partes en una solicitud multipart: el archivo en una parte, la cadena JSON en otra. Esta es la forma estándar de adjuntar metadatos a una carga.
¿Qué ruta debo usar para un archivo en el Runner? Usa una ruta dentro del directorio del host que montaste en el volumen del Runner con el flag -v en el momento del despliegue, por ejemplo /opt/runner/yourfile.jpg. Copia el archivo en ese directorio montado, luego abre el paso, haz clic en Batch Edit y establece el valor del campo a esa ruta. El equivalente en la CLI se ve así: /opt/apidog/runner/yourfile.jpg.
¿Existe un límite de tamaño de archivo o una lista de tipos de archivo permitidos? El comportamiento de carga en Apidog se refiere a cómo se construye la solicitud y de dónde se lee el archivo. Tus límites reales de tamaño y tipo provienen de la API que estás probando, así que verifica las reglas de validación de tu propio servidor y escribe aserciones contra las respuestas que devuelve para archivos demasiado grandes o rechazados.
¿Debo usar form-data o x-www-form-urlencoded para las cargas? Usa form-data. Se mapea a multipart/form-data y está diseñado para transportar archivos. x-www-form-urlencoded es para formularios simples con campos escalares cortos y sin archivos, por lo que no transportará tu imagen o PDF.
Conclusión
Las pruebas de carga de archivos se resumen en dos cosas: construir la solicitud multipart correctamente y asegurarse de que el archivo sea accesible dondequiera que se ejecute la prueba. En Apidog, estableces el Body en form-data, cambias el tipo de tu campo a file, haces clic en Upload, agregas cualquier JSON como una parte de cadena, luego envías y verificas. Cuando mueves el mismo escenario al Runner o la CLI, preparas el archivo en esa máquina y rediriges la ruta con Batch Edit o una variable, y la ejecución automatizada se comporta como la local.
¿Quieres probarlo contra tu propio endpoint? Descarga Apidog, apunta una solicitud form-data a tu ruta de carga y observa cómo vuelve la respuesta. Es gratis para empezar, no se requiere tarjeta de crédito.