Cómo consumir una API REST desde un script CMD de Windows

Introducción: consultar servicios web sin salir de CMD

Un script CMD de Windows puede utilizar curl.exe para realizar solicitudes HTTP y guardar respuestas JSON sin desarrollar una aplicación completa. Es una solución práctica cuando necesitas consultar un servicio corporativo, recuperar un fichero de datos o incorporar una comprobación remota a un proceso que ya funciona con archivos .cmd o .bat.

El reto no consiste solo en obtener una respuesta: una automatización útil debe distinguir un fallo de conexión de un error de la API, conservar la evidencia necesaria y evitar que un fichero antiguo se confunda con una descarga correcta. En esta guía construiremos una llamada sencilla y la convertiremos en un script que devuelve un resultado verificable al sistema que lo ejecuta.

El enfoque se centra deliberadamente en el intérprete de comandos de Windows, sus reglas de sintaxis y su funcionamiento cotidiano. No pretende sustituir a un cliente HTTP especializado ni explicar la arquitectura general de las APIs. Los ejemplos utilizan direcciones api.example.com, que son ilustrativas: debes cambiarlas por puntos de conexión reales para ejecutarlos.

Índice

1. Cuándo resulta útil consumir una API desde CMD
2. Requisitos y comprobaciones iniciales
3. Primera solicitud GET y descarga de JSON
4. Reglas de CMD que afectan a las llamadas
5. Parámetros, cabeceras y autenticación
6. Diferencia entre errores de curl y estados HTTP
7. Script CMD completo con controles de errores
8. Enviar JSON mediante POST
9. Seguridad, reintentos y mantenimiento
10. Ejecución programada y límites de CMD
11. Lista de comprobación y preguntas frecuentes

Cuándo tiene sentido consumir una API REST con un archivo .cmd o .bat

Muchas organizaciones mantienen pequeños procesos en CMD: copiar un fichero antes de abrir un programa, comprobar la disponibilidad de una aplicación o lanzar una tarea de mantenimiento. Cuando un servicio proporciona una API HTTP, una de esas tareas puede incorporar una consulta remota sin tener que cambiar toda la operativa.

Entre los casos concretos están comprobar el estado de un sistema antes de importar datos, descargar un catálogo que se utilizará posteriormente o enviar a un servicio interno una solicitud sencilla. Por ejemplo, un equipo administrativo puede recibir cada mañana un archivo JSON con el estado de determinados pedidos, mientras que la validación y el tratamiento de esos datos se realizan en otra aplicación.

La ventaja principal es la integración con tareas de Windows ya existentes. CMD puede ejecutar programas, comprobar códigos de salida, organizar carpetas y encadenar operaciones. Sin embargo, no dispone de un analizador JSON nativo cómodo ni de estructuras modernas para construir clientes HTTP complejos. Para manejar respuestas extensas, paginación o autenticaciones sofisticadas conviene evaluar otras herramientas.

Antes de automatizar, define qué representa un resultado correcto: no es lo mismo que el servidor responda que comprobar que el dato recibido corresponde a la fecha, identidad y operación esperadas. Este criterio evita trasladar errores silenciosos al resto del proceso.

Requisitos para llamar a una API desde Windows

En las versiones modernas de Windows 10 y en Windows 11 suele estar disponible curl.exe. Abre el Símbolo del sistema y comprueba que existe y qué versión tienes instalada:

where curl.exe
curl.exe --version

Si Windows informa de que no reconoce el comando, verifica la instalación y la variable PATH antes de continuar. Usa expresamente curl.exe en los ejemplos para identificar el ejecutable; así no dependes de alias de otras consolas, como el que existe para curl en algunas versiones de PowerShell.

Además, necesitas la URL del endpoint, el método HTTP admitido, el tipo de respuesta esperado y, si la API no es pública, una identidad autorizada. Consulta la documentación del servicio para conocer los permisos, la caducidad de credenciales y los límites de uso. No presupongas que todas las APIs devuelven JSON ni que un endpoint admite cualquier método.

