Modelado de solicitudes en Postman: parámetros, headers y cuerpos JSON

Construcción consistente de solicitudes para escenarios reales

Modelar una solicitud en Postman no es solo “hacer que funcione”, sino hacerla repetible, legible y fácil de mantener. En la práctica, una request bien modelada define con claridad: qué parámetros acepta, qué headers son obligatorios, cómo luce el body esperado (tipos, campos requeridos, anidamientos) y cómo documentar el uso para que otros puedan ejecutarla sin adivinar.

Checklist de consistencia (antes de enviar)

• Nombre y propósito: el nombre describe acción + recurso + variante (p. ej., Create Order (with items)).
• Parámetros: se distinguen path, query y variables (ambiente/colección).
• Headers: estandarizados y mínimos; evitar duplicados.
• Body: formato correcto (raw JSON, form-data, x-www-form-urlencoded) según el endpoint.
• Validación visual: JSON formateado, sin comas finales, sin comillas mal cerradas.
• Trazabilidad: descripción, ejemplos de payload, notas de validación y supuestos.

Parámetros: path, query y variables (sin mezclar responsabilidades)

1) Path params (parte de la ruta)

Se usan cuando el recurso está identificado en la URL. En Postman, define la ruta con placeholders y asigna valores desde variables.

GET {{baseUrl}}/users/{{userId}}

Buenas prácticas:

• {{baseUrl}} en variables de ambiente (dev/qa/prod).
• {{userId}} como variable de colección o de request si cambia por ejecución.
• Evita “quemar” IDs en la URL; dificulta la reutilización.

2) Query params (filtros, paginación, orden)

Se usan para modificar la consulta sin cambiar el recurso base. En Postman, utiliza la pestaña Params para que se codifiquen correctamente.

GET {{baseUrl}}/orders?status=pending&page=1&pageSize=20&sort=-createdAt

Guía práctica:

Continúa en nuestra aplicación.

• Escuche el audio con la pantalla apagada.
• Obtenga un certificado al finalizar.
• ¡Más de 5000 cursos para que explores!

O continúa leyendo más abajo...

Descargar la aplicación

• Agrega cada parámetro en Params (clave/valor) en lugar de escribirlos manualmente.
• Activa/desactiva parámetros con el checkbox para probar variantes sin borrar valores.
• Usa variables para valores frecuentes: pageSize={{pageSize}}.

3) Variables (ambiente, colección, globales)

Las variables permiten estandarizar endpoints y credenciales sin editar cada request. Recomendación operativa:

• Ambiente: baseUrl, credenciales temporales, tokens, IDs del entorno.
• Colección: constantes del dominio (p. ej., apiVersion).
• Request: valores efímeros o específicos de un caso.

Headers frecuentes: estandarización e implicaciones

Los headers definen cómo se interpreta tu solicitud y qué respuesta esperas. Estandarizarlos reduce errores sutiles (por ejemplo, enviar JSON con un Content-Type incorrecto).

Content-Type

Indica el formato del cuerpo que estás enviando. Implicación: si el servidor espera JSON y envías application/x-www-form-urlencoded, puede interpretar mal el payload o rechazarlo.

• Para JSON: Content-Type: application/json
• Para x-www-form-urlencoded: Content-Type: application/x-www-form-urlencoded
• Para form-data: normalmente Postman gestiona el multipart/form-data (incluye boundary). Evita forzarlo manualmente.

Accept

Indica el formato de respuesta esperado. Implicación: puede afectar negociación de contenido (si el API soporta múltiples formatos).

• Común: Accept: application/json

Authorization

Define el mecanismo de autenticación. Implicación: un token vencido o un esquema incorrecto (Bearer vs otro) produce 401/403 y puede confundirse con errores de endpoint.

Ejemplo típico:

Authorization: Bearer {{token}}

Recomendación en Postman:

• Configura Authorization a nivel de colección (cuando aplique) y hereda en requests.
• Evita duplicar Authorization como header manual si ya está configurado en la pestaña Authorization (puede generar inconsistencias).

Plantilla de headers recomendada

Accept: application/json
Content-Type: application/json
Authorization: Bearer {{token}}

Nota: en requests GET sin body, Content-Type suele ser innecesario; mantenlo solo si tu estándar lo requiere o si el backend lo valida estrictamente.

Diseño de bodies JSON: obligatorios, opcionales, tipos, anidamientos y listas

Un body JSON bien diseñado es explícito: define qué campos son requeridos, cuáles opcionales, qué tipo de dato se espera y cómo se representan estructuras complejas (objetos anidados y arreglos).

Convención práctica: documentar “contrato” del payload

En la descripción de la request (o en la documentación interna de la colección), agrega una mini-especificación:

• Campos obligatorios: marcados como required.
• Campos opcionales: cuándo aplican.
• Tipos: string/number/boolean/object/array.
• Reglas: longitudes, rangos, formatos (email, ISO date).

Ejemplo: crear una orden con items

Supongamos un endpoint:

POST {{baseUrl}}/orders

Body raw JSON (modelo recomendado):

{
  "customerId": "{{customerId}}",
  "currency": "USD",
  "notes": "Entrega en recepción",
  "shippingAddress": {
    "line1": "Av. Principal 123",
    "city": "Lima",
    "country": "PE",
    "postalCode": "15001"
  },
  "items": [
    {
      "sku": "SKU-001",
      "quantity": 2,
      "unitPrice": 19.99
    },
    {
      "sku": "SKU-002",
      "quantity": 1,
      "unitPrice": 5.5
    }
  ],
  "metadata": {
    "source": "postman",
    "campaign": "summer"
  }
}

Errores comunes al modelar JSON (y cómo evitarlos)

