DEV Community

Cover image for Cómo Probar APIs de Subida de Archivos (multipart/form-data) en Apidog
Roobia
Roobia

Posted on • Originally published at apidog.com

Cómo Probar APIs de Subida de Archivos (multipart/form-data) en Apidog

Has creado un endpoint que recibe un archivo. Por ejemplo, un usuario sube una imagen de perfil a POST /avatars o tu aplicación envía un PDF firmado a POST /documents. Para probarlo por HTTP necesitas seleccionar un archivo real, adjuntarlo a un campo de formulario, enviar la solicitud y validar la respuesta.

Prueba Apidog hoy

Las cargas de archivos usan multipart/form-data, no JSON. Por eso no basta con pegar un cuerpo y pulsar Enviar: necesitas configurar campos de archivo y asegurarte de que el archivo exista también cuando la prueba se ejecute en el Runner o mediante CLI. Apidog permite cubrir ambos casos.

Si necesitas repasar el formato, consulta la guía sobre carga de archivos en APIs y la referencia de MDN sobre FormData.

Qué es multipart/form-data y por qué lo necesitan las cargas

En la sección Body de Apidog puedes elegir form-data, x-www-form-urlencoded, JSON, XML, raw o binario. Para la mayoría de endpoints usarás JSON. Para adjuntar archivos, usa form-data.

form-data se envía con el encabezado:

Content-Type: multipart/form-data
Enter fullscreen mode Exit fullscreen mode

El cuerpo se divide en partes. Cada parte tiene un nombre y contenido propio:

  • Una parte puede contener texto, como title o category.
  • Otra puede contener los bytes de una imagen, PDF u otro archivo.
  • Todas las partes viajan en la misma solicitud HTTP.

No confundas form-data con x-www-form-urlencoded. Ambos usan pares clave-valor, pero x-www-form-urlencoded sirve para campos escalares simples y no transporta archivos.

En Apidog, cada parámetro de form-data tiene un tipo, como string, integer o file. Al cambiar un campo a file, Apidog adjunta el archivo seleccionado en lugar de enviar una cadena de texto.

Enviar un único archivo y verificar la respuesta

Supongamos que pruebas este endpoint:

POST /avatars
Enter fullscreen mode Exit fullscreen mode

El endpoint recibe un campo llamado avatar y devuelve una URL para la imagen almacenada.

1. Configura la solicitud como form-data

  1. Crea o abre la solicitud.
  2. Configura el método como POST.
  3. Introduce la URL de tu endpoint, por ejemplo: 
   https://api.example.com/avatars
Enter fullscreen mode Exit fullscreen mode
  1. Abre la pestaña Body.
  2. Selecciona form-data.

Apidog configura Content-Type: multipart/form-data automáticamente.

2. Añade el campo de archivo

Crea un parámetro con esta configuración:

Clave Tipo
avatar file

Cambia el tipo de string a file. El campo de valor mostrará un selector de archivos.

3. Selecciona el archivo local

Haz clic en Upload y selecciona, por ejemplo:

jane-profile.png
Enter fullscreen mode Exit fullscreen mode

Apidog guarda la ruta local del archivo. No guarda los bytes del archivo en la nube; este detalle es importante para ejecuciones en Runner y CLI.

4. Envía la solicitud

Pulsa Enviar. Una respuesta exitosa podría ser:

{
  "id": "usr_8842",
  "avatarUrl": "https://cdn.example.com/avatars/usr_8842.png",
  "sizeBytes": 48210,
  "contentType": "image/png"
}
Enter fullscreen mode Exit fullscreen mode

5. Añade aserciones

Un 200 no garantiza por sí solo que la carga sea correcta. Valida también los datos relevantes de la respuesta:

status code == 200
$.avatarUrl exists
$.contentType == "image/png"
Enter fullscreen mode Exit fullscreen mode

En Apidog, añade estas verificaciones como aserciones post-solicitud:

  • Código de estado igual a 200.
  • Existencia de $.avatarUrl.
  • Valor de $.contentType igual a image/png.

Consulta la guía de aserciones de API para ver operadores y ejemplos con JSONPath.

Como comprobación externa, la misma carga con curl sería:

curl -X POST https://api.example.com/avatars \
  -F "avatar=@jane-profile.png"
Enter fullscreen mode Exit fullscreen mode