Para seguir la guía puedes crear una carpeta de trabajo, por ejemplo C:\Integraciones\Inventario, y guardar allí tus archivos .cmd. Los ejemplos que usan %~dp0 depositarán sus resultados en la carpeta donde esté ubicado el script, independientemente del directorio desde el que se invoque.

Primera solicitud GET: leer la respuesta de una API

Una petición GET recupera un recurso. Si la API permite consultarlo y no exige autenticación, la llamada más simple puede realizarse así:

curl.exe --silent --show-error ^
  --header "Accept: application/json" ^
  "https://api.example.com/v1/inventario"

curl.exe solicita la URL; --header indica que preferimos una respuesta JSON mediante la cabecera Accept; --silent oculta la barra de progreso, mientras que --show-error permite seguir viendo errores de la herramienta. La respuesta se escribe en la consola.

Para utilizar los datos en otro paso, es preferible guardarlos en un archivo. El siguiente ejemplo contiene la estructura mínima de un fichero consultar-inventario.cmd:

@echo off
setlocal EnableExtensions DisableDelayedExpansion

set "URL=https://api.example.com/v1/inventario"
set "FICHERO=%~dp0inventario.json"

curl.exe --silent --show-error ^
  --header "Accept: application/json" ^
  --output "%FICHERO%" ^
  "%URL%"

if errorlevel 1 (
  echo ERROR: la solicitud no pudo completarse.
  exit /b 1
)

echo Solicitud ejecutada. Revise el estado HTTP antes de usar los datos.
exit /b 0

La combinación --output y %~dp0 permite guardar el contenido sin depender del directorio actual. if errorlevel 1 detecta un código de salida distinto de cero. Este primer script es didáctico, no un control de éxito HTTP completo: curl puede terminar con código cero aunque el servidor haya respondido 404 o 500. Resolveremos esa diferencia más adelante.

Las reglas de CMD que más errores provocan

Continuación de líneas con el carácter ^

En un archivo .cmd, el acento circunflejo ^ permite continuar una orden en la línea siguiente. Debe quedar como último carácter de la línea: un espacio después de ^ puede romper la continuación. No copies sin adaptar ejemplos escritos para Bash, que suelen utilizar \, ni ejemplos de PowerShell que emplean otras reglas de continuación.

Comillas, espacios y caracteres especiales

Escribe las rutas entre comillas dobles, especialmente si contienen espacios. Aplica el mismo criterio a las URLs. En CMD, & separa comandos si no está correctamente protegido; por eso una URL con varios parámetros puede producir un comportamiento inesperado cuando se omiten las comillas.

La forma set "VARIABLE=valor" evita incorporar espacios accidentales al final del valor. Las variables del entorno se expanden mediante %VARIABLE%; en cambio, %~dp0 representa la unidad y carpeta del fichero por lotes que se está ejecutando.

Por qué aparece %%{http_code} en un .cmd

La opción de curl --write-out admite variables propias, como %{http_code}, para informar del estado HTTP. Dentro de un archivo por lotes debes duplicar el signo de porcentaje: %%{http_code}. De no hacerlo, CMD puede interpretar de forma incorrecta la expresión. Esta regla se aplica al archivo .cmd y no debe copiarse sin más a otras consolas.

También hay que recordar que %%F representa una variable de un bucle for dentro de un archivo por lotes, mientras que un comando interactivo de CMD utilizaría %F. Son dos usos distintos del signo de porcentaje y confundirlos produce errores frecuentes.

Parámetros de consulta, cabeceras y autenticación

Enviar filtros y parámetros sin construir una URL a mano

Cuando un endpoint admite filtros, curl permite incorporarlos como parámetros de consulta utilizando --get y --data-urlencode. Esto resulta especialmente útil cuando los valores contienen espacios o caracteres que necesitan codificación:

curl.exe --silent --show-error --get ^
  --data-urlencode "estado=pendiente" ^
  --data-urlencode "pagina=2" ^
  "https://api.example.com/v1/pedidos"

La API recibirá una consulta con los parámetros estado y pagina. Debes utilizar exactamente los nombres y valores definidos por su contrato; son ficticios en este ejemplo. Evita colocar contraseñas o tokens en la URL, ya que pueden acabar almacenados en registros, historiales y sistemas intermedios.

Pasar un token Bearer por una cabecera

Si el servicio exige un token Bearer, suele enviarse mediante Authorization. El siguiente fragmento presupone que un mecanismo autorizado ya ha establecido la variable de entorno API_TOKEN; no inventa ni obtiene una credencial:

@echo off
setlocal EnableExtensions DisableDelayedExpansion

if not defined API_TOKEN (
  echo ERROR: la variable API_TOKEN no esta definida.
  exit /b 2
)

curl.exe --silent --show-error ^
  --header "Accept: application/json" ^
  --header "Authorization: Bearer %API_TOKEN%" ^
  --output "%~dp0respuesta.json" ^
  "https://api.example.com/v1/inventario"

exit /b %ERRORLEVEL%

Este ejemplo sirve para mostrar la cabecera, pero su comprobación final sigue siendo básica: devuelve el estado del proceso curl, no verifica por separado el código HTTP. Para una ejecución periódica, combina la autenticación con el control completo de estados de la siguiente sección.

Una variable de entorno no es una caja fuerte. El token puede quedar expuesto a procesos con permisos suficientes o aparecer en los argumentos del proceso curl. No lo escribas literalmente en un archivo distribuido a varias personas, no lo imprimas con echo y no actives trazas detalladas que registren cabeceras sensibles. Cuando el entorno necesite protección reforzada, valora un gestor de secretos y un método de acceso que reduzca la exposición en la línea de comandos.

Cómo distinguir el error del ejecutable del resultado HTTP

En una llamada a una API intervienen al menos dos resultados independientes. El primero es el código de salida de curl, que permite identificar problemas como fallos de DNS, certificados, conexión o tiempo de espera. El segundo es el código de estado HTTP devuelto por el servidor. Una petición puede completarse técnicamente y, aun así, recibir una respuesta que la aplicación no puede utilizar.

• 200: la petición se ha atendido correctamente; aún debes comprobar el contenido y su significado.
• 201: normalmente indica que se ha creado un recurso, habitual tras determinadas operaciones POST.
• 204: éxito sin contenido de respuesta; no debes exigir un fichero JSON con datos.
• 400: la solicitud no cumple lo que espera el servidor.
• 401 o 403: conviene comprobar credenciales, permisos y el contexto de autorización, sin asumir que ambos códigos significan lo mismo.
• 404: el recurso solicitado no está disponible en esa ruta o contexto.
• 429: es posible que se hayan alcanzado límites de solicitudes.
• 500, 502 o 503: el servidor o un componente intermedio ha sufrido un problema al atender la petición.

Si una integración falla, conviene diferenciar la incidencia de transporte del contrato HTTP antes de modificar código o credenciales. En el artículo cómo detectar errores habituales al consumir APIs se desarrolla esa investigación desde una perspectiva más amplia; aquí nos centraremos en cómo traducir el resultado a una salida útil para CMD.

Ejemplo completo: script CMD que descarga JSON y comprueba el resultado

El siguiente fichero consultar-inventario.cmd incorpora controles apropiados para una lectura periódica sencilla: verifica que curl existe, prepara una carpeta de salida, elimina resultados anteriores, limita los tiempos de espera, guarda por separado cuerpo, estado HTTP y errores de transporte, y devuelve códigos de salida diferentes según el fallo.

@echo off
setlocal EnableExtensions DisableDelayedExpansion

rem Ajustar esta URL a la API real y autorizada.
set "URL=https://api.example.com/v1/inventario"
set "SALIDA=%~dp0salida"
set "CUERPO=%SALIDA%\inventario.json"
set "ESTADO_ARCHIVO=%SALIDA%\estado-http.txt"
set "ERRORES=%SALIDA%\curl-errores.txt"

where curl.exe >nul 2>&1
if errorlevel 1 (
  echo ERROR: curl.exe no esta disponible.
  exit /b 10
)

if not exist "%SALIDA%" mkdir "%SALIDA%"
if not exist "%SALIDA%" (
  echo ERROR: no se pudo crear la carpeta de salida.
  exit /b 11
)

rem Impedir que una respuesta anterior parezca nueva.
del /q "%CUERPO%" "%ESTADO_ARCHIVO%" "%ERRORES%" 2>nul

curl.exe --silent --show-error ^
  --connect-timeout 10 --max-time 45 ^
  --header "Accept: application/json" ^
  --output "%CUERPO%" ^
  --write-out "%%{http_code}" ^
  "%URL%" > "%ESTADO_ARCHIVO%" 2> "%ERRORES%"

set "RESULTADO_CURL=%ERRORLEVEL%"
if not "%RESULTADO_CURL%"=="0" (
  echo ERROR de transporte. Codigo curl: %RESULTADO_CURL%.
  if exist "%ERRORES%" type "%ERRORES%"
  exit /b 20
)

set "HTTP_STATUS="
set /p "HTTP_STATUS="<"%ESTADO_ARCHIVO%"

if not "%HTTP_STATUS:~0,1%"=="2" (
  echo ERROR: la API devolvio HTTP %HTTP_STATUS%.
  exit /b 21
)

if "%HTTP_STATUS%"=="204" (
  echo OK: HTTP 204, operacion sin cuerpo de respuesta.
  exit /b 0
)

if not exist "%CUERPO%" (
  echo ERROR: no existe el archivo de respuesta.
  exit /b 22
)

for %%F in ("%CUERPO%") do if %%~zF EQU 0 (
  echo ERROR: el archivo de respuesta esta vacio.
  exit /b 23
)

echo OK: HTTP %HTTP_STATUS%. Archivo: "%CUERPO%"
exit /b 0

El endpoint del ejemplo es ficticio y debe sustituirse antes de ejecutar el fichero. El código está planteado para un GET de una API que normalmente devuelve datos cuando responde con éxito. El estado 204 se trata expresamente como una operación correcta sin cuerpo; para cualquier otra respuesta 2xx, el script comprueba que el archivo exista y no esté vacío.

Qué significan las comprobaciones

• where curl.exe permite fallar de manera explícita si no está instalado el ejecutable.
• --connect-timeout 10 limita la fase de conexión y --max-time 45 establece un límite temporal total por transferencia.
• --output guarda el cuerpo de la respuesta, aunque corresponda a un error HTTP. Por eso no se procesa hasta comprobar el estado.
• --write-out "%%{http_code}" escribe el código de estado en un archivo independiente para que CMD pueda leerlo.
• 2> "%ERRORES%" separa los mensajes de error de curl del cuerpo recibido.
• exit /b entrega al proceso llamante un código de salida que puede comprobar un programador de tareas u otro script.

El archivo inventario.json no debe darse por validado únicamente porque tenga contenido. Podría contener una estructura inesperada o datos de otro periodo. Antes de cargarlo en un sistema empresarial, hay que validar su estructura, el tipo de contenido y los campos esenciales con una herramienta adecuada. CMD no ofrece, por sí solo, un analizador JSON con garantías.

El ejemplo elimina la respuesta anterior antes de hacer una nueva consulta para impedir que una ejecución fallida deje un éxito aparente. En procesos que no pueden perder el resultado anterior, una alternativa más segura es descargar a un archivo temporal, validarlo y solo entonces sustituir de forma controlada el fichero de producción.

Cómo enviar datos JSON a una API mediante POST desde CMD

Para crear o comunicar información a un servicio es habitual utilizar POST, siempre que así lo establezca su documentación. En CMD, escribir un JSON complejo directamente entre comillas suele generar problemas de escape. Una solución más legible consiste en guardar el cuerpo de la petición en un archivo separado.

1. Preparar el archivo peticion.json

Guarda este contenido de ejemplo como peticion.json en la misma carpeta del script, con la codificación de caracteres que exija la API; normalmente se utilizará UTF-8:

{
  "referencia": "SOL-2026-0042",
  "cantidad": 3,
  "comentario": "Solicitud de prueba"
}

2. Ejecutar la solicitud

@echo off
setlocal EnableExtensions DisableDelayedExpansion

curl.exe --silent --show-error ^
  --request POST ^
  --header "Content-Type: application/json; charset=utf-8" ^
  --header "Accept: application/json" ^
  --data-binary "@%~dp0peticion.json" ^
  --output "%~dp0respuesta-creacion.json" ^
  "https://api.example.com/v1/solicitudes"

exit /b %ERRORLEVEL%

--request POST establece el método; Content-Type identifica el formato enviado; --data-binary "@archivo" transmite los bytes del fichero sin reformatear su contenido. El nombre respuesta-creacion.json indica dónde se guardará el cuerpo devuelto, si existe.

Este fragmento no constituye una validación completa de la operación. Para producción, adapta el control de estado del ejemplo anterior: comprueba el código de salida de curl y el código HTTP que el contrato del servicio considere correcto, por ejemplo 201. Algunos servicios responden sin cuerpo, otros incluyen información del recurso creado. No supongas que todos se comportan igual.

Un POST puede tener efectos de negocio. Si la conexión se interrumpe después de que el servidor haya procesado la solicitud, repetirla sin comprobaciones podría generar un duplicado. Utiliza identificadores de operación o mecanismos de idempotencia cuando el servicio los ofrezca. El tratamiento detallado del contenido JSON merece una atención propia, distinta de la mecánica de ejecución del archivo CMD.

Seguridad y fiabilidad al automatizar llamadas desde CMD

Conservar la verificación HTTPS

Utiliza endpoints HTTPS y mantén la verificación del certificado del servidor. Si aparece un error TLS, investiga certificados, nombres de servidor, proxy y almacenes de confianza. No conviertas --insecure en una solución permanente: ocultaría una comprobación esencial de autenticidad del servidor.

Aplicar tiempos de espera y reintentos con criterio

Una tarea que funciona sin supervisión no debería permanecer bloqueada indefinidamente. Establece límites de conexión y de tiempo total acordes con la operación. Para consultas GET que pueden repetirse sin efectos secundarios, curl permite introducir reintentos ante determinadas incidencias transitorias:

curl.exe --silent --show-error ^
  --retry 2 --retry-delay 3 ^
  --connect-timeout 10 --max-time 45 ^
  --output "%~dp0respuesta.json" ^
  "https://api.example.com/v1/inventario"

En este fragmento se permiten dos reintentos adicionales a la primera ejecución cuando curl identifica condiciones recuperables; no significa repetir automáticamente cualquier fallo. Los reintentos también consumen tiempo y cuota. No copies esta estrategia a operaciones que crean pedidos, realizan cargos o cambian estados sin estudiar previamente su idempotencia y sus condiciones de recuperación.

Si el servicio publica límites de solicitudes o exige respetar Retry-After, diseña el consumo conforme a su contrato. Puedes ampliar este punto en cómo controlar límites de uso y cuotas de una API.

Guardar registros útiles sin exponer datos

El script debe permitir saber cuándo se ejecutó, a qué operación lógica correspondía y qué resultado devolvió, pero no necesita conservar tokens, cabeceras de autorización ni datos personales completos. Restringe los permisos de lectura de la carpeta donde se guardan las respuestas, configura una política de retención y evita que los nombres de fichero revelen información sensible.

Si varios procesos llaman a servicios remotos, conviene mantener criterios homogéneos de registro, correlación y tratamiento de fallos. La perspectiva general se desarrolla en cómo registrar todas las llamadas realizadas a una API; un archivo de errores aislado, como el del ejemplo, no equivale a una solución centralizada de auditoría.

Evitar ejecuciones simultáneas sobre el mismo archivo

Dos tareas que escriben a la vez en inventario.json pueden pisarse los resultados. Si la integración admite concurrencia, asigna un directorio o identificador de ejecución distinto, y aplica una publicación controlada del resultado validado. Cuando el proceso deba ejecutarse de uno en uno, configura esa restricción en el programador o añade un mecanismo de bloqueo adecuado.

Ejecutar la consulta automáticamente con el Programador de tareas

Una vez que el archivo .cmd funciona manualmente, puedes programarlo en el Programador de tareas de Windows. Configura una acción que ejecute cmd.exe y utiliza como argumento la llamada al fichero, por ejemplo:

cmd.exe /d /c "C:\Integraciones\consultar-inventario.cmd"

En un entorno real, establece la ruta exacta al archivo, utiliza una cuenta con los permisos mínimos necesarios y revisa las condiciones de ejecución, el directorio de trabajo y el acceso de esa cuenta a las credenciales. No supongas que la cuenta que ejecuta una tarea programada tiene las mismas variables de entorno, unidades de red o permisos que tu sesión interactiva.

Prueba el script desde la misma identidad con la que se programará y verifica qué ocurre si no hay conexión, si el servidor responde con error y si ya existe una ejecución anterior. Observa asimismo el último resultado de la tarea y los ficheros de salida. Programar un comando no implica que el dato obtenido sea correcto: el tratamiento posterior debe quedar condicionado al éxito comprobado de la operación.

Cuándo conviene dejar de utilizar CMD

CMD es adecuado para orquestar herramientas existentes y realizar transferencias sencillas. Empieza a resultar poco práctico cuando necesitas analizar arreglos y objetos JSON anidados, renovar tokens automáticamente, gestionar paginación compleja, controlar concurrencia o construir peticiones dinámicas con muchos campos.

Si esos requisitos aparecen, puede ser más conveniente adoptar un lenguaje con bibliotecas HTTP y JSON o desarrollar un cliente estructurado. No es una derrota del enfoque inicial: es reconocer cuándo la complejidad deja de estar en el lanzamiento del comando y pasa al procesamiento de los datos.

Si el número de servicios aumenta, conviene separar parámetros y comportamientos comunes en lugar de copiar decenas de archivos casi idénticos. Esa evolución se explica en cómo diseñar scripts reutilizables para consumir múltiples APIs, sin convertir esta guía específica de CMD en una arquitectura completa de integración.

Comprobaciones antes de utilizar el script con información real

Antes de dejar una integración funcionando sin supervisión, ejecuta una pequeña batería de pruebas controladas. No basta con que el comando haya funcionado una vez desde tu escritorio.

1. Consulta correcta: el cuerpo se descarga, el estado coincide con lo previsto y el proceso devuelve cero.
2. Endpoint inexistente: una respuesta 404 no se considera un éxito operativo.
3. Credencial incorrecta: el script distingue un fallo de autorización y no imprime secretos.
4. Fallo de conexión o certificado: el código de salida indica el error y no se reutilizan archivos antiguos.
5. Respuesta vacía o estructura inválida: el siguiente paso no consume datos sin validar.
6. Ejecución programada: la cuenta de servicio tiene acceso al ejecutable, a la red y a las carpetas autorizadas.
7. Repetición de la tarea: volver a ejecutarla no provoca duplicados ni efectos no deseados.

Las pruebas deben utilizar un entorno de desarrollo o pruebas si la API modifica información. Realizar un POST de demostración contra producción puede crear registros verdaderos aunque el JSON contenga nombres aparentemente ficticios.

Preguntas frecuentes sobre APIs REST desde CMD

Conclusión: una llamada sencilla necesita controles claros

Consumir una API REST desde un script CMD de Windows es perfectamente viable con curl.exe cuando el objetivo está acotado: hacer una consulta, enviar un fichero JSON o incorporar una operación HTTP a un procedimiento existente. Su utilidad depende menos del número de comandos que de la claridad con la que se comprueban los resultados.

La práctica decisiva es separar transporte, respuesta HTTP y validación de datos. Si además se limitan los tiempos de espera, se protegen las credenciales, se evitan resultados antiguos y se devuelve un código de salida comprensible, un archivo por lotes puede convertirse en una pieza útil de la operativa diaria, sin atribuirle capacidades de análisis que no tiene.