• Tipos incorrectos: enviar "quantity": "2" (string) en lugar de número.
• Campos opcionales enviados como null: si el API no acepta null, omite el campo.
• Listas vacías: algunos endpoints requieren mínimo 1 elemento.
• Fechas: estandariza formato (p. ej., ISO 8601: 2026-02-03T10:30:00Z).

Formateador y validación visual: evita errores de sintaxis

Postman ayuda a detectar problemas antes de enviar:

Paso a paso para validar un body JSON

• Ve a Body > raw > selecciona JSON.
• Pega el payload.
• Usa el formateo (pretty) para reindentar y detectar comas o llaves faltantes.
• Verifica que las variables {{...}} estén bien escritas (sin espacios, con el nombre exacto).
• Si el API falla, copia el body enviado real desde la consola de Postman (Postman Console) para confirmar qué se transmitió.

Tip práctico: cuando uses variables dentro de JSON, mantén el tipo correcto. Si una variable representa un número, no la encierres en comillas.

{
  "quantity": {{qty}}
}

Si la variable puede estar vacía, define un valor por defecto en el ambiente o valida antes de enviar.

Comparación de envío de datos: raw JSON vs x-www-form-urlencoded vs form-data

Elegir el tipo de body correcto depende del contrato del endpoint. Postman permite los tres, pero cada uno tiene implicaciones de encoding, archivos y compatibilidad.

Ejemplo 1: raw JSON

POST {{baseUrl}}/users
Accept: application/json
Content-Type: application/json

{
  "email": "ana@correo.com",
  "name": "Ana",
  "roles": ["admin", "billing"]
}

Ejemplo 2: x-www-form-urlencoded

En Postman: Body > x-www-form-urlencoded y agrega claves/valores.

grant_type=client_credentials
client_id={{clientId}}
client_secret={{clientSecret}}
audience={{audience}}

Nota: este formato suele requerir Content-Type: application/x-www-form-urlencoded.

Ejemplo 3: form-data (incluyendo archivos)

En Postman: Body > form-data. Define campos tipo Text y el archivo como File.

file: (File) invoice.pdf
customerId: (Text) {{customerId}}
description: (Text) "Factura de enero"

Recomendaciones:

• No establezcas manualmente Content-Type para multipart; deja que Postman lo genere con el boundary.
• Si el backend espera el campo file con un nombre específico, respétalo exactamente.
• Documenta el tamaño máximo permitido y tipos MIME aceptados si el API los restringe.

Guía paso a paso: modelar una request “lista para equipo”

Paso 1: nombra la request con convención

• Formato sugerido: Action Resource (Variant)
• Ejemplos: Get Orders (paged), Create Order (with items), Upload Invoice (multipart)

Paso 2: define URL con variables

{{baseUrl}}/orders/{{orderId}}

• Evita URLs absolutas por request.
• Centraliza baseUrl en el ambiente.

Paso 3: configura Params (si aplica)

• Agrega page, pageSize, status desde la pestaña Params.
• Usa variables para valores repetidos.

Paso 4: estandariza Authorization

• En la colección: Authorization > Bearer Token > {{token}}.
• En requests específicas, solo sobrescribe si el endpoint usa otro esquema.

Paso 5: aplica headers mínimos

• Accept: application/json
• Content-Type: application/json (solo si hay body JSON)

Paso 6: diseña el body con contrato claro

• Empieza con un ejemplo “válido mínimo” (solo requeridos).
• Luego un ejemplo “completo” (incluye opcionales).
• Usa objetos anidados y arrays de forma explícita.

Ejemplo “válido mínimo”:

{
  "customerId": "{{customerId}}",
  "currency": "USD",
  "shippingAddress": {
    "line1": "Av. Principal 123",
    "city": "Lima",
    "country": "PE",
    "postalCode": "15001"
  },
  "items": [
    { "sku": "SKU-001", "quantity": 1, "unitPrice": 19.99 }
  ]
}

Ejemplo “completo”:

{
  "customerId": "{{customerId}}",
  "currency": "USD",
  "notes": "Dejar en recepción",
  "shippingAddress": {
    "line1": "Av. Principal 123",
    "line2": "Dpto 502",
    "city": "Lima",
    "state": "Lima",
    "country": "PE",
    "postalCode": "15001"
  },
  "items": [
    { "sku": "SKU-001", "quantity": 2, "unitPrice": 19.99 },
    { "sku": "SKU-002", "quantity": 1, "unitPrice": 5.5 }
  ],
  "metadata": { "source": "postman", "priority": "high" }
}

Paso 7: formatea y valida visualmente

• Selecciona raw + JSON.
• Formatea (pretty) y revisa indentación.
• Verifica comillas, comas y llaves.

Prácticas de trazabilidad en la colección (documentación interna)

La trazabilidad convierte una colección en un artefacto de trabajo compartido. En Postman, aprovecha el campo de Description de la request y/o de la carpeta para registrar decisiones y ejemplos.

Qué documentar en cada request

• Propósito: qué hace y qué no hace.
• Precondiciones: variables requeridas ({{token}}, {{customerId}}), permisos necesarios.
• Headers esperados: si hay requisitos estrictos.
• Ejemplos de payload: mínimo y completo.
• Notas de validación: reglas de negocio (p. ej., items[].quantity debe ser entero > 0).
• Casos borde: valores típicos que rompen (strings vacíos, arrays vacíos, nulls).

Plantilla lista para pegar en Description

Purpose:
- Crea una orden con uno o más items.

Preconditions:
- token (Bearer) válido en {{token}}
- customerId válido en {{customerId}}

Headers:
- Accept: application/json
- Content-Type: application/json

Payload (minimal):
{ ... }

Payload (full):
{ ... }

Validation notes:
- items debe tener al menos 1 elemento
- items[].quantity entero > 0
- currency ISO 4217