El flag -F crea una parte multipart y @ indica a curl que debe leer el archivo local.

Enviar un archivo y JSON en la misma solicitud

Los endpoints reales suelen requerir metadatos además del archivo. Por ejemplo:

POST /documents
Enter fullscreen mode Exit fullscreen mode

Puede recibir un PDF, un título, una categoría y etiquetas.

Campos escalares junto al archivo

Para campos simples, añade varias filas en form-data:

Clave Tipo Ejemplo
file file q3-invoice.pdf
title string Q3 Invoice
category string billing

Todos los campos se enviarán en la misma solicitud multipart.

JSON estructurado como una parte de texto

Si los metadatos contienen objetos anidados o arrays, añade un campo string llamado metadata y pega el JSON como valor:

{
  "title": "Q3 Invoice",
  "category": "billing",
  "tags": ["invoice", "2026", "paid"]
}
Enter fullscreen mode Exit fullscreen mode

La solicitud tendrá estas partes:

  • file: tipo file, con q3-invoice.pdf.
  • metadata: tipo string, con el JSON serializado.

El servidor recibe el archivo en una parte y analiza el JSON de la otra. La documentación de carga de archivos de Stripe muestra un ejemplo de endpoint multipart con archivo y campos adicionales.

Si migras desde Postman, consulta cómo subir un archivo y datos JSON en Postman.

Adjuntar varios archivos

No necesitas un modo especial para múltiples archivos. Añade una fila por cada parte que espere tu API:

Clave Tipo
file file
thumbnail file

Selecciona un archivo para cada fila mediante Upload.

Convertir la carga en un escenario de prueba repetible

Enviar una solicitud manualmente prueba un caso puntual. Para detectar regresiones, guarda el flujo en un escenario de prueba.

Por ejemplo:

  1. Ejecuta POST /avatars.
  2. Captura el id devuelto.
  3. Ejecuta GET /users/{id}.
  4. Verifica que la URL del avatar persiste.

Guarda la carga como un paso del escenario y reutiliza el valor devuelto en las solicitudes posteriores. La guía sobre cómo escribir un escenario de prueba con Apidog explica cómo encadenar pasos y pasar valores entre ellos.

Después puedes:

Sin embargo, una carga que funciona en tu equipo puede fallar al ejecutarse en otra máquina.

La trampa: el archivo no existe donde se ejecuta la prueba

Apidog almacena la ruta local del archivo, no el archivo. En tu portátil, la ruta funciona porque el archivo existe. En otra máquina, esa ruta puede no resolver a ningún archivo.

Esto suele ocurrir en dos casos.

Colaboración en equipo

Si seleccionaste:

/Users/jane/pics/jane-profile.png
Enter fullscreen mode Exit fullscreen mode

un compañero verá esa ruta, pero no podrá usarla si el archivo no existe en su equipo. Debe copiar el archivo localmente y seleccionar una ruta válida para su máquina.

Runner y CLI

Un escenario puede pasar localmente y fallar en Runner o CI porque el host de ejecución no tiene el archivo en la ruta guardada.

La regla es simple:

El archivo debe existir en la máquina que envía la solicitud y la ruta configurada debe apuntar a ese archivo.

Configurar archivos para el Runner

El Runner lee archivos desde un directorio del host montado como volumen al desplegarlo con -v.

Flujo recomendado:

  1. Monta un directorio del host al desplegar el Runner.
  2. Copia el archivo de prueba dentro de ese directorio.
  3. Abre el paso de carga en el escenario.
  4. Haz clic en Batch Edit.
  5. Sustituye la ruta del archivo por una ruta accesible desde el Runner.

Por ejemplo:

/opt/runner/jane-profile.png
Enter fullscreen mode Exit fullscreen mode

El archivo debe estar dentro del directorio montado. Si no está incluido en el volumen configurado con -v, el Runner no podrá encontrarlo.

Configurar archivos para la CLI

Para la CLI, aplica el mismo principio:

  1. Copia el archivo a la máquina donde se ejecuta la CLI.
  2. Edita el paso de carga con Batch Edit.
  3. Usa una ruta válida en esa máquina.

Por ejemplo:

/opt/apidog/runner/jane-profile.png
Enter fullscreen mode Exit fullscreen mode

Evita rutas rígidas con variables de entorno

En lugar de guardar una ruta literal en el escenario, usa una variable.

Por ejemplo:

