Formularios form-data y Pruebas de Subida de Archivos
Aprende a probar endpoints de subida de archivos (imágenes, PDFs, adjuntos) en Postman utilizando el formato multipart/form-data y el selector de tipo File.
¿Por qué JSON no es Adecuado para Subir Archivos Pesados?
Aunque JSON es ideal para enviar textos y números, codificar una imagen o un archivo PDF de 15 MB dentro de una cadena Base64 en JSON aumenta el tamaño del archivo en un 33% y satura la memoria del servidor.
El estándar web indiscutible para transferir archivos binarios desde formularios hacia una API es la cabecera:
multipart/form-data
El Secreto de Postman: Cambiar el Campo a Tipo "File"
Muchos desarrolladores novatos se confunden porque intentan escribir la ruta del archivo como texto normal. Para subir un archivo real en Postman:
- Configura tu petición como
POST(ej.https://api.kilopolis.com/v1/usuarios/avatar). - En la pestaña Body, selecciona el botón de opción form-data.
- En la columna Key (Clave), escribe el nombre del campo que espera tu backend (por ejemplo:
avatar). - El Paso Clave: Pasa el cursor sobre el lado derecho de la casilla Key. Aparecerá un menú desplegable sutil que dice Text. Haz clic en él y cámbialo a File (Archivo).
- Al cambiarlo a File, la columna Value (Valor) se transformará en un botón: "Select Files".
- Haz clic en Select Files y elige tu imagen (
.png,.jpg) o PDF desde tu disco duro. - Puedes agregar campos de texto tradicionales en las filas siguientes (por ejemplo:
usuario_id = 15). - Haz clic en Send. Postman dividirá los datos en partes binarias (boundaries) y el backend procesará el archivo como si viniera de un formulario HTML real.
⚡ Recepción de Archivo Multipart en Backend PHP
Código que procesa la petición enviada desde la pestaña form-data de Postman:
<?php
header('Content-Type: application/json; charset=utf-8');
// Verificar que la petición sea POST y contenga un archivo
if ($_SERVER['REQUEST_METHOD'] !== 'POST' || empty($_FILES['avatar'])) {
http_response_code(400);
echo json_encode(['error' => 'Se requiere el archivo avatar en formato form-data']);
exit;
}
$archivo = $_FILES['avatar'];
// Validar tipo MIME
$tiposPermitidos = ['image/jpeg', 'image/png', 'image/webp'];
if (!in_array($archivo['type'], $tiposPermitidos, true)) {
http_response_code(422);
echo json_encode(['error' => 'Formato no admitido. Solo se aceptan imágenes JPG, PNG o WebP']);
exit;
}
// Guardar en directorio de subidas
$nombreDestino = 'avatar_' . time() . '_' . basename($archivo['name']);
$rutaFinal = __DIR__ . '/uploads/' . $nombreDestino;
if (move_uploaded_file($archivo['tmp_name'], $rutaFinal)) {
http_response_code(201);
echo json_encode([
'success' => true,
'mensaje' => 'Archivo subido y procesado exitosamente',
'url' => 'https://api.kilopolis.com/uploads/' . $nombreDestino,
'bytes' => $archivo['size']
]);
} else {
http_response_code(500);
echo json_encode(['error' => 'Error del servidor al escribir el archivo en disco']);
}Mini-Quiz de Retención
Comprueba tu comprensión antes de pasar a la siguiente lección¿Qué ajuste específico debes realizar en la pestaña Body > form-data de Postman para poder seleccionar y adjuntar un archivo físico de tu computadora en lugar de un texto simple?
¿Tienes dudas con este tema?
Sócrates AI puede darte analogías y explicarte este código paso a paso.🚀 ¿Quieres dominar Manual de Postman: Pruebas de APIs REST & Automatización y crear proyectos reales?
Aprende arquitectura limpia, desarrollo web moderno, buenas prácticas y despliegue en producción con nuestro Bootcamp Fullstack Developer con mentorías en vivo.
🏛️ Autoría y Propiedad Intelectual: Obra educativa original de David Amador para Kilopolis Academia (Solucionáticos), estructurada sobre las especificaciones y estándares abiertos del W3C, el estándar vivo de WHATWG y la documentación oficial de código abierto. © Todos los derechos reservados.