{{upload_file_path}}
Enter fullscreen mode Exit fullscreen mode

Asigna un valor distinto por entorno:

# Local
/Users/jane/pics/jane-profile.png

# Runner
/opt/runner/jane-profile.png
Enter fullscreen mode Exit fullscreen mode

Así, el escenario no cambia entre tu portátil, el Runner y CI. Solo cambia el valor de la variable según el entorno.

Consulta la documentación de Apidog sobre solicitudes de carga de archivos para los pasos de montaje y edición masiva.

Automatiza el flujo con la CLI de Apidog

Cuando el escenario esté guardado, puedes ejecutarlo en CI sin interfaz gráfica.

Instala la CLI e inicia sesión:

npm install -g apidog-cli
apidog login --with-token <YOUR_ACCESS_TOKEN>
Enter fullscreen mode Exit fullscreen mode

Ejecuta un escenario guardado indicando el ID del escenario y el entorno:

apidog run --access-token $APIDOG_ACCESS_TOKEN -t <scenario_id> -e <env_id> -r cli
Enter fullscreen mode Exit fullscreen mode

Parámetros principales:

  • -t: ID del escenario de prueba.
  • -e: ID del entorno.
  • -r: reportero. Puedes usar cli, html o junit, separados por comas.

La CLI devuelve resultados de éxito o fallo mediante códigos de salida, por lo que puedes integrarla en una pipeline de CI.

Consulta la guía de instalación de la CLI de Apidog para los detalles de configuración.

Antes de ejecutar un escenario con carga de archivos en CI:

  1. Copia el archivo al runner de CI.
  2. Configura una ruta válida mediante Batch Edit o una variable.
  3. Verifica que el archivo esté dentro de un directorio accesible para el proceso de ejecución.

Para pruebas con datos por fila, consulta las pruebas impulsadas por datos con la CLI de Apidog.

Preguntas frecuentes

¿Por qué mi compañero no puede enviar mi solicitud de carga?

Apidog guarda la ruta local, no el archivo. Si la ruta apunta a tu disco, otro usuario no tendrá acceso a ella. Cada persona debe tener una copia local del archivo y configurar una ruta válida en su entorno.

El mismo comportamiento aplica a pruebas programadas y ejecuciones en Runner.

¿Cómo envío JSON junto con un archivo?

Usa form-data:

  1. Añade el archivo con tipo file.
  2. Añade otro campo con tipo string.
  3. Pega el JSON en ese segundo campo.

El servidor recibirá el archivo y la cadena JSON como partes separadas de la misma solicitud multipart.

¿Qué ruta debo usar en el Runner?

Usa una ruta dentro del directorio montado en el volumen del Runner mediante -v.

Ejemplo:

/opt/runner/yourfile.jpg
Enter fullscreen mode Exit fullscreen mode

Copia el archivo en ese directorio y actualiza el paso mediante Batch Edit. En CLI, una ruta equivalente podría ser:

/opt/apidog/runner/yourfile.jpg
Enter fullscreen mode Exit fullscreen mode

¿Apidog define límites de tamaño o tipos permitidos?

Los límites reales dependen de la API que pruebas. Tu servidor define los tamaños máximos, los tipos MIME permitidos y las reglas de validación.

Añade aserciones para validar las respuestas de archivos demasiado grandes, tipos no permitidos u otros errores de carga.

¿Debo usar form-data o x-www-form-urlencoded?

Usa form-data para archivos. Se asigna a multipart/form-data y permite enviar archivos junto con otros campos.

Usa x-www-form-urlencoded solo para formularios simples con campos escalares y sin archivos.

Conclusión

Para probar cargas de archivos necesitas resolver dos problemas:

  1. Construir correctamente una solicitud multipart/form-data.
  2. Garantizar que el archivo exista en la máquina donde se ejecuta la prueba.

En Apidog, configura el Body como form-data, cambia el campo a tipo file, selecciona el archivo y añade aserciones sobre la respuesta. Para adjuntar metadatos estructurados, envía el JSON en otra parte de tipo string.

Cuando ejecutes el escenario en Runner o CLI, prepara el archivo en ese host y usa Batch Edit o variables de entorno para apuntar a una ruta válida.

¿Quieres probarlo con tu propio endpoint? Descarga Apidog, crea una solicitud form-data para tu ruta de carga y valida la respuesta.

Top comments